diff options
Diffstat (limited to 'doc/bashref.info')
| -rw-r--r-- | doc/bashref.info | 10348 |
1 files changed, 10348 insertions, 0 deletions
diff --git a/doc/bashref.info b/doc/bashref.info new file mode 100644 index 0000000..189e58b --- /dev/null +++ b/doc/bashref.info @@ -0,0 +1,10348 @@ +This is bashref.info, produced by makeinfo version 4.13 from +/Users/chet/src/bash/src/doc/bashref.texi. + +This text is a brief description of the features that are present in +the Bash shell (version 4.1, 23 December 2009). + + This is Edition 4.1, last updated 23 December 2009, of `The GNU Bash +Reference Manual', for `Bash', Version 4.1. + + Copyright (C) 1988-2009 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.3 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 are free to copy and modify + this GNU manual. Buying copies from GNU Press supports the FSF in + developing GNU and promoting software freedom." + + +INFO-DIR-SECTION Basics +START-INFO-DIR-ENTRY +* Bash: (bash). The GNU Bourne-Again SHell. +END-INFO-DIR-ENTRY + + +File: bashref.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Bash Features +************* + +This text is a brief description of the features that are present in +the Bash shell (version 4.1, 23 December 2009). + + This is Edition 4.1, last updated 23 December 2009, of `The GNU Bash +Reference Manual', for `Bash', Version 4.1. + + Bash contains features that appear in other popular shells, and some +features that only appear in Bash. Some of the shells that Bash has +borrowed concepts from are the Bourne Shell (`sh'), the Korn Shell +(`ksh'), and the C-shell (`csh' and its successor, `tcsh'). The +following menu breaks the features up into categories based upon which +one of these other shells inspired the feature. + + This manual is meant as a brief introduction to features found in +Bash. The Bash manual page should be used as the definitive reference +on shell behavior. + +* Menu: + +* Introduction:: An introduction to the shell. +* Definitions:: Some definitions used in the rest of this + manual. +* Basic Shell Features:: The shell "building blocks". +* Shell Builtin Commands:: Commands that are a part of the shell. +* Shell Variables:: Variables used or set by Bash. +* Bash Features:: Features found only in Bash. +* Job Control:: What job control is and how Bash allows you + to use it. +* Command Line Editing:: Chapter describing the command line + editing features. +* Using History Interactively:: Command History Expansion +* Installing Bash:: How to build and install Bash on your system. +* Reporting Bugs:: How to report bugs in Bash. +* Major Differences From The Bourne Shell:: A terse list of the differences + between Bash and historical + versions of /bin/sh. +* GNU Free Documentation License:: Copying and sharing this documentation. +* Indexes:: Various indexes for this manual. + + +File: bashref.info, Node: Introduction, Next: Definitions, Prev: Top, Up: Top + +1 Introduction +************** + +* Menu: + +* What is Bash?:: A short description of Bash. +* What is a shell?:: A brief introduction to shells. + + +File: bashref.info, Node: What is Bash?, Next: What is a shell?, Up: 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 `sh', which appeared in the Seventh Edition Bell +Labs Research version of Unix. + + Bash is largely compatible with `sh' and incorporates useful +features from the Korn shell `ksh' and the C shell `csh'. It is +intended to be a conformant implementation of the IEEE POSIX Shell and +Tools portion of the IEEE POSIX specification (IEEE Standard 1003.1). +It offers functional improvements over `sh' for both interactive and +programming use. + + While the GNU operating system provides other shells, including a +version of `csh', 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. + + +File: bashref.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction + +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 command interpreter and a programming +language. As a command interpreter, the shell provides the user +interface to the rich set of GNU utilities. The programming language +features allow these utilities to be combined. Files containing +commands can be created, and become commands themselves. These new +commands have the same status as system commands in directories such as +`/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 from 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; asynchronous 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 functionality 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. + + 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 programming language. These interactive features +include job control, command line editing, command history and aliases. +Each of these features is described in this manual. + + +File: bashref.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top + +2 Definitions +************* + +These definitions are used throughout the remainder of this manual. + +`POSIX' + A family of open system standards based on Unix. Bash is + primarily concerned with the Shell and Utilities portion of the + POSIX 1003.1 standard. + +`blank' + A space or tab character. + +`builtin' + A command that is implemented internally by the shell itself, + rather than by an executable program somewhere in the file system. + +`control operator' + A `token' that performs a control function. It is a `newline' or + one of the following: `||', `&&', `&', `;', `;;', `|', `|&', `(', + or `)'. + +`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. + +`job' + 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: `|', `&', `;', + `(', `)', `<', or `>'. + +`name' + A `word' consisting solely of letters, numbers, and underscores, + and beginning with a letter or underscore. `Name's are used as + shell variable and function names. Also referred to as an + `identifier'. + +`operator' + A `control operator' or a `redirection operator'. *Note + Redirections::, for a list of redirection operators. Operators + contain at least one unquoted `metacharacter'. + +`process group' + A collection of related processes each having the same process + group ID. + +`process group ID' + A unique identifier 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'. + +`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 standard. + +`token' + A sequence of characters considered a single unit by the shell. + It is either a `word' or an `operator'. + +`word' + A sequence of characters treated as a unit by the shell. Words + may not include unquoted `metacharacters'. + + +File: bashref.info, Node: Basic Shell Features, Next: Shell Builtin Commands, Prev: Definitions, Up: Top + +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 specification for the +`standard' Unix shell. + + This chapter briefly summarizes the shell's `building blocks': +commands, control structures, 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. + +* Menu: + +* Shell Syntax:: What your input means to the shell. +* Shell Commands:: The types of commands you can use. +* Shell Functions:: Grouping commands by name. +* Shell Parameters:: How the shell stores values. +* Shell Expansions:: How Bash expands parameters and the various + expansions available. +* Redirections:: A way to control where input and output go. +* Executing Commands:: What happens when you run a command. +* Shell Scripts:: Executing files of shell commands. + + +File: bashref.info, Node: Shell Syntax, Next: Shell Commands, Up: Basic Shell Features + +3.1 Shell Syntax +================ + +* Menu: + +* Shell Operation:: The basic operation of the shell. +* Quoting:: How to remove the special meaning from characters. +* Comments:: How to specify comments. + + When the shell reads input, it proceeds through a sequence of +operations. If the input indicates the beginning of a comment, the +shell ignores the comment symbol (`#'), 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. + + +File: bashref.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax + +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 (*note Shell Scripts::), from a string + supplied as an argument to the `-c' invocation option (*note + Invoking Bash::), or from the user's terminal. + + 2. Breaks the input into words and operators, obeying the quoting + rules described in *note Quoting::. These tokens are separated by + `metacharacters'. Alias expansion is performed by this step + (*note Aliases::). + + 3. Parses the tokens into simple and compound commands (*note Shell + Commands::). + + 4. Performs the various shell expansions (*note Shell Expansions::), + breaking the expanded tokens into lists of filenames (*note + Filename Expansion::) and commands and arguments. + + 5. Performs any necessary redirections (*note Redirections::) and + removes the redirection operators and their operands from the + argument list. + + 6. Executes the command (*note Executing Commands::). + + 7. Optionally waits for the command to complete and collects its exit + status (*note Exit Status::). + + + +File: bashref.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax + +3.1.2 Quoting +------------- + +* Menu: + +* Escape Character:: How to remove the special meaning from a single + character. +* Single Quotes:: How to inhibit all interpretation of a sequence + of characters. +* Double Quotes:: How to suppress most of the interpretation of a + sequence of characters. +* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. +* Locale Translation:: How to translate strings into different languages. + + 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 (*note Definitions::) 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 (*note +History Interaction::), the HISTORY EXPANSION character, usually `!', +must be quoted to prevent history expansion. *Note Bash History +Facilities::, for more details concerning history expansion. + + There are three quoting mechanisms: the ESCAPE CHARACTER, single +quotes, and double quotes. + + +File: bashref.info, Node: Escape Character, Next: Single Quotes, Up: Quoting + +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). + + +File: bashref.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting + +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. + + +File: bashref.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting + +3.1.2.3 Double Quotes +..................... + +Enclosing characters in double quotes (`"') preserves the literal value +of all characters within the quotes, with the exception of `$', ``', +`\', and, when history expansion is enabled, `!'. The characters `$' +and ``' retain their special meaning within double quotes (*note Shell +Expansions::). The backslash retains its special meaning only when +followed by one of the following characters: `$', ``', `"', `\', 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 (*note Shell Parameter Expansion::). + + +File: bashref.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting + +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: + +`\a' + alert (bell) + +`\b' + backspace + +`\e' +`\E' + an escape character (not ANSI C) + +`\f' + form feed + +`\n' + newline + +`\r' + carriage return + +`\t' + horizontal tab + +`\v' + vertical tab + +`\\' + backslash + +`\'' + single quote + +`\"' + double 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. + + +File: bashref.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting + +3.1.2.5 Locale-Specific Translation +................................... + +A double-quoted string preceded by a dollar sign (`$') will cause the +string to be translated 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_MESSAGES/`TEXTDOMAIN'.mo. + + +File: bashref.info, Node: Comments, Prev: Quoting, Up: Shell Syntax + +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 (*note +The Shopt Builtin::), 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. *Note Interactive Shells::, for a description of +what makes a shell interactive. + + +File: bashref.info, Node: Shell Commands, Next: Shell Functions, Prev: Shell Syntax, Up: Basic Shell Features + +3.2 Shell Commands +================== + +A simple shell command such as `echo a b c' 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. + +* Menu: + +* Simple Commands:: The most common type of command. +* Pipelines:: Connecting the input and output of several + commands. +* Lists:: How to execute commands sequentially. +* Compound Commands:: Shell commands for control flow. +* Coprocesses:: Two-way communication between commands. + + +File: bashref.info, Node: Simple Commands, Next: Pipelines, Up: Shell Commands + +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 `blank's, terminated by one of +the shell's control operators (*note Definitions::). The first word +generally specifies a command to be executed, with the rest of the +words being that command's arguments. + + The return status (*note Exit Status::) 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. + + +File: bashref.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Shell Commands + +3.2.2 Pipelines +--------------- + +A `pipeline' is a sequence of simple commands separated by one of the +control operators `|' or `|&'. + + The format for a pipeline is + [`time' [`-p']] [`!'] COMMAND1 [ [`|' or `|&'] 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. This connection is performed before any +redirections specified by the command. + + If `|&' is used, the standard error of COMMAND1 is connected to +COMMAND2's standard input through the pipe; it is shorthand for `2>&1 +|'. This implicit redirection of the standard error is performed after +any redirections specified by the command. + + 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. +*Note Bash Variables::, for a description of the available formats. +The use of `time' as a reserved word permits the timing of shell +builtins, shell functions, and pipelines. An external `time' command +cannot time these easily. + + If the pipeline is not executed asynchronously (*note Lists::), the +shell waits for all commands in the pipeline to complete. + + Each command in a pipeline is executed in its own subshell (*note +Command Execution Environment::). The exit status of a pipeline is the +exit status of the last command in the pipeline, unless the `pipefail' +option is enabled (*note The Set Builtin::). 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. + + +File: bashref.info, Node: Lists, Next: Compound Commands, Prev: Pipelines, Up: Shell Commands + +3.2.3 Lists of Commands +----------------------- + +A `list' is a sequence of one or more pipelines separated by one of the +operators `;', `&', `&&', or `||', and optionally terminated by one of +`;', `&', or a `newline'. + + Of these list operators, `&&' and `||' have equal precedence, +followed by `;' and `&', which have equal precedence. + + A sequence of one or more newlines may appear in a `list' to delimit +commands, equivalent 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 (*note Job Control::), 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 command to terminate in turn. The return status is the +exit status of the last command executed. + + AND and OR lists are sequences of one or more pipelines separated by +the control operators `&&' and `||', respectively. AND and OR lists +are executed with left associativity. + + An AND list has the form + COMMAND1 && COMMAND2 + +COMMAND2 is executed if, and only if, COMMAND1 returns an exit status +of zero. + + An OR list has the form + COMMAND1 || COMMAND2 + +COMMAND2 is executed if, and only if, COMMAND1 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. + + +File: bashref.info, Node: Compound Commands, Next: Coprocesses, Prev: Lists, Up: Shell Commands + +3.2.4 Compound Commands +----------------------- + +* Menu: + +* Looping Constructs:: Shell commands for iterative action. +* Conditional Constructs:: Shell commands for conditional execution. +* Command Grouping:: Ways to group commands. + + Compound commands 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 (*note Redirections::) associated with a compound command +apply to all commands within that compound command unless explicitly +overridden. + + Bash provides looping constructs, conditional commands, and +mechanisms to group commands and execute them as a unit. + + +File: bashref.info, Node: Looping Constructs, Next: Conditional Constructs, Up: Compound Commands + +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: + 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 "$@"' + had been specified (*note Special Parameters::). 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 (( EXPR1 ; EXPR2 ; EXPR3 )) ; do COMMANDS ; done + First, the arithmetic expression EXPR1 is evaluated according to + the rules described below (*note Shell Arithmetic::). 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 arithmetic 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 (*note Bourne Shell Builtins::) +may be used to control loop execution. + + +File: bashref.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Compound Commands + +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 `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 [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... esac' + + `case' will selectively execute the COMMAND-LIST corresponding to + the first PATTERN that matches WORD. If the shell option + `nocasematch' (see the description of `shopt' in *note The Shopt + Builtin::) is enabled, the match is performed without regard to + the case of alphabetic characters. The `|' 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 `;;', `;&', or `;;&'. The + WORD undergoes tilde expansion, parameter expansion, command + substitution, arithmetic expansion, and quote removal before + 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 `;;', `;&', or `;;&'. 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 | dog | cat) echo -n "four";; + man | kangaroo ) echo -n "two";; + *) echo -n "an unknown number of";; + esac + echo " legs." + + If the `;;' operator is used, no subsequent matches are attempted + after the first pattern match. Using `;&' in place of `;;' + causes execution to continue with the COMMAND-LIST associated with + the next clause, if any. Using `;;&' in place of `;;' causes the + shell to test the patterns in the next clause, if any, and execute + any associated COMMAND-LIST on a successful match. + + 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 number. If the `in WORDS' is + omitted, the positional parameters are printed, as if `in "$@"' + had been specified. 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'. + + 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 $fname \($REPLY\) + break; + done + +`((...))' + (( EXPRESSION )) + + The arithmetic EXPRESSION is evaluated according to the rules + described below (*note Shell Arithmetic::). 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" + *Note Bash Builtins::, for a full description of the `let' builtin. + +`[[...]]' + [[ EXPRESSION ]] + + Return a status of 0 or 1 depending on the evaluation of the + conditional expression EXPRESSION. Expressions are composed of + the primaries described below in *note Bash Conditional + Expressions::. Word splitting and filename expansion are not + performed on the words between the `[[' and `]]'; tilde expansion, + parameter and variable expansion, arithmetic expansion, command + substitution, process substitution, and quote removal are + performed. Conditional operators such as `-f' must be unquoted to + be recognized as primaries. + + When used with `[[', The `<' and `>' operators sort + lexicographically using the current locale. + + When the `==' and `!=' operators are used, the string to the right + of the operator is considered a pattern and matched according to + the rules described below in *note Pattern Matching::. If the + shell option `nocasematch' (see the description of `shopt' in + *note The Shopt Builtin::) 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, 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 considered 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 return value is 2. If the shell option `nocasematch' + (see the description of `shopt' in *note The Shopt Builtin::) is + enabled, the match is performed without regard to the case of + alphabetic characters. Any part of the pattern may be quoted to + force it to be matched as a string. 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 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. + + `EXPRESSION1 && EXPRESSION2' + True if both EXPRESSION1 and EXPRESSION2 are true. + + `EXPRESSION1 || EXPRESSION2' + True if either EXPRESSION1 or EXPRESSION2 is true. + The `&&' and `||' operators do not evaluate EXPRESSION2 if the + value of EXPRESSION1 is sufficient to determine the return value + of the entire conditional expression. + + + +File: bashref.info, Node: Command Grouping, Prev: Conditional Constructs, Up: Compound Commands + +3.2.4.3 Grouping Commands +......................... + +Bash provides two ways to group a list of commands to be executed as a +unit. When commands 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. + +`()' + ( LIST ) + + Placing a list of commands between parentheses causes a subshell + environment to be created (*note Command Execution Environment::), + 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 newline) 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 +`blank's or other shell metacharacters. 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. + + +File: bashref.info, Node: Coprocesses, Prev: Compound Commands, Up: Shell Commands + +3.2.5 Coprocesses +----------------- + +A `coprocess' is a shell command preceded by the `coproc' reserved word. +A coprocess is executed asynchronously in a subshell, as if the command +had been terminated with the `&' control operator, with a two-way pipe +established between the executing shell and the coprocess. + + The format for a coprocess is: + `coproc' [NAME] COMMAND [REDIRECTIONS] + +This creates a coprocess named NAME. If NAME is not supplied, the +default name is COPROC. NAME must not be supplied if COMMAND is a +simple command (*note Simple Commands::); otherwise, it is interpreted +as the first word of the simple command. + + When the coproc is executed, the shell creates an array variable +(*note Arrays::) named NAME in the context of the executing shell. The +standard output of COMMAND is connected via a pipe to a file descriptor +in the executing shell, and that file descriptor is assigned to NAME[0]. +The standard input of COMMAND is connected via a pipe to a file +descriptor in the executing shell, and that file descriptor is assigned +to NAME[1]. This pipe is established before any redirections specified +by the command (*note Redirections::). The file descriptors can be +utilized as arguments to shell commands and redirections using standard +word expansions. + + The process id of the shell spawned to execute the coprocess is +available as the value of the variable NAME_PID. The `wait' builtin +command may be used to wait for the coprocess to terminate. + + The return status of a coprocess is the exit status of COMMAND. + + +File: bashref.info, Node: Shell Functions, Next: Shell Parameters, Prev: Shell Commands, Up: Basic Shell Features + +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 [ REDIRECTIONS ] + + 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 (*note Compound Commands::). That command is +usually a LIST enclosed between { and }, but may be any compound +command listed above. COMPOUND-COMMAND is executed whenever NAME is +specified as the name of a command. Any redirections (*note +Redirections::) associated with the shell function are performed when +the function is executed. + + A function definition may be deleted using the `-f' option to the +`unset' builtin (*note Bourne Shell Builtins::). + + 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 `blank's or newlines. This is because the braces are +reserved words and are only recognized as such when they are separated +from the command list by whitespace or another shell metacharacter. +Also, when using the braces, the LIST must be terminated by a semicolon, +a `&', or a newline. + + When a function is executed, the arguments to the function become +the positional parameters during its execution (*note Positional +Parameters::). The special parameter `#' 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 these exceptions: 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), and the `ERR' trap +is not inherited unless the `-o errtrace' shell option has been enabled. +*Note Bourne Shell Builtins::, 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 `#' 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. + + Function names and definitions may be listed with the `-f' option to +the `declare' or `typeset' builtin commands (*note Bash Builtins::). +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 (*note Bourne Shell Builtins::). 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. + + +File: bashref.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features + +3.4 Shell Parameters +==================== + +* Menu: + +* Positional Parameters:: The shell's command-line arguments. +* Special Parameters:: Parameters denoted by special characters. + + 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 *note Bash Builtins::). + + 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 expansion, 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 (*note Arithmetic Expansion::). Word splitting is not +performed, with the exception of `"$@"' as explained below. Filename +expansion is not performed. Assignment 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 (*note Arrays::), 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 `+=' is +applied to an array variable using compound assignment (*note +Arrays::), the variable's value is not unset (as it is when using `='), +and new values are appended to the array beginning at one greater than +the array's maximum index (for indexed arrays), or added as additional +key-value pairs in an associative array. When applied to a +string-valued variable, VALUE is expanded and appended to the +variable's value. + + +File: bashref.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters + +3.4.1 Positional Parameters +--------------------------- + +A POSITIONAL PARAMETER is a parameter denoted by one or more digits, +other than the single digit `0'. Positional parameters are assigned +from the shell's arguments when it is invoked, and may be reassigned +using the `set' builtin command. Positional parameter `N' may be +referenced as `${N}', or as `$N' when `N' consists of a single digit. +Positional parameters may not be assigned to with assignment statements. +The `set' and `shift' builtins are used to set and unset them (*note +Shell Builtin Commands::). The positional parameters are temporarily +replaced when a shell function is executed (*note Shell Functions::). + + When a positional parameter consisting of more than a single digit +is expanded, it must be enclosed in braces. + + +File: bashref.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters + +3.4.2 Special Parameters +------------------------ + +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. + +`*' + Expands to the positional parameters, starting from one. When the + expansion occurs within double quotes, it expands to a single word + with the value of each parameter separated by the first character + of the `IFS' special variable. That is, `"$*"' is equivalent to + `"$1C$2C..."', where C is the first character of the value of the + `IFS' variable. If `IFS' is unset, the parameters are separated + by spaces. If `IFS' is null, the parameters are joined without + intervening separators. + +`@' + Expands to the positional parameters, starting from one. When the + expansion occurs within double quotes, each parameter expands to a + separate word. That is, `"$@"' is equivalent to `"$1" "$2" ...'. + If the double-quoted expansion occurs within a word, the expansion + of the first parameter is joined with the beginning part of the + original word, and the expansion of the last parameter is joined + with the last part of the original word. When there are no + positional parameters, `"$@"' and `$@' expand to nothing (i.e., + they are removed). + +`#' + Expands to the number of positional parameters in decimal. + +`?' + Expands to the exit status of the most recently executed foreground + pipeline. + +`-' + (A hyphen.) Expands to the current option flags as specified upon + invocation, by the `set' builtin command, or those set by the + shell itself (such as the `-i' option). + +`$' + Expands to the process ID of the shell. In a `()' subshell, it + expands to the process ID of the invoking shell, not the subshell. + +`!' + Expands to the process ID of the most recently executed background + (asynchronous) command. + +`0' + Expands to the name of the shell or shell script. This is set at + shell initialization. If Bash is invoked with a file of commands + (*note Shell Scripts::), `$0' is set to the name of that file. If + Bash is started with the `-c' option (*note Invoking Bash::), then + `$0' is set to the first argument after the string to be executed, + if one is present. Otherwise, it is set to the filename used to + invoke Bash, as given by argument zero. + +`_' + (An underscore.) At shell startup, set to the absolute pathname + used to invoke the shell or shell script being executed as passed + in the environment or argument list. Subsequently, expands to the + last argument to the previous command, after expansion. Also set + to the full pathname used to invoke each command executed and + placed in the environment exported to that command. When checking + mail, this parameter holds the name of the mail file. + + +File: bashref.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features + +3.5 Shell Expansions +==================== + +Expansion is performed on the command line after it has been split into +`token's. There are seven kinds of expansion performed: + * brace expansion + + * tilde expansion + + * parameter and variable expansion + + * command substitution + + * arithmetic expansion + + * word splitting + + * filename expansion + +* Menu: + +* Brace Expansion:: Expansion of expressions within braces. +* Tilde Expansion:: Expansion of the ~ character. +* Shell Parameter Expansion:: How Bash expands variables to their values. +* Command Substitution:: Using the output of a command as an argument. +* Arithmetic Expansion:: How to use arithmetic in shell expansions. +* Process Substitution:: A way to write and read to and from a + command. +* Word Splitting:: How the results of expansion are split into separate + arguments. +* Filename Expansion:: A shorthand for specifying filenames matching patterns. +* Quote Removal:: How and when quote characters are removed from + words. + + The order of expansions is: brace expansion, tilde expansion, +parameter, variable, and arithmetic expansion and command substitution +(done in a left-to-right fashion), word splitting, and filename +expansion. + + On systems that can support it, there is an additional expansion +available: PROCESS SUBSTITUTION. This is performed at the same time as +parameter, variable, and arithmetic expansion and command substitution. + + Only brace expansion, word splitting, and filename expansion can +change the number of words of the expansion; other expansions expand a +single word to a single word. The only exceptions to this are the +expansions of `"$@"' (*note Special Parameters::) and `"${NAME[@]}"' +(*note Arrays::). + + After all expansions, `quote removal' (*note Quote Removal::) is +performed. + + +File: bashref.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Shell Expansions + +3.5.1 Brace Expansion +--------------------- + +Brace expansion is a mechanism by which arbitrary strings may be +generated. This mechanism is similar to FILENAME EXPANSION (*note +Filename Expansion::), but the file names generated need not exist. +Patterns to be brace expanded take the form of an optional PREAMBLE, +followed by either a series of comma-separated strings or a seqeunce +expression between a pair of braces, followed by an optional POSTSCRIPT. +The preamble is prefixed to each string contained within the braces, and +the postscript is then appended to each resulting string, expanding left +to right. + + Brace expansions may be nested. The results of each expanded string +are not sorted; left to right order is preserved. For example, + bash$ echo a{d,c,b}e + ade ace abe + + A sequence expression takes the form `{X..Y[..INCR]}', where X and Y +are either integers or single characters, and INCR, an optional +increment, is an integer. When integers are supplied, the expression +expands to each number between X and Y, inclusive. Supplied integers +may be prefixed with `0' to force each term to have the same width. +When either X or Y begins with a zero, the shell attempts to force all +generated terms to contain the same number of digits, zero-padding +where necessary. When characters are supplied, the expression expands +to each character lexicographically between X and Y, inclusive. Note +that both X and Y must be of the same type. When the increment is +supplied, it is used as the difference between each term. The default +increment is 1 or -1 as appropriate. + + Brace expansion is performed before any other expansions, and any +characters special to other expansions are preserved in the result. It +is strictly textual. Bash does not apply any syntactic interpretation +to the context of the expansion or the text between the braces. To +avoid conflicts with parameter expansion, the string `${' is not +considered eligible for brace expansion. + + A correctly-formed brace expansion must contain unquoted opening and +closing braces, and at least one unquoted comma or a valid sequence +expression. Any incorrectly formed brace expansion is left unchanged. + + A { or `,' may be quoted with a backslash to prevent its being +considered part of a brace expression. To avoid conflicts with +parameter expansion, the string `${' is not considered eligible for +brace expansion. + + This construct is typically used as shorthand when the common prefix +of the strings to be generated is longer than in the above example: + mkdir /usr/local/src/bash/{old,new,dist,bugs} + or + chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} + + +File: bashref.info, Node: Tilde Expansion, Next: Shell Parameter Expansion, Prev: Brace Expansion, Up: Shell Expansions + +3.5.2 Tilde Expansion +--------------------- + +If a word begins with an unquoted tilde character (`~'), all of the +characters up to the first unquoted slash (or all characters, if there +is no unquoted slash) are considered a TILDE-PREFIX. If none of the +characters in the tilde-prefix are quoted, the characters in the +tilde-prefix following the tilde are treated as a possible LOGIN NAME. +If this login name is the null string, the tilde is replaced with the +value of the `HOME' shell variable. If `HOME' is unset, the home +directory of the user executing the shell is substituted instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. + + If the tilde-prefix is `~+', the value of the shell variable `PWD' +replaces the tilde-prefix. If the tilde-prefix is `~-', the value of +the shell variable `OLDPWD', if it is set, is substituted. + + If the characters following the tilde in the tilde-prefix consist of +a number N, optionally prefixed by a `+' or a `-', the tilde-prefix is +replaced with the corresponding element from the directory stack, as it +would be displayed by the `dirs' builtin invoked with the characters +following tilde in the tilde-prefix as an argument (*note The Directory +Stack::). If the tilde-prefix, sans the tilde, consists of a number +without a leading `+' or `-', `+' is assumed. + + If the login name is invalid, or the tilde expansion fails, the word +is left unchanged. + + Each variable assignment is checked for unquoted tilde-prefixes +immediately following a `:' or the first `='. In these cases, tilde +expansion is also performed. Consequently, one may use file names with +tildes in assignments to `PATH', `MAILPATH', and `CDPATH', and the +shell assigns the expanded value. + + The following table shows how Bash treats unquoted tilde-prefixes: + +`~' + The value of `$HOME' + +`~/foo' + `$HOME/foo' + +`~fred/foo' + The subdirectory `foo' of the home directory of the user `fred' + +`~+/foo' + `$PWD/foo' + +`~-/foo' + `${OLDPWD-'~-'}/foo' + +`~N' + The string that would be displayed by `dirs +N' + +`~+N' + The string that would be displayed by `dirs +N' + +`~-N' + The string that would be displayed by `dirs -N' + + + +File: bashref.info, Node: Shell Parameter Expansion, Next: Command Substitution, Prev: Tilde Expansion, Up: Shell Expansions + +3.5.3 Shell Parameter Expansion +------------------------------- + +The `$' character introduces parameter expansion, command substitution, +or arithmetic expansion. The parameter name or symbol to be expanded +may be enclosed in braces, which are optional but serve to protect the +variable to be expanded from characters immediately following it which +could be interpreted as part of the name. + + When braces are used, the matching ending brace is the first `}' not +escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. + + The basic form of parameter expansion is ${PARAMETER}. The value of +PARAMETER is substituted. The braces are required when PARAMETER is a +positional parameter with more than one digit, or when PARAMETER is +followed by a character that is not to be interpreted as part of its +name. + + If the first character of PARAMETER is an exclamation point (!), a +level of variable indirection is introduced. Bash uses the value of +the variable formed from the rest of PARAMETER as the name of the +variable; this variable is then expanded and that value is used in the +rest of the substitution, rather than the value of PARAMETER itself. +This is known as `indirect expansion'. The exceptions to this are the +expansions of ${!PREFIX*} and ${!NAME[@]} described below. The +exclamation point must immediately follow the left brace in order to +introduce indirection. + + In each of the cases below, WORD is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. + + When not performing substring expansion, using the form described +below, Bash tests for a parameter that is unset or null. Omitting the +colon results in a test only for a parameter that is unset. Put +another way, if the colon is included, the operator tests for both +PARAMETER's existence and that its value is not null; if the colon is +omitted, the operator tests only for existence. + +`${PARAMETER:-WORD}' + If PARAMETER is unset or null, the expansion of WORD is + substituted. Otherwise, the value of PARAMETER is substituted. + +`${PARAMETER:=WORD}' + If PARAMETER is unset or null, the expansion of WORD is assigned + to PARAMETER. The value of PARAMETER is then substituted. + Positional parameters and special parameters may not be assigned to + in this way. + +`${PARAMETER:?WORD}' + If PARAMETER is null or unset, the expansion of WORD (or a message + to that effect if WORD is not present) is written to the standard + error and the shell, if it is not interactive, exits. Otherwise, + the value of PARAMETER is substituted. + +`${PARAMETER:+WORD}' + If PARAMETER is null or unset, nothing is substituted, otherwise + the expansion of WORD is substituted. + +`${PARAMETER:OFFSET}' +`${PARAMETER:OFFSET:LENGTH}' + Expands to up to LENGTH characters of PARAMETER starting at the + character specified by OFFSET. If LENGTH is omitted, expands to + the substring of PARAMETER starting at the character specified by + OFFSET. LENGTH and OFFSET are arithmetic expressions (*note Shell + Arithmetic::). This is referred to as Substring Expansion. + + LENGTH must evaluate to a number greater than or equal to zero. + If OFFSET evaluates to a number less than zero, the value is used + as an offset from the end of the value of PARAMETER. If PARAMETER + is `@', the result is LENGTH positional parameters beginning at + OFFSET. If PARAMETER is an indexed array name subscripted by `@' + or `*', the result is the LENGTH members of the array beginning + with `${PARAMETER[OFFSET]}'. A negative OFFSET is taken relative + to one greater than the maximum index of the specified array. + Substring expansion applied to an associative array produces + undefined results. + + Note that a negative offset must be separated from the colon by at + least one space to avoid being confused with the `:-' expansion. + Substring indexing is zero-based unless the positional parameters + are used, in which case the indexing starts at 1 by default. If + OFFSET is 0, and the positional parameters are used, `$@' is + prefixed to the list. + +`${!PREFIX*}' +`${!PREFIX@}' + Expands to the names of variables whose names begin with PREFIX, + separated by the first character of the `IFS' special variable. + When `@' is used and the expansion appears within double quotes, + each variable name expands to a separate word. + +`${!NAME[@]}' +`${!NAME[*]}' + If NAME is an array variable, expands to the list of array indices + (keys) assigned in NAME. If NAME is not an array, expands to 0 if + NAME is set and null otherwise. When `@' is used and the + expansion appears within double quotes, each key expands to a + separate word. + +`${#PARAMETER}' + The length in characters of the expanded value of PARAMETER is + substituted. If PARAMETER is `*' or `@', the value substituted is + the number of positional parameters. If PARAMETER is an array + name subscripted by `*' or `@', the value substituted is the + number of elements in the array. + +`${PARAMETER#WORD}' +`${PARAMETER##WORD}' + The WORD is expanded to produce a pattern just as in filename + expansion (*note Filename Expansion::). If the pattern matches + the beginning of the expanded value of PARAMETER, then the result + of the expansion is the expanded value of PARAMETER with the + shortest matching pattern (the `#' case) or the longest matching + pattern (the `##' case) deleted. If PARAMETER is `@' or `*', the + pattern removal operation is applied to each positional parameter + in turn, and the expansion is the resultant list. If PARAMETER is + an array variable subscripted with `@' or `*', the pattern removal + operation is applied to each member of the array in turn, and the + expansion is the resultant list. + +`${PARAMETER%WORD}' +`${PARAMETER%%WORD}' + The WORD is expanded to produce a pattern just as in filename + expansion. If the pattern matches a trailing portion of the + expanded value of PARAMETER, then the result of the expansion is + the value of PARAMETER with the shortest matching pattern (the `%' + case) or the longest matching pattern (the `%%' case) deleted. If + PARAMETER is `@' or `*', the pattern removal operation is applied + to each positional parameter in turn, and the expansion is the + resultant list. If PARAMETER is an array variable subscripted + with `@' or `*', the pattern removal operation is applied to each + member of the array in turn, and the expansion is the resultant + list. + +`${PARAMETER/PATTERN/STRING}' + The PATTERN is expanded to produce a pattern just as in filename + expansion. PARAMETER is expanded and the longest match of PATTERN + against its value is replaced with STRING. If PATTERN begins with + `/', all matches of PATTERN are replaced with STRING. Normally + only the first match is replaced. If PATTERN begins with `#', it + must match at the beginning of the expanded value of PARAMETER. + If PATTERN begins with `%', it must match at the end of the + expanded value of PARAMETER. If STRING is null, matches of + PATTERN are deleted and the `/' following PATTERN may be omitted. + If PARAMETER is `@' or `*', the substitution operation is applied + to each positional parameter in turn, and the expansion is the + resultant list. If PARAMETER is an array variable subscripted + with `@' or `*', the substitution operation is applied to each + member of the array in turn, and the expansion is the resultant + list. + +`${PARAMETER^PATTERN}' +`${PARAMETER^^PATTERN}' +`${PARAMETER,PATTERN}' +`${PARAMETER,,PATTERN}' + This expansion modifies the case of alphabetic characters in + PARAMETER. The PATTERN is expanded to produce a pattern just as in + filename expansion. The `^' operator converts lowercase letters + matching PATTERN to uppercase; the `,' operator converts matching + uppercase letters to lowercase. The `^^' and `,,' expansions + convert each matched character in the expanded value; the `^' and + `,' expansions match and convert only the first character in the + expanded value. If PATTERN is omitted, it is treated like a `?', + which matches every character. If PARAMETER is `@' or `*', the + case modification operation is applied to each positional + parameter in turn, and the expansion is the resultant list. If + PARAMETER is an array variable subscripted with `@' or `*', the + case modification operation is applied to each member of the array + in turn, and the expansion is the resultant list. + + + +File: bashref.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Shell Parameter Expansion, Up: Shell Expansions + +3.5.4 Command Substitution +-------------------------- + +Command substitution allows the output of a command to replace the +command itself. Command substitution occurs when a command is enclosed +as follows: + $(COMMAND) + or + `COMMAND` + +Bash performs the expansion by executing COMMAND and replacing the +command substitution with the standard output of the command, with any +trailing newlines deleted. Embedded newlines are not deleted, but they +may be removed during word splitting. The command substitution `$(cat +FILE)' can be replaced by the equivalent but faster `$(< FILE)'. + + When the old-style backquote form of substitution is used, backslash +retains its literal meaning except when followed by `$', ``', or `\'. +The first backquote not preceded by a backslash terminates the command +substitution. When using the `$(COMMAND)' form, all characters between +the parentheses make up the command; none are treated specially. + + Command substitutions may be nested. To nest when using the +backquoted form, escape the inner backquotes with backslashes. + + If the substitution appears within double quotes, word splitting and +filename expansion are not performed on the results. + + +File: bashref.info, Node: Arithmetic Expansion, Next: Process Substitution, Prev: Command Substitution, Up: Shell Expansions + +3.5.5 Arithmetic Expansion +-------------------------- + +Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic +expansion is: + + $(( EXPRESSION )) + + The expression is treated as if it were within double quotes, but a +double quote inside the parentheses is not treated specially. All +tokens in the expression undergo parameter expansion, command +substitution, and quote removal. Arithmetic expansions may be nested. + + The evaluation is performed according to the rules listed below +(*note Shell Arithmetic::). If the expression is invalid, Bash prints +a message indicating failure to the standard error and no substitution +occurs. + + +File: bashref.info, Node: Process Substitution, Next: Word Splitting, Prev: Arithmetic Expansion, Up: Shell Expansions + +3.5.6 Process Substitution +-------------------------- + +Process substitution is supported on systems that support named pipes +(FIFOs) or the `/dev/fd' method of naming open files. It takes the +form of + <(LIST) + or + >(LIST) + The process LIST is run with its input or output connected to a FIFO +or some file in `/dev/fd'. The name of this file is passed as an +argument to the current command as the result of the expansion. If the +`>(LIST)' form is used, writing to the file will provide input for +LIST. If the `<(LIST)' form is used, the file passed as an argument +should be read to obtain the output of LIST. Note that no space may +appear between the `<' or `>' and the left parenthesis, otherwise the +construct would be interpreted as a redirection. + + When available, process substitution is performed simultaneously with +parameter and variable expansion, command substitution, and arithmetic +expansion. + + +File: bashref.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions + +3.5.7 Word Splitting +-------------------- + +The shell scans the results of parameter expansion, command +substitution, and arithmetic expansion that did not occur within double +quotes for word splitting. + + The shell treats each character of `$IFS' as a delimiter, and splits +the results of the other expansions into words on these characters. If +`IFS' is unset, or its value is exactly `<space><tab><newline>', the +default, then sequences of ` <space>', `<tab>', and `<newline>' at the +beginning and end of the results of the previous expansions are +ignored, and any sequence of `IFS' characters not at the beginning or +end serves to delimit words. If `IFS' has a value other than the +default, then sequences of the whitespace characters `space' and `tab' +are ignored at the beginning and end of the word, as long as the +whitespace character is in the value of `IFS' (an `IFS' whitespace +character). Any character in `IFS' that is not `IFS' whitespace, along +with any adjacent `IFS' whitespace characters, delimits a field. A +sequence of `IFS' whitespace characters is also treated as a delimiter. +If the value of `IFS' is null, no word splitting occurs. + + Explicit null arguments (`""' or `''') are retained. Unquoted +implicit null arguments, resulting from the expansion of parameters +that have no values, are removed. If a parameter with no value is +expanded within double quotes, a null argument results and is retained. + + Note that if no expansion occurs, no splitting is performed. + + +File: bashref.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions + +3.5.8 Filename Expansion +------------------------ + +* Menu: + +* Pattern Matching:: How the shell matches patterns. + + After word splitting, unless the `-f' option has been set (*note The +Set Builtin::), Bash scans each word for the characters `*', `?', and +`['. If one of these characters appears, then the word is regarded as +a PATTERN, and replaced with an alphabetically sorted list of file +names matching the pattern. If no matching file names are found, and +the shell option `nullglob' is disabled, the word is left unchanged. +If the `nullglob' option is set, and no matches are found, the word is +removed. If the `failglob' shell option is set, and no matches are +found, an error message is printed and the command is not executed. If +the shell option `nocaseglob' is enabled, the match is performed +without regard to the case of alphabetic characters. + + When a pattern is used for filename expansion, the character `.' at +the start of a filename or immediately following a slash must be +matched explicitly, unless the shell option `dotglob' is set. When +matching a file name, the slash character must always be matched +explicitly. In other cases, the `.' character is not treated specially. + + See the description of `shopt' in *note The Shopt Builtin::, for a +description of the `nocaseglob', `nullglob', `failglob', and `dotglob' +options. + + The `GLOBIGNORE' shell variable may be used to restrict the set of +filenames matching a pattern. If `GLOBIGNORE' is set, each matching +filename that also matches one of the patterns in `GLOBIGNORE' is +removed from the list of matches. The filenames `.' and `..' are +always ignored when `GLOBIGNORE' is set and not null. However, setting +`GLOBIGNORE' to a non-null value has the effect of enabling the +`dotglob' shell option, so all other filenames beginning with a `.' +will match. To get the old behavior of ignoring filenames beginning +with a `.', make `.*' one of the patterns in `GLOBIGNORE'. The +`dotglob' option is disabled when `GLOBIGNORE' is unset. + + +File: bashref.info, Node: Pattern Matching, Up: Filename Expansion + +3.5.8.1 Pattern Matching +........................ + +Any character that appears in a pattern, other than the special pattern +characters described below, matches itself. The NUL character may not +occur in a pattern. A backslash escapes the following character; the +escaping backslash is discarded when matching. The special pattern +characters must be quoted if they are to be matched literally. + + The special pattern characters have the following meanings: +`*' + Matches any string, including the null string. When the + `globstar' shell option is enabled, and `*' is used in a filename + expansion context, two adjacent `*'s used as a single pattern will + match all files and zero or more directories and subdirectories. + If followed by a `/', two adjacent `*'s will match only + directories and subdirectories. + +`?' + Matches any single character. + +`[...]' + Matches any one of the enclosed characters. A pair of characters + separated by a hyphen denotes a RANGE EXPRESSION; any character + that sorts between those two characters, inclusive, using the + current locale's collating sequence and character set, is matched. + If the first character following the `[' is a `!' or a `^' then + any character not enclosed is matched. A `-' may be matched by + including it as the first or last character in the set. A `]' may + be matched by including it as the first character in the set. The + sorting order of characters in range expressions is determined by + the current locale and the value of the `LC_COLLATE' shell + variable, if set. + + For example, in the default C locale, `[a-dx-z]' is equivalent to + `[abcdxyz]'. Many locales sort characters in dictionary order, + and in these locales `[a-dx-z]' is typically not equivalent to + `[abcdxyz]'; it might be equivalent to `[aBbCcDdxXyYz]', for + example. To obtain the traditional interpretation of ranges in + bracket expressions, you can force the use of the C locale by + setting the `LC_COLLATE' or `LC_ALL' environment variable to the + value `C'. + + Within `[' and `]', CHARACTER CLASSES can be specified using the + syntax `[:'CLASS`:]', where CLASS is one of the following classes + defined in the POSIX standard: + alnum alpha ascii blank cntrl digit graph lower + print punct space upper word xdigit + A character class matches any character belonging to that class. + The `word' character class matches letters, digits, and the + character `_'. + + Within `[' and `]', an EQUIVALENCE CLASS can be specified using + the syntax `[='C`=]', which matches all characters with the same + collation weight (as defined by the current locale) as the + character C. + + Within `[' and `]', the syntax `[.'SYMBOL`.]' matches the + collating symbol SYMBOL. + + If the `extglob' shell option is enabled using the `shopt' builtin, +several extended pattern matching operators are recognized. In the +following description, a PATTERN-LIST is a list of one or more patterns +separated by a `|'. Composite patterns may be formed using one or more +of the following sub-patterns: + +`?(PATTERN-LIST)' + Matches zero or one occurrence of the given patterns. + +`*(PATTERN-LIST)' + Matches zero or more occurrences of the given patterns. + +`+(PATTERN-LIST)' + Matches one or more occurrences of the given patterns. + +`@(PATTERN-LIST)' + Matches one of the given patterns. + +`!(PATTERN-LIST)' + Matches anything except one of the given patterns. + + +File: bashref.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions + +3.5.9 Quote Removal +------------------- + +After the preceding expansions, all unquoted occurrences of the +characters `\', `'', and `"' that did not result from one of the above +expansions are removed. + + +File: bashref.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features + +3.6 Redirections +================ + +Before a command is executed, its input and output may be REDIRECTED +using a special notation interpreted by the shell. Redirection may +also be used to open and close files for the current shell execution +environment. The following redirection operators may precede or appear +anywhere within a simple command or may follow a command. Redirections +are processed in the order they appear, from left to right. + + Each redirection that may be preceded by a file descriptor number +may instead be preceded by a word of the form {VARNAME}. In this case, +for each redirection operator except >&- and <&-, the shell will +allocate a file descriptor greater than 10 and assign it to {VARNAME}. +If >&- or <&- is preceded by {VARNAME}, the value of VARNAME defines +the file descriptor to close. + + In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is `<', +the redirection refers to the standard input (file descriptor 0). If +the first character of the redirection operator is `>', the redirection +refers to the standard output (file descriptor 1). + + The word following the redirection operator in the following +descriptions, unless otherwise noted, is subjected to brace expansion, +tilde expansion, parameter expansion, command substitution, arithmetic +expansion, quote removal, filename expansion, and word splitting. If +it expands to more than one word, Bash reports an error. + + Note that the order of redirections is significant. For example, +the command + ls > DIRLIST 2>&1 + directs both standard output (file descriptor 1) and standard error +(file descriptor 2) to the file DIRLIST, while the command + ls 2>&1 > DIRLIST + directs only the standard output to file DIRLIST, because the +standard error was made a copy of the standard output before the +standard output was redirected to DIRLIST. + + Bash handles several filenames specially when they are used in +redirections, as described in the following table: + +`/dev/fd/FD' + If FD is a valid integer, file descriptor FD is duplicated. + +`/dev/stdin' + File descriptor 0 is duplicated. + +`/dev/stdout' + File descriptor 1 is duplicated. + +`/dev/stderr' + File descriptor 2 is duplicated. + +`/dev/tcp/HOST/PORT' + If HOST is a valid hostname or Internet address, and PORT is an + integer port number or service name, Bash attempts to open a TCP + connection to the corresponding socket. + +`/dev/udp/HOST/PORT' + If HOST is a valid hostname or Internet address, and PORT is an + integer port number or service name, Bash attempts to open a UDP + connection to the corresponding socket. + + + A failure to open or create a file causes the redirection to fail. + + Redirections using file descriptors greater than 9 should be used +with care, as they may conflict with file descriptors the shell uses +internally. + +3.6.1 Redirecting Input +----------------------- + +Redirection of input causes the file whose name results from the +expansion of WORD to be opened for reading on file descriptor `n', or +the standard input (file descriptor 0) if `n' is not specified. + + The general format for redirecting input is: + [N]<WORD + +3.6.2 Redirecting Output +------------------------ + +Redirection of output causes the file whose name results from the +expansion of WORD to be opened for writing on file descriptor N, or the +standard output (file descriptor 1) if N is not specified. If the file +does not exist it is created; if it does exist it is truncated to zero +size. + + The general format for redirecting output is: + [N]>[|]WORD + + If the redirection operator is `>', and the `noclobber' option to +the `set' builtin has been enabled, the redirection will fail if the +file whose name results from the expansion of WORD exists and is a +regular file. If the redirection operator is `>|', or the redirection +operator is `>' and the `noclobber' option is not enabled, the +redirection is attempted even if the file named by WORD exists. + +3.6.3 Appending Redirected Output +--------------------------------- + +Redirection of output in this fashion causes the file whose name +results from the expansion of WORD to be opened for appending on file +descriptor N, or the standard output (file descriptor 1) if N is not +specified. If the file does not exist it is created. + + The general format for appending output is: + [N]>>WORD + +3.6.4 Redirecting Standard Output and Standard Error +---------------------------------------------------- + +This construct allows both the standard output (file descriptor 1) and +the standard error output (file descriptor 2) to be redirected to the +file whose name is the expansion of WORD. + + There are two formats for redirecting standard output and standard +error: + &>WORD + and + >&WORD + Of the two forms, the first is preferred. This is semantically +equivalent to + >WORD 2>&1 + +3.6.5 Appending Standard Output and Standard Error +-------------------------------------------------- + +This construct allows both the standard output (file descriptor 1) and +the standard error output (file descriptor 2) to be appended to the +file whose name is the expansion of WORD. + + The format for appending standard output and standard error is: + &>>WORD + This is semantically equivalent to + >>WORD 2>&1 + +3.6.6 Here Documents +-------------------- + +This type of redirection instructs the shell to read input from the +current source until a line containing only WORD (with no trailing +blanks) is seen. All of the lines read up to that point are then used +as the standard input for a command. + + The format of here-documents is: + <<[-]WORD + HERE-DOCUMENT + DELIMITER + + No parameter expansion, command substitution, arithmetic expansion, +or filename expansion is performed on WORD. If any characters in WORD +are quoted, the DELIMITER is the result of quote removal on WORD, and +the lines in the here-document are not expanded. If WORD is unquoted, +all lines of the here-document are subjected to parameter expansion, +command substitution, and arithmetic expansion. In the latter case, +the character sequence `\newline' is ignored, and `\' must be used to +quote the characters `\', `$', and ``'. + + If the redirection operator is `<<-', then all leading tab +characters are stripped from input lines and the line containing +DELIMITER. This allows here-documents within shell scripts to be +indented in a natural fashion. + +3.6.7 Here Strings +------------------ + +A variant of here documents, the format is: + <<< WORD + + The WORD is expanded and supplied to the command on its standard +input. + +3.6.8 Duplicating File Descriptors +---------------------------------- + +The redirection operator + [N]<&WORD + is used to duplicate input file descriptors. If WORD expands to one +or more digits, the file descriptor denoted by N is made to be a copy +of that file descriptor. If the digits in WORD do not specify a file +descriptor open for input, a redirection error occurs. If WORD +evaluates to `-', file descriptor N is closed. If N is not specified, +the standard input (file descriptor 0) is used. + + The operator + [N]>&WORD + is used similarly to duplicate output file descriptors. If N is not +specified, the standard output (file descriptor 1) is used. If the +digits in WORD do not specify a file descriptor open for output, a +redirection error occurs. As a special case, if N is omitted, and WORD +does not expand to one or more digits, the standard output and standard +error are redirected as described previously. + +3.6.9 Moving File Descriptors +----------------------------- + +The redirection operator + [N]<&DIGIT- + moves the file descriptor DIGIT to file descriptor N, or the +standard input (file descriptor 0) if N is not specified. DIGIT is +closed after being duplicated to N. + + Similarly, the redirection operator + [N]>&DIGIT- + moves the file descriptor DIGIT to file descriptor N, or the +standard output (file descriptor 1) if N is not specified. + +3.6.10 Opening File Descriptors for Reading and Writing +------------------------------------------------------- + +The redirection operator + [N]<>WORD + causes the file whose name is the expansion of WORD to be opened for +both reading and writing on file descriptor N, or on file descriptor 0 +if N is not specified. If the file does not exist, it is created. + + +File: bashref.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features + +3.7 Executing Commands +====================== + +* Menu: + +* Simple Command Expansion:: How Bash expands simple commands before + executing them. +* Command Search and Execution:: How Bash finds commands and runs them. +* Command Execution Environment:: The environment in which Bash + executes commands that are not + shell builtins. +* Environment:: The environment given to a command. +* Exit Status:: The status returned by commands and how Bash + interprets it. +* Signals:: What happens when Bash or a command it runs + receives a signal. + + +File: bashref.info, Node: Simple Command Expansion, Next: Command Search and Execution, Up: Executing Commands + +3.7.1 Simple Command Expansion +------------------------------ + +When a simple command is executed, the shell performs the following +expansions, assignments, and redirections, from left to right. + + 1. The words that the parser has marked as variable assignments (those + preceding the command name) and redirections are saved for later + processing. + + 2. The words that are not variable assignments or redirections are + expanded (*note Shell Expansions::). If any words remain after + expansion, the first word is taken to be the name of the command + and the remaining words are the arguments. + + 3. Redirections are performed as described above (*note + Redirections::). + + 4. The text after the `=' in each variable assignment undergoes tilde + expansion, parameter expansion, command substitution, arithmetic + expansion, and quote removal before being assigned to the variable. + + If no command name results, the variable assignments affect the +current shell environment. Otherwise, the variables are added to the +environment of the executed command and do not affect the current shell +environment. If any of the assignments attempts to assign a value to a +readonly variable, an error occurs, and the command exits with a +non-zero status. + + If no command name results, redirections are performed, but do not +affect the current shell environment. A redirection error causes the +command to exit with a non-zero status. + + If there is a command name left after expansion, execution proceeds +as described below. Otherwise, the command exits. If one of the +expansions contained a command substitution, the exit status of the +command is the exit status of the last command substitution performed. +If there were no command substitutions, the command exits with a status +of zero. + + +File: bashref.info, Node: Command Search and Execution, Next: Command Execution Environment, Prev: Simple Command Expansion, Up: Executing Commands + +3.7.2 Command Search and Execution +---------------------------------- + +After a command has been split into words, if it results in a simple +command and an optional list of arguments, the following actions are +taken. + + 1. If the command name contains no slashes, the shell attempts to + locate it. If there exists a shell function by that name, that + function is invoked as described in *note Shell Functions::. + + 2. If the name does not match a function, the shell searches for it + in the list of shell builtins. If a match is found, that builtin + is invoked. + + 3. If the name is neither a shell function nor a builtin, and + contains no slashes, Bash searches each element of `$PATH' for a + directory containing an executable file by that name. Bash uses a + hash table to remember the full pathnames of executable files to + avoid multiple `PATH' searches (see the description of `hash' in + *note Bourne Shell Builtins::). A full search of the directories + in `$PATH' is performed only if the command is not found in the + hash table. If the search is unsuccessful, the shell searches for + a defined shell function named `command_not_found_handle'. If + that function exists, it is invoked with the original command and + the original command's arguments as its arguments, and the + function's exit status becomes the exit status of the shell. If + that function is not defined, the shell prints an error message + and returns an exit status of 127. + + 4. If the search is successful, or if the command name contains one + or more slashes, the shell executes the named program in a + separate execution environment. Argument 0 is set to the name + given, and the remaining arguments to the command are set to the + arguments supplied, if any. + + 5. If this execution fails because the file is not in executable + format, and the file is not a directory, it is assumed to be a + SHELL SCRIPT and the shell executes it as described in *note Shell + Scripts::. + + 6. If the command was not begun asynchronously, the shell waits for + the command to complete and collects its exit status. + + + +File: bashref.info, Node: Command Execution Environment, Next: Environment, Prev: Command Search and Execution, Up: Executing Commands + +3.7.3 Command Execution Environment +----------------------------------- + +The shell has an EXECUTION ENVIRONMENT, which consists of the following: + + * open files inherited by the shell at invocation, as modified by + redirections supplied to the `exec' builtin + + * the current working directory as set by `cd', `pushd', or `popd', + or inherited by the shell at invocation + + * the file creation mode mask as set by `umask' or inherited from + the shell's parent + + * current traps set by `trap' + + * shell parameters that are set by variable assignment or with `set' + or inherited from the shell's parent in the environment + + * shell functions defined during execution or inherited from the + shell's parent in the environment + + * options enabled at invocation (either by default or with + command-line arguments) or by `set' + + * options enabled by `shopt' (*note The Shopt Builtin::) + + * shell aliases defined with `alias' (*note Aliases::) + + * various process IDs, including those of background jobs (*note + Lists::), the value of `$$', and the value of `$PPID' + + + When a simple command other than a builtin or shell function is to +be executed, it is invoked in a separate execution environment that +consists of the following. Unless otherwise noted, the values are +inherited from the shell. + + * the shell's open files, plus any modifications and additions + specified by redirections to the command + + * the current working directory + + * the file creation mode mask + + * shell variables and functions marked for export, along with + variables exported for the command, passed in the environment + (*note Environment::) + + * traps caught by the shell are reset to the values inherited from + the shell's parent, and traps ignored by the shell are ignored + + + A command invoked in this separate environment cannot affect the +shell's execution environment. + + Command substitution, commands grouped with parentheses, and +asynchronous commands are invoked in a subshell environment that is a +duplicate of the shell environment, except that traps caught by the +shell are reset to the values that the shell inherited from its parent +at invocation. Builtin commands that are invoked as part of a pipeline +are also executed in a subshell environment. Changes made to the +subshell environment cannot affect the shell's execution environment. + + Subshells spawned to execute command substitutions inherit the value +of the `-e' option from the parent shell. When not in POSIX mode, Bash +clears the `-e' option in such subshells. + + If a command is followed by a `&' and job control is not active, the +default standard input for the command is the empty file `/dev/null'. +Otherwise, the invoked command inherits the file descriptors of the +calling shell as modified by redirections. + + +File: bashref.info, Node: Environment, Next: Exit Status, Prev: Command Execution Environment, Up: Executing Commands + +3.7.4 Environment +----------------- + +When a program is invoked it is given an array of strings called the +ENVIRONMENT. This is a list of name-value pairs, of the form +`name=value'. + + Bash provides several ways to manipulate the environment. On +invocation, the shell scans its own environment and creates a parameter +for each name found, automatically marking it for EXPORT to child +processes. Executed commands inherit the environment. The `export' +and `declare -x' commands allow parameters and functions to be added to +and deleted from the environment. If the value of a parameter in the +environment is modified, the new value becomes part of the environment, +replacing the old. The environment inherited by any executed command +consists of the shell's initial environment, whose values may be +modified in the shell, less any pairs removed by the `unset' and +`export -n' commands, plus any additions via the `export' and `declare +-x' commands. + + The environment for any simple command or function may be augmented +temporarily by prefixing it with parameter assignments, as described in +*note Shell Parameters::. These assignment statements affect only the +environment seen by that command. + + If the `-k' option is set (*note The Set Builtin::), then all +parameter assignments are placed in the environment for a command, not +just those that precede the command name. + + When Bash invokes an external command, the variable `$_' is set to +the full path name of the command and passed to that command in its +environment. + + +File: bashref.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands + +3.7.5 Exit Status +----------------- + +The exit status of an executed command is the value returned by the +WAITPID system call or equivalent function. Exit statuses fall between +0 and 255, though, as explained below, the shell may use values above +125 specially. Exit statuses from shell builtins and compound commands +are also limited to this range. Under certain circumstances, the shell +will use special values to indicate specific failure modes. + + For the shell's purposes, a command which exits with a zero exit +status has succeeded. A non-zero exit status indicates failure. This +seemingly counter-intuitive scheme is used so there is one well-defined +way to indicate success and a variety of ways to indicate various +failure modes. When a command terminates on a fatal signal whose +number is N, Bash uses the value 128+N as the exit status. + + If a command is not found, the child process created to execute it +returns a status of 127. If a command is found but is not executable, +the return status is 126. + + If a command fails because of an error during expansion or +redirection, the exit status is greater than zero. + + The exit status is used by the Bash conditional commands (*note +Conditional Constructs::) and some of the list constructs (*note +Lists::). + + All of the Bash builtins return an exit status of zero if they +succeed and a non-zero status on failure, so they may be used by the +conditional and list constructs. All builtins return an exit status of +2 to indicate incorrect usage. + + +File: bashref.info, Node: Signals, Prev: Exit Status, Up: Executing Commands + +3.7.6 Signals +------------- + +When Bash is interactive, in the absence of any traps, it ignores +`SIGTERM' (so that `kill 0' does not kill an interactive shell), and +`SIGINT' is caught and handled (so that the `wait' builtin is +interruptible). When Bash receives a `SIGINT', it breaks out of any +executing loops. In all cases, Bash ignores `SIGQUIT'. If job control +is in effect (*note Job Control::), Bash ignores `SIGTTIN', `SIGTTOU', +and `SIGTSTP'. + + Non-builtin commands started by Bash have signal handlers set to the +values inherited by the shell from its parent. When job control is not +in effect, asynchronous commands ignore `SIGINT' and `SIGQUIT' in +addition to these inherited handlers. Commands run as a result of +command substitution ignore the keyboard-generated job control signals +`SIGTTIN', `SIGTTOU', and `SIGTSTP'. + + The shell exits by default upon receipt of a `SIGHUP'. Before +exiting, an interactive shell resends the `SIGHUP' to all jobs, running +or stopped. Stopped jobs are sent `SIGCONT' to ensure that they receive +the `SIGHUP'. To prevent the shell from sending the `SIGHUP' signal to +a particular job, it should be removed from the jobs table with the +`disown' builtin (*note Job Control Builtins::) or marked to not +receive `SIGHUP' using `disown -h'. + + If the `huponexit' shell option has been set with `shopt' (*note +The Shopt Builtin::), Bash sends a `SIGHUP' to all jobs when an +interactive login shell exits. + + If Bash is waiting for a command to complete and receives a signal +for which a trap has been set, the trap will not be executed until the +command completes. When Bash is waiting for an asynchronous command +via the `wait' builtin, the reception of a signal for which a trap has +been set will cause the `wait' builtin to return immediately with an +exit status greater than 128, immediately after which the trap is +executed. + + +File: bashref.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features + +3.8 Shell Scripts +================= + +A shell script is a text file containing shell commands. When such a +file is used as the first non-option argument when invoking Bash, and +neither the `-c' nor `-s' option is supplied (*note Invoking Bash::), +Bash reads and executes commands from the file, then exits. This mode +of operation creates a non-interactive shell. The shell first searches +for the file in the current directory, and looks in the directories in +`$PATH' if not found there. + + When Bash runs a shell script, it sets the special parameter `0' to +the name of the file, rather than the name of the shell, and the +positional parameters are set to the remaining arguments, if any are +given. If no additional arguments are supplied, the positional +parameters are unset. + + A shell script may be made executable by using the `chmod' command +to turn on the execute bit. When Bash finds such a file while +searching the `$PATH' for a command, it spawns a subshell to execute +it. In other words, executing + filename ARGUMENTS + is equivalent to executing + bash filename ARGUMENTS + +if `filename' is an executable shell script. This subshell +reinitializes itself, so that the effect is as if a new shell had been +invoked to interpret the script, with the exception that the locations +of commands remembered by the parent (see the description of `hash' in +*note Bourne Shell Builtins::) are retained by the child. + + Most versions of Unix make this a part of the operating system's +command execution mechanism. If the first line of a script begins with +the two characters `#!', the remainder of the line specifies an +interpreter for the program. Thus, you can specify Bash, `awk', Perl, +or some other interpreter and write the rest of the script file in that +language. + + The arguments to the interpreter consist of a single optional +argument following the interpreter name on the first line of the script +file, followed by the name of the script file, followed by the rest of +the arguments. Bash will perform this action on operating systems that +do not handle it themselves. Note that some older versions of Unix +limit the interpreter name and argument to a maximum of 32 characters. + + Bash scripts often begin with `#! /bin/bash' (assuming that Bash has +been installed in `/bin'), since this ensures that Bash will be used to +interpret the script, even if it is executed under another shell. + + +File: bashref.info, Node: Shell Builtin Commands, Next: Shell Variables, Prev: Basic Shell Features, Up: Top + +4 Shell Builtin Commands +************************ + +* Menu: + +* Bourne Shell Builtins:: Builtin commands inherited from the Bourne + Shell. +* Bash Builtins:: Table of builtins specific to Bash. +* Modifying Shell Behavior:: Builtins to modify shell attributes and + optional behavior. +* Special Builtins:: Builtin commands classified specially by + POSIX. + + Builtin commands are contained within the shell itself. When the +name of a builtin command is used as the first word of a simple command +(*note Simple Commands::), the shell executes the command directly, +without invoking another program. Builtin commands are necessary to +implement functionality impossible or inconvenient to obtain with +separate utilities. + + This section briefly describes the builtins which Bash inherits from +the Bourne Shell, as well as the builtin commands which are unique to +or have been extended in Bash. + + Several builtin commands are described in other chapters: builtin +commands which provide the Bash interface to the job control facilities +(*note Job Control Builtins::), the directory stack (*note Directory +Stack Builtins::), the command history (*note Bash History Builtins::), +and the programmable completion facilities (*note Programmable +Completion Builtins::). + + Many of the builtins have been extended by POSIX or Bash. + + Unless otherwise noted, each builtin command documented as accepting +options preceded by `-' accepts `--' to signify the end of the options. +The `:', `true', `false', and `test' builtins do not accept options and +do not treat `--' specially. The `exit', `logout', `break', +`continue', `let', and `shift' builtins accept and process arguments +beginning with `-' without requiring `--'. Other builtins that accept +arguments but are not specified as accepting options interpret +arguments beginning with `-' as invalid options and require `--' to +prevent this interpretation. + + +File: bashref.info, Node: Bourne Shell Builtins, Next: Bash Builtins, Up: Shell Builtin Commands + +4.1 Bourne Shell Builtins +========================= + +The following shell builtin commands are inherited from the Bourne +Shell. These commands are implemented as specified by the POSIX +standard. + +`: (a colon)' + : [ARGUMENTS] + Do nothing beyond expanding ARGUMENTS and performing redirections. + The return status is zero. + +`. (a period)' + . FILENAME [ARGUMENTS] + Read and execute commands from the FILENAME argument in the + current shell context. If FILENAME does not contain a slash, the + `PATH' variable is used to find FILENAME. When Bash is not in + POSIX mode, the current directory is searched if FILENAME is not + found in `$PATH'. If any ARGUMENTS are supplied, they become the + positional parameters when FILENAME is executed. Otherwise the + positional parameters are unchanged. The return status is the + exit status of the last command executed, or zero if no commands + are executed. If FILENAME is not found, or cannot be read, the + return status is non-zero. This builtin is equivalent to `source'. + +`break' + break [N] + Exit from a `for', `while', `until', or `select' loop. If N is + supplied, the Nth enclosing loop is exited. N must be greater + than or equal to 1. The return status is zero unless N is not + greater than or equal to 1. + +`cd' + cd [-L|-P] [DIRECTORY] + Change the current working directory to DIRECTORY. If DIRECTORY + is not given, the value of the `HOME' shell variable is used. If + the shell variable `CDPATH' exists, it is used as a search path. + If DIRECTORY begins with a slash, `CDPATH' is not used. + + The `-P' option means to not follow symbolic links; symbolic links + are followed by default or with the `-L' option. If DIRECTORY is + `-', it is equivalent to `$OLDPWD'. + + If a non-empty directory name from `CDPATH' is used, or if `-' is + the first argument, and the directory change is successful, the + absolute pathname of the new working directory is written to the + standard output. + + The return status is zero if the directory is successfully changed, + non-zero otherwise. + +`continue' + continue [N] + Resume the next iteration of an enclosing `for', `while', `until', + or `select' loop. If N is supplied, the execution of the Nth + enclosing loop is resumed. N must be greater than or equal to 1. + The return status is zero unless N is not greater than or equal to + 1. + +`eval' + eval [ARGUMENTS] + The arguments are concatenated together into a single command, + which is then read and executed, and its exit status returned as + the exit status of `eval'. If there are no arguments or only + empty arguments, the return status is zero. + +`exec' + exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]] + If COMMAND is supplied, it replaces the shell without creating a + new process. If the `-l' option is supplied, the shell places a + dash at the beginning of the zeroth argument passed to COMMAND. + This is what the `login' program does. The `-c' option causes + COMMAND to be executed with an empty environment. If `-a' is + supplied, the shell passes NAME as the zeroth argument to COMMAND. + If no COMMAND is specified, redirections may be used to affect the + current shell environment. If there are no redirection errors, the + return status is zero; otherwise the return status is non-zero. + +`exit' + exit [N] + Exit the shell, returning a status of N to the shell's parent. If + N is omitted, the exit status is that of the last command executed. + Any trap on `EXIT' is executed before the shell terminates. + +`export' + export [-fn] [-p] [NAME[=VALUE]] + Mark each NAME to be passed to child processes in the environment. + If the `-f' option is supplied, the NAMEs refer to shell + functions; otherwise the names refer to shell variables. The `-n' + option means to no longer mark each NAME for export. If no NAMES + are supplied, or if the `-p' option is given, a list of exported + names is displayed. The `-p' option displays output in a form + that may be reused as input. If a variable name is followed by + =VALUE, the value of the variable is set to VALUE. + + The return status is zero unless an invalid option is supplied, + one of the names is not a valid shell variable name, or `-f' is + supplied with a name that is not a shell function. + +`getopts' + getopts OPTSTRING NAME [ARGS] + `getopts' is used by shell scripts to parse positional parameters. + OPTSTRING contains the option characters to be recognized; if a + character is followed by a colon, the option is expected to have an + argument, which should be separated from it by white space. The + colon (`:') and question mark (`?') may not be used as option + characters. Each time it is invoked, `getopts' places the next + option in the shell variable NAME, initializing NAME if it does + not exist, and the index of the next argument to be processed into + the variable `OPTIND'. `OPTIND' is initialized to 1 each time the + shell or a shell script is invoked. When an option requires an + argument, `getopts' places that argument into the variable + `OPTARG'. The shell does not reset `OPTIND' automatically; it + must be manually reset between multiple calls to `getopts' within + the same shell invocation if a new set of parameters is to be used. + + When the end of options is encountered, `getopts' exits with a + return value greater than zero. `OPTIND' is set to the index of + the first non-option argument, and `name' is set to `?'. + + `getopts' normally parses the positional parameters, but if more + arguments are given in ARGS, `getopts' parses those instead. + + `getopts' can report errors in two ways. If the first character of + OPTSTRING is a colon, SILENT error reporting is used. In normal + operation diagnostic messages are printed when invalid options or + missing option arguments are encountered. If the variable `OPTERR' + is set to 0, no error messages will be displayed, even if the first + character of `optstring' is not a colon. + + If an invalid option is seen, `getopts' places `?' into NAME and, + if not silent, prints an error message and unsets `OPTARG'. If + `getopts' is silent, the option character found is placed in + `OPTARG' and no diagnostic message is printed. + + If a required argument is not found, and `getopts' is not silent, + a question mark (`?') is placed in NAME, `OPTARG' is unset, and a + diagnostic message is printed. If `getopts' is silent, then a + colon (`:') is placed in NAME and `OPTARG' is set to the option + character found. + +`hash' + hash [-r] [-p FILENAME] [-dt] [NAME] + Remember the full pathnames of commands specified as NAME + arguments, so they need not be searched for on subsequent + invocations. The commands are found by searching through the + directories listed in `$PATH'. The `-p' option inhibits the path + search, and FILENAME is used as the location of NAME. The `-r' + option causes the shell to forget all remembered locations. The + `-d' option causes the shell to forget the remembered location of + each NAME. If the `-t' option is supplied, the full pathname to + which each NAME corresponds is printed. If multiple NAME + arguments are supplied with `-t' the NAME is printed before the + hashed full pathname. The `-l' option causes output to be + displayed in a format that may be reused as input. If no + arguments are given, or if only `-l' is supplied, information + about remembered commands is printed. The return status is zero + unless a NAME is not found or an invalid option is supplied. + +`pwd' + pwd [-LP] + Print the absolute pathname of the current working directory. If + the `-P' option is supplied, the pathname printed will not contain + symbolic links. If the `-L' option is supplied, the pathname + printed may contain symbolic links. The return status is zero + unless an error is encountered while determining the name of the + current directory or an invalid option is supplied. + +`readonly' + readonly [-aApf] [NAME[=VALUE]] ... + Mark each NAME as readonly. The values of these names may not be + changed by subsequent assignment. If the `-f' option is supplied, + each NAME refers to a shell function. The `-a' option means each + NAME refers to an indexed array variable; the `-A' option means + each NAME refers to an associative array variable. If no NAME + arguments are given, or if the `-p' option is supplied, a list of + all readonly names is printed. The `-p' option causes output to + be displayed in a format that may be reused as input. If a + variable name is followed by =VALUE, the value of the variable is + set to VALUE. The return status is zero unless an invalid option + is supplied, one of the NAME arguments is not a valid shell + variable or function name, or the `-f' option is supplied with a + name that is not a shell function. + +`return' + return [N] + Cause a shell function to exit with the return value N. If N is + not supplied, the return value is the exit status of the last + command executed in the function. This may also be used to + terminate execution of a script being executed with the `.' (or + `source') builtin, returning either N or the exit status of the + last command executed within the script as the exit status of the + script. Any command associated with the `RETURN' trap is executed + before execution resumes after the function or script. The return + status is non-zero if `return' is used outside a function and not + during the execution of a script by `.' or `source'. + +`shift' + shift [N] + Shift the positional parameters to the left by N. The positional + parameters from N+1 ... `$#' are renamed to `$1' ... `$#'-N. + Parameters represented by the numbers `$#' to `$#'-N+1 are unset. + N must be a non-negative number less than or equal to `$#'. If N + is zero or greater than `$#', the positional parameters are not + changed. If N is not supplied, it is assumed to be 1. The return + status is zero unless N is greater than `$#' or less than zero, + non-zero otherwise. + +`test' +`[' + Evaluate a conditional expression EXPR. Each operator and operand + must be a separate argument. Expressions are composed of the + primaries described below in *note Bash Conditional Expressions::. + `test' does not accept any options, nor does it accept and ignore + an argument of `--' as signifying the end of options. + + When the `[' form is used, the last argument to the command must + be a `]'. + + Expressions may be combined using the following operators, listed + in decreasing order of precedence. The evaluation depends on the + number of arguments; see below. + + `! EXPR' + True if EXPR is false. + + `( EXPR )' + Returns the value of EXPR. This may be used to override the + normal precedence of operators. + + `EXPR1 -a EXPR2' + True if both EXPR1 and EXPR2 are true. + + `EXPR1 -o EXPR2' + True if either EXPR1 or EXPR2 is true. + + The `test' and `[' builtins evaluate conditional expressions using + a set of rules based on the number of arguments. + + 0 arguments + The expression is false. + + 1 argument + The expression is true if and only if the argument is not + null. + + 2 arguments + If the first argument is `!', the expression is true if and + only if the second argument is null. If the first argument + is one of the unary conditional operators (*note Bash + Conditional Expressions::), the expression is true if the + unary test is true. If the first argument is not a valid + unary operator, the expression is false. + + 3 arguments + If the second argument is one of the binary conditional + operators (*note Bash Conditional Expressions::), the result + of the expression is the result of the binary test using the + first and third arguments as operands. The `-a' and `-o' + operators are considered binary operators when there are + three arguments. If the first argument is `!', the value is + the negation of the two-argument test using the second and + third arguments. If the first argument is exactly `(' and + the third argument is exactly `)', the result is the + one-argument test of the second argument. Otherwise, the + expression is false. + + 4 arguments + If the first argument is `!', the result is the negation of + the three-argument expression composed of the remaining + arguments. Otherwise, the expression is parsed and evaluated + according to precedence using the rules listed above. + + 5 or more arguments + The expression is parsed and evaluated according to precedence + using the rules listed above. + +`times' + times + Print out the user and system times used by the shell and its + children. The return status is zero. + +`trap' + trap [-lp] [ARG] [SIGSPEC ...] + The commands in ARG are to be read and executed when the shell + receives signal SIGSPEC. If ARG is absent (and there is a single + SIGSPEC) or equal to `-', each specified signal's disposition is + reset to the value it had when the shell was started. If ARG is + the null string, then the signal specified by each SIGSPEC is + ignored by the shell and commands it invokes. If ARG is not + present and `-p' has been supplied, the shell displays the trap + commands associated with each SIGSPEC. If no arguments are + supplied, or only `-p' is given, `trap' prints the list of commands + associated with each signal number in a form that may be reused as + shell input. The `-l' option causes the shell to print a list of + signal names and their corresponding numbers. Each SIGSPEC is + either a signal name or a signal number. Signal names are case + insensitive and the `SIG' prefix is optional. + + If a SIGSPEC is `0' or `EXIT', ARG is executed when the shell + exits. If a SIGSPEC is `DEBUG', the command ARG is executed + before every simple command, `for' command, `case' command, + `select' command, every arithmetic `for' command, and before the + first command executes in a shell function. Refer to the + description of the `extdebug' option to the `shopt' builtin (*note + The Shopt Builtin::) for details of its effect on the `DEBUG' trap. + If a SIGSPEC is `RETURN', the command ARG is executed each time a + shell function or a script executed with the `.' or `source' + builtins finishes executing. + + If a SIGSPEC is `ERR', the command ARG is executed whenever a + simple command has a non-zero exit status, subject to the + following conditions. The `ERR' trap is not executed if the + failed command is part of the command list immediately following + an `until' or `while' keyword, part of the test following the `if' + or `elif' reserved words, part of a command executed in a `&&' or + `||' list, or if the command's return status is being inverted + using `!'. These are the same conditions obeyed by the `errexit' + option. + + Signals ignored upon entry to the shell cannot be trapped or reset. + Trapped signals that are not being ignored are reset to their + original values in a subshell or subshell environment when one is + created. + + The return status is zero unless a SIGSPEC does not specify a + valid signal. + +`umask' + umask [-p] [-S] [MODE] + Set the shell process's file creation mask to MODE. If MODE + begins with a digit, it is interpreted as an octal number; if not, + it is interpreted as a symbolic mode mask similar to that accepted + by the `chmod' command. If MODE is omitted, the current value of + the mask is printed. If the `-S' option is supplied without a + MODE argument, the mask is printed in a symbolic format. If the + `-p' option is supplied, and MODE is omitted, the output is in a + form that may be reused as input. The return status is zero if + the mode is successfully changed or if no MODE argument is + supplied, and non-zero otherwise. + + Note that when the mode is interpreted as an octal number, each + number of the umask is subtracted from `7'. Thus, a umask of `022' + results in permissions of `755'. + +`unset' + unset [-fv] [NAME] + Each variable or function NAME is removed. If no options are + supplied, or the `-v' option is given, each NAME refers to a shell + variable. If the `-f' option is given, the NAMEs refer to shell + functions, and the function definition is removed. Readonly + variables and functions may not be unset. The return status is + zero unless a NAME is readonly. + + +File: bashref.info, Node: Bash Builtins, Next: Modifying Shell Behavior, Prev: Bourne Shell Builtins, Up: Shell Builtin Commands + +4.2 Bash Builtin Commands +========================= + +This section describes builtin commands which are unique to or have +been extended in Bash. Some of these commands are specified in the +POSIX standard. + +`alias' + alias [`-p'] [NAME[=VALUE] ...] + + Without arguments or with the `-p' option, `alias' prints the list + of aliases on the standard output in a form that allows them to be + reused as input. If arguments are supplied, an alias is defined + for each NAME whose VALUE is given. If no VALUE is given, the name + and value of the alias is printed. Aliases are described in *note + Aliases::. + +`bind' + bind [-m KEYMAP] [-lpsvPSV] + bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ] + bind [-m KEYMAP] -f FILENAME + bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND + bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME + bind READLINE-COMMAND + + Display current Readline (*note Command Line Editing::) key and + function bindings, bind a key sequence to a Readline function or + macro, or set a Readline variable. Each non-option argument is a + command as it would appear in a Readline initialization file + (*note Readline Init File::), but each binding or command must be + passed as a separate argument; e.g., + `"\C-x\C-r":re-read-init-file'. + + Options, if supplied, have the following meanings: + + `-m KEYMAP' + Use KEYMAP as the keymap to be affected by the subsequent + bindings. Acceptable KEYMAP names are `emacs', + `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', + `vi-command', and `vi-insert'. `vi' is equivalent to + `vi-command'; `emacs' is equivalent to `emacs-standard'. + + `-l' + List the names of all Readline functions. + + `-p' + Display Readline function names and bindings in such a way + that they can be used as input or in a Readline + initialization file. + + `-P' + List current Readline function names and bindings. + + `-v' + Display Readline variable names and values in such a way that + they can be used as input or in a Readline initialization + file. + + `-V' + List current Readline variable names and values. + + `-s' + Display Readline key sequences bound to macros and the + strings they output in such a way that they can be used as + input or in a Readline initialization file. + + `-S' + Display Readline key sequences bound to macros and the + strings they output. + + `-f FILENAME' + Read key bindings from FILENAME. + + `-q FUNCTION' + Query about which keys invoke the named FUNCTION. + + `-u FUNCTION' + Unbind all keys bound to the named FUNCTION. + + `-r KEYSEQ' + Remove any current binding for KEYSEQ. + + `-x KEYSEQ:SHELL-COMMAND' + Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered. + When SHELL-COMMAND is executed, the shell sets the + `READLINE_LINE' variable to the contents of the Readline line + buffer and the `READLINE_POINT' variable to the current + location of the insertion point. If the executed command + changes the value of `READLINE_LINE' or `READLINE_POINT', + those new values will be reflected in the editing state. + + The return status is zero unless an invalid option is supplied or + an error occurs. + +`builtin' + builtin [SHELL-BUILTIN [ARGS]] + Run a shell builtin, passing it ARGS, and return its exit status. + This is useful when defining a shell function with the same name + as a shell builtin, retaining the functionality of the builtin + within the function. The return status is non-zero if + SHELL-BUILTIN is not a shell builtin command. + +`caller' + caller [EXPR] + Returns the context of any active subroutine call (a shell + function or a script executed with the `.' or `source' builtins). + + Without EXPR, `caller' displays the line number and source + filename of the current subroutine call. If a non-negative + integer is supplied as EXPR, `caller' displays the line number, + subroutine name, and source file corresponding to that position in + the current execution call stack. This extra information may be + used, for example, to print a stack trace. The current frame is + frame 0. + + The return value is 0 unless the shell is not executing a + subroutine call or EXPR does not correspond to a valid position in + the call stack. + +`command' + command [-pVv] COMMAND [ARGUMENTS ...] + Runs COMMAND with ARGUMENTS ignoring any shell function named + COMMAND. Only shell builtin commands or commands found by + searching the `PATH' are executed. If there is a shell function + named `ls', running `command ls' within the function will execute + the external command `ls' instead of calling the function + recursively. The `-p' option means to use a default value for + `PATH' that is guaranteed to find all of the standard utilities. + The return status in this case is 127 if COMMAND cannot be found + or an error occurred, and the exit status of COMMAND otherwise. + + If either the `-V' or `-v' option is supplied, a description of + COMMAND is printed. The `-v' option causes a single word + indicating the command or file name used to invoke COMMAND to be + displayed; the `-V' option produces a more verbose description. + In this case, the return status is zero if COMMAND is found, and + non-zero if not. + +`declare' + declare [-aAfFilrtux] [-p] [NAME[=VALUE] ...] + + Declare variables and give them attributes. If no NAMEs are + given, then display the values of variables instead. + + The `-p' option will display the attributes and values of each + NAME. When `-p' is used with NAME arguments, additional options + are ignored. + + When `-p' is supplied without NAME arguments, `declare' will + display the attributes and values of all variables having the + attributes specified by the additional options. If no other + options are supplied with `-p', `declare' will display the + attributes and values of all shell variables. The `-f' option + will restrict the display to shell functions. + + The `-F' option inhibits the display of function definitions; only + the function name and attributes are printed. If the `extdebug' + shell option is enabled using `shopt' (*note The Shopt Builtin::), + the source file name and line number where the function is defined + are displayed as well. `-F' implies `-f'. The following options + can be used to restrict output to variables with the specified + attributes or to give variables attributes: + + `-a' + Each NAME is an indexed array variable (*note Arrays::). + + `-A' + Each NAME is an associative array variable (*note Arrays::). + + `-f' + Use function names only. + + `-i' + The variable is to be treated as an integer; arithmetic + evaluation (*note Shell Arithmetic::) is performed when the + variable is assigned a value. + + `-l' + When the variable is assigned a value, all upper-case + characters are converted to lower-case. The upper-case + attribute is disabled. + + `-r' + Make NAMEs readonly. These names cannot then be assigned + values by subsequent assignment statements or unset. + + `-t' + Give each NAME the `trace' attribute. Traced functions + inherit the `DEBUG' and `RETURN' traps from the calling shell. + The trace attribute has no special meaning for variables. + + `-u' + When the variable is assigned a value, all lower-case + characters are converted to upper-case. The lower-case + attribute is disabled. + + `-x' + Mark each NAME for export to subsequent commands via the + environment. + + Using `+' instead of `-' turns off the attribute instead, with the + exceptions that `+a' may not be used to destroy an array variable + and `+r' will not remove the readonly attribute. When used in a + function, `declare' makes each NAME local, as with the `local' + command. If a variable name is followed by =VALUE, the value of + the variable is set to VALUE. + + The return status is zero unless an invalid option is encountered, + an attempt is made to define a function using `-f foo=bar', an + attempt is made to assign a value to a readonly variable, an + attempt is made to assign a value to an array variable without + using the compound assignment syntax (*note Arrays::), one of the + NAMES is not a valid shell variable name, an attempt is made to + turn off readonly status for a readonly variable, an attempt is + made to turn off array status for an array variable, or an attempt + is made to display a non-existent function with `-f'. + +`echo' + echo [-neE] [ARG ...] + Output the ARGs, separated by spaces, terminated with a newline. + The return status is always 0. If `-n' is specified, the trailing + newline is suppressed. If the `-e' option is given, + interpretation of the following backslash-escaped characters is + enabled. The `-E' option disables the interpretation of these + escape characters, even on systems where they are interpreted by + default. The `xpg_echo' shell option may be used to dynamically + determine whether or not `echo' expands these escape characters by + default. `echo' does not interpret `--' to mean the end of + options. + + `echo' interprets the following escape sequences: + `\a' + alert (bell) + + `\b' + backspace + + `\c' + suppress further output + + `\e' + escape + + `\f' + form feed + + `\n' + new line + + `\r' + carriage return + + `\t' + horizontal tab + + `\v' + vertical tab + + `\\' + backslash + + `\0NNN' + the eight-bit character whose value is the octal value NNN + (zero to three octal digits) + + `\xHH' + the eight-bit character whose value is the hexadecimal value + HH (one or two hex digits) + +`enable' + enable [-a] [-dnps] [-f FILENAME] [NAME ...] + Enable and disable builtin shell commands. Disabling a builtin + allows a disk command which has the same name as a shell builtin + to be executed without specifying a full pathname, even though the + shell normally searches for builtins before disk commands. If + `-n' is used, the NAMEs become disabled. Otherwise NAMEs are + enabled. For example, to use the `test' binary found via `$PATH' + instead of the shell builtin version, type `enable -n test'. + + If the `-p' option is supplied, or no NAME arguments appear, a + list of shell builtins is printed. With no other arguments, the + list consists of all enabled shell builtins. The `-a' option + means to list each builtin with an indication of whether or not it + is enabled. + + The `-f' option means to load the new builtin command NAME from + shared object FILENAME, on systems that support dynamic loading. + The `-d' option will delete a builtin loaded with `-f'. + + If there are no options, a list of the shell builtins is displayed. + The `-s' option restricts `enable' to the POSIX special builtins. + If `-s' is used with `-f', the new builtin becomes a special + builtin (*note Special Builtins::). + + The return status is zero unless a NAME is not a shell builtin or + there is an error loading a new builtin from a shared object. + +`help' + help [-dms] [PATTERN] + Display helpful information about builtin commands. If PATTERN is + specified, `help' gives detailed help on all commands matching + PATTERN, otherwise a list of the builtins is printed. + + Options, if supplied, have the following meanings: + + `-d' + Display a short description of each PATTERN + + `-m' + Display the description of each PATTERN in a manpage-like + format + + `-s' + Display only a short usage synopsis for each PATTERN + + The return status is zero unless no command matches PATTERN. + +`let' + let EXPRESSION [EXPRESSION] + The `let' builtin allows arithmetic to be performed on shell + variables. Each EXPRESSION is evaluated according to the rules + given below in *note Shell Arithmetic::. If the last EXPRESSION + evaluates to 0, `let' returns 1; otherwise 0 is returned. + +`local' + local [OPTION] NAME[=VALUE] ... + For each argument, a local variable named NAME is created, and + assigned VALUE. The OPTION can be any of the options accepted by + `declare'. `local' can only be used within a function; it makes + the variable NAME have a visible scope restricted to that function + and its children. The return status is zero unless `local' is + used outside a function, an invalid NAME is supplied, or NAME is a + readonly variable. + +`logout' + logout [N] + Exit a login shell, returning a status of N to the shell's parent. + +`mapfile' + mapfile [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] [ + -C CALLBACK] [-c QUANTUM] [ARRAY] + Read lines from the standard input into the indexed array variable + ARRAY, or from file descriptor FD if the `-u' option is supplied. + The variable `MAPFILE' is the default ARRAY. Options, if + supplied, have the following meanings: + `-n' + Copy at most COUNT lines. If COUNT is 0, all lines are + copied. + + `-O' + Begin assigning to ARRAY at index ORIGIN. The default index + is 0. + + `-s' + Discard the first COUNT lines read. + + `-t' + Remove a trailing newline from each line read. + + `-u' + Read lines from file descriptor FD instead of the standard + input. + + `-C' + Evaluate CALLBACK each time QUANTUMP lines are read. The + `-c' option specifies QUANTUM. + + `-c' + Specify the number of lines read between each call to + CALLBACK. + + If `-C' is specified without `-c', the default quantum is 5000. + When CALLBACK is evaluated, it is supplied the index of the next + array element to be assigned as an additional argument. CALLBACK + is evaluated after the line is read but before the array element + is assigned. + + If not supplied with an explicit origin, `mapfile' will clear ARRAY + before assigning to it. + + `mapfile' returns successfully unless an invalid option or option + argument is supplied, ARRAY is invalid or unassignable, or ARRAY + is not an indexed array. + +`printf' + printf [-v VAR] FORMAT [ARGUMENTS] + Write the formatted ARGUMENTS to the standard output under the + control of the FORMAT. The FORMAT is a character string which + contains three types of objects: plain characters, which are + simply copied to standard output, character escape sequences, + which are converted and copied to the standard output, and format + specifications, each of which causes printing of the next + successive ARGUMENT. In addition to the standard `printf(1)' + formats, `%b' causes `printf' to expand backslash escape sequences + in the corresponding ARGUMENT, (except that `\c' terminates + output, backslashes in `\'', `\"', and `\?' are not removed, and + octal escapes beginning with `\0' may contain up to four digits), + and `%q' causes `printf' to output the corresponding ARGUMENT in a + format that can be reused as shell input. + + The `-v' option causes the output to be assigned to the variable + VAR rather than being printed to the standard output. + + The FORMAT is reused as necessary to consume all of the ARGUMENTS. + If the FORMAT requires more ARGUMENTS than are supplied, the extra + format specifications behave as if a zero value or null string, as + appropriate, had been supplied. The return value is zero on + success, non-zero on failure. + +`read' + read [-ers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS] [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...] + One line is read from the standard input, or from the file + descriptor FD supplied as an argument to the `-u' option, and the + first word is assigned to the first NAME, the second word to the + second NAME, and so on, with leftover words and their intervening + separators assigned to the last NAME. If there are fewer words + read from the input stream than names, the remaining names are + assigned empty values. The characters in the value of the `IFS' + variable are used to split the line into words. The backslash + character `\' may be used to remove any special meaning for the + next character read and for line continuation. If no names are + supplied, the line read is assigned to the variable `REPLY'. The + return code is zero, unless end-of-file is encountered, `read' + times out (in which case the return code is greater than 128), or + an invalid file descriptor is supplied as the argument to `-u'. + + Options, if supplied, have the following meanings: + + `-a ANAME' + The words are assigned to sequential indices of the array + variable ANAME, starting at 0. All elements are removed from + ANAME before the assignment. Other NAME arguments are + ignored. + + `-d DELIM' + The first character of DELIM is used to terminate the input + line, rather than newline. + + `-e' + Readline (*note Command Line Editing::) is used to obtain the + line. Readline uses the current (or default, if line editing + was not previously active) editing settings. + + `-i TEXT' + If Readline is being used to read the line, TEXT is placed + into the editing buffer before editing begins. + + `-n NCHARS' + `read' returns after reading NCHARS characters rather than + waiting for a complete line of input, but honor a delimiter + if fewer than NCHARS characters are read before the delimiter. + + `-N NCHARS' + `read' returns after reading exactly NCHARS characters rather + than waiting for a complete line of input, unless EOF is + encountered or `read' times out. Delimiter characters + encountered in the input are not treated specially and do not + cause `read' to return until NCHARS characters are read. + + `-p PROMPT' + Display PROMPT, without a trailing newline, before attempting + to read any input. The prompt is displayed only if input is + coming from a terminal. + + `-r' + If this option is given, backslash does not act as an escape + character. The backslash is considered to be part of the + line. In particular, a backslash-newline pair may not be + used as a line continuation. + + `-s' + Silent mode. If input is coming from a terminal, characters + are not echoed. + + `-t TIMEOUT' + Cause `read' to time out and return failure if a complete + line of input is not read within TIMEOUT seconds. TIMEOUT + may be a decimal number with a fractional portion following + the decimal point. This option is only effective if `read' + is reading input from a terminal, pipe, or other special + file; it has no effect when reading from regular files. If + TIMEOUT is 0, `read' returns success if input is available on + the specified file descriptor, failure otherwise. The exit + status is greater than 128 if the timeout is exceeded. + + `-u FD' + Read input from file descriptor FD. + + +`readarray' + readarray [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] [ + -C CALLBACK] [-c QUANTUM] [ARRAY] + Read lines from the standard input into the indexed array variable + ARRAY, or from file descriptor FD if the `-u' option is supplied. + + A synonym for `mapfile'. + +`source' + source FILENAME + A synonym for `.' (*note Bourne Shell Builtins::). + +`type' + type [-afptP] [NAME ...] + For each NAME, indicate how it would be interpreted if used as a + command name. + + If the `-t' option is used, `type' prints a single word which is + one of `alias', `function', `builtin', `file' or `keyword', if + NAME is an alias, shell function, shell builtin, disk file, or + shell reserved word, respectively. If the NAME is not found, then + nothing is printed, and `type' returns a failure status. + + If the `-p' option is used, `type' either returns the name of the + disk file that would be executed, or nothing if `-t' would not + return `file'. + + The `-P' option forces a path search for each NAME, even if `-t' + would not return `file'. + + If a command is hashed, `-p' and `-P' print the hashed value, not + necessarily the file that appears first in `$PATH'. + + If the `-a' option is used, `type' returns all of the places that + contain an executable named FILE. This includes aliases and + functions, if and only if the `-p' option is not also used. + + If the `-f' option is used, `type' does not attempt to find shell + functions, as with the `command' builtin. + + The return status is zero if all of the NAMES are found, non-zero + if any are not found. + +`typeset' + typeset [-afFrxi] [-p] [NAME[=VALUE] ...] + The `typeset' command is supplied for compatibility with the Korn + shell; however, it has been deprecated in favor of the `declare' + builtin command. + +`ulimit' + ulimit [-abcdefilmnpqrstuvxHST] [LIMIT] + `ulimit' provides control over the resources available to processes + started by the shell, on systems that allow such control. If an + option is given, it is interpreted as follows: + `-S' + Change and report the soft limit associated with a resource. + + `-H' + Change and report the hard limit associated with a resource. + + `-a' + All current limits are reported. + + `-b' + The maximum socket buffer size. + + `-c' + The maximum size of core files created. + + `-d' + The maximum size of a process's data segment. + + `-e' + The maximum scheduling priority ("nice"). + + `-f' + The maximum size of files written by the shell and its + children. + + `-i' + The maximum number of pending signals. + + `-l' + The maximum size that may be locked into memory. + + `-m' + The maximum resident set size (many systems do not honor this + limit). + + `-n' + The maximum number of open file descriptors (most systems do + not allow this value to be set). + + `-p' + The pipe buffer size. + + `-q' + The maximum number of bytes in POSIX message queues. + + `-r' + The maximum real-time scheduling priority. + + `-s' + The maximum stack size. + + `-t' + The maximum amount of cpu time in seconds. + + `-u' + The maximum number of processes available to a single user. + + `-v' + The maximum amount of virtual memory available to the process. + + `-x' + The maximum number of file locks. + + `-T' + The maximum number of threads. + + + If LIMIT is given, it is the new value of the specified resource; + the special LIMIT values `hard', `soft', and `unlimited' stand for + the current hard limit, the current soft limit, and no limit, + respectively. A hard limit cannot be increased by a non-root user + once it is set; a soft limit may be increased up to the value of + the hard limit. Otherwise, the current value of the soft limit + for the specified resource is printed, unless the `-H' option is + supplied. When setting new limits, if neither `-H' nor `-S' is + supplied, both the hard and soft limits are set. If no option is + given, then `-f' is assumed. Values are in 1024-byte increments, + except for `-t', which is in seconds, `-p', which is in units of + 512-byte blocks, and `-n' and `-u', which are unscaled values. + + The return status is zero unless an invalid option or argument is + supplied, or an error occurs while setting a new limit. + +`unalias' + unalias [-a] [NAME ... ] + + Remove each NAME from the list of aliases. If `-a' is supplied, + all aliases are removed. Aliases are described in *note Aliases::. + + + +File: bashref.info, Node: Modifying Shell Behavior, Next: Special Builtins, Prev: Bash Builtins, Up: Shell Builtin Commands + +4.3 Modifying Shell Behavior +============================ + +* Menu: + +* The Set Builtin:: Change the values of shell attributes and + positional parameters. +* The Shopt Builtin:: Modify shell optional behavior. + + +File: bashref.info, Node: The Set Builtin, Next: The Shopt Builtin, Up: Modifying Shell Behavior + +4.3.1 The Set Builtin +--------------------- + +This builtin is so complicated that it deserves its own section. `set' +allows you to change the values of shell options and set the positional +parameters, or to display the names and values of shell variables. + +`set' + set [--abefhkmnptuvxBCEHPT] [-o OPTION] [ARGUMENT ...] + set [+abefhkmnptuvxBCEHPT] [+o OPTION] [ARGUMENT ...] + + If no options or arguments are supplied, `set' displays the names + and values of all shell variables and functions, sorted according + to the current locale, in a format that may be reused as input for + setting or resetting the currently-set variables. Read-only + variables cannot be reset. In POSIX mode, only shell variables + are listed. + + When options are supplied, they set or unset shell attributes. + Options, if specified, have the following meanings: + + `-a' + Mark variables and function which are modified or created for + export to the environment of subsequent commands. + + `-b' + Cause the status of terminated background jobs to be reported + immediately, rather than before printing the next primary + prompt. + + `-e' + Exit immediately if a pipeline (*note Pipelines::), which may + consist of a single simple command (*note Simple Commands::), + a subshell command enclosed in parentheses (*note Command + Grouping::), or one of the commands executed as part of a + command list enclosed by braces (*note Command Grouping::) + returns a non-zero status. The shell does not exit if the + command that fails is part of the command list immediately + following a `while' or `until' keyword, part of the test in + an `if' statement, part of any command executed in a `&&' or + `||' list except the command following the final `&&' or `||', + any command in a pipeline but the last, or if the command's + return status is being inverted with `!'. A trap on `ERR', + if set, is executed before the shell exits. + + This option applies to the shell environment and each + subshell environment separately (*note Command Execution + Environment::), and may cause subshells to exit before + executing all the commands in the subshell. + + `-f' + Disable filename expansion (globbing). + + `-h' + Locate and remember (hash) commands as they are looked up for + execution. This option is enabled by default. + + `-k' + All arguments in the form of assignment statements are placed + in the environment for a command, not just those that precede + the command name. + + `-m' + Job control is enabled (*note Job Control::). + + `-n' + Read commands but do not execute them; this may be used to + check a script for syntax errors. This option is ignored by + interactive shells. + + `-o OPTION-NAME' + Set the option corresponding to OPTION-NAME: + + `allexport' + Same as `-a'. + + `braceexpand' + Same as `-B'. + + `emacs' + Use an `emacs'-style line editing interface (*note + Command Line Editing::). This also affects the editing + interface used for `read -e'. + + `errexit' + Same as `-e'. + + `errtrace' + Same as `-E'. + + `functrace' + Same as `-T'. + + `hashall' + Same as `-h'. + + `histexpand' + Same as `-H'. + + `history' + Enable command history, as described in *note Bash + History Facilities::. This option is on by default in + interactive shells. + + `ignoreeof' + An interactive shell will not exit upon reading EOF. + + `keyword' + Same as `-k'. + + `monitor' + Same as `-m'. + + `noclobber' + Same as `-C'. + + `noexec' + Same as `-n'. + + `noglob' + Same as `-f'. + + `nolog' + Currently ignored. + + `notify' + Same as `-b'. + + `nounset' + Same as `-u'. + + `onecmd' + Same as `-t'. + + `physical' + Same as `-P'. + + `pipefail' + If set, the return value of a pipeline is the value of + the last (rightmost) command to exit with a non-zero + status, or zero if all commands in the pipeline exit + successfully. This option is disabled by default. + + `posix' + Change the behavior of Bash where the default operation + differs from the POSIX standard to match the standard + (*note Bash POSIX Mode::). This is intended to make + Bash behave as a strict superset of that standard. + + `privileged' + Same as `-p'. + + `verbose' + Same as `-v'. + + `vi' + Use a `vi'-style line editing interface. This also + affects the editing interface used for `read -e'. + + `xtrace' + Same as `-x'. + + `-p' + Turn on privileged mode. In this mode, the `$BASH_ENV' and + `$ENV' files are not processed, shell functions are not + inherited from the environment, and the `SHELLOPTS', + `BASHOPTS', `CDPATH' and `GLOBIGNORE' variables, if they + appear in the environment, are ignored. If the shell is + started with the effective user (group) id not equal to the + real user (group) id, and the `-p' option is not supplied, + these actions are taken and the effective user id is set to + the real user id. If the `-p' option is supplied at startup, + the effective user id is not reset. Turning this option off + causes the effective user and group ids to be set to the real + user and group ids. + + `-t' + Exit after reading and executing one command. + + `-u' + Treat unset variables and parameters other than the special + parameters `@' or `*' as an error when performing parameter + expansion. An error message will be written to the standard + error, and a non-interactive shell will exit. + + `-v' + Print shell input lines as they are read. + + `-x' + Print a trace of simple commands, `for' commands, `case' + commands, `select' commands, and arithmetic `for' commands + and their arguments or associated word lists after they are + expanded and before they are executed. The value of the `PS4' + variable is expanded and the resultant value is printed before + the command and its expanded arguments. + + `-B' + The shell will perform brace expansion (*note Brace + Expansion::). This option is on by default. + + `-C' + Prevent output redirection using `>', `>&', and `<>' from + overwriting existing files. + + `-E' + If set, any trap on `ERR' is inherited by shell functions, + command substitutions, and commands executed in a subshell + environment. The `ERR' trap is normally not inherited in + such cases. + + `-H' + Enable `!' style history substitution (*note History + Interaction::). This option is on by default for interactive + shells. + + `-P' + If set, do not follow symbolic links when performing commands + such as `cd' which change the current directory. The + physical directory is used instead. By default, Bash follows + the logical chain of directories when performing commands + which change the current directory. + + For example, if `/usr/sys' is a symbolic link to + `/usr/local/sys' then: + $ cd /usr/sys; echo $PWD + /usr/sys + $ cd ..; pwd + /usr + + If `set -P' is on, then: + $ cd /usr/sys; echo $PWD + /usr/local/sys + $ cd ..; pwd + /usr/local + + `-T' + If set, any trap on `DEBUG' and `RETURN' are inherited by + shell functions, command substitutions, and commands executed + in a subshell environment. The `DEBUG' and `RETURN' traps + are normally not inherited in such cases. + + `--' + If no arguments follow this option, then the positional + parameters are unset. Otherwise, the positional parameters + are set to the ARGUMENTS, even if some of them begin with a + `-'. + + `-' + Signal the end of options, cause all remaining ARGUMENTS to + be assigned to the positional parameters. The `-x' and `-v' + options are turned off. If there are no arguments, the + positional parameters remain unchanged. + + Using `+' rather than `-' causes these options to be turned off. + The options can also be used upon invocation of the shell. The + current set of options may be found in `$-'. + + The remaining N ARGUMENTS are positional parameters and are + assigned, in order, to `$1', `$2', ... `$N'. The special + parameter `#' is set to N. + + The return status is always zero unless an invalid option is + supplied. + + +File: bashref.info, Node: The Shopt Builtin, Prev: The Set Builtin, Up: Modifying Shell Behavior + +4.3.2 The Shopt Builtin +----------------------- + +This builtin allows you to change additional shell optional behavior. + +`shopt' + shopt [-pqsu] [-o] [OPTNAME ...] + Toggle the values of variables controlling optional shell behavior. + With no options, or with the `-p' option, a list of all settable + options is displayed, with an indication of whether or not each is + set. The `-p' option causes output to be displayed in a form that + may be reused as input. Other options have the following meanings: + + `-s' + Enable (set) each OPTNAME. + + `-u' + Disable (unset) each OPTNAME. + + `-q' + Suppresses normal output; the return status indicates whether + the OPTNAME is set or unset. If multiple OPTNAME arguments + are given with `-q', the return status is zero if all + OPTNAMES are enabled; non-zero otherwise. + + `-o' + Restricts the values of OPTNAME to be those defined for the + `-o' option to the `set' builtin (*note The Set Builtin::). + + If either `-s' or `-u' is used with no OPTNAME arguments, the + display is limited to those options which are set or unset, + respectively. + + Unless otherwise noted, the `shopt' options are disabled (off) by + default. + + The return status when listing options is zero if all OPTNAMES are + enabled, non-zero otherwise. When setting or unsetting options, + the return status is zero unless an OPTNAME is not a valid shell + option. + + The list of `shopt' options is: + `autocd' + If set, a command name that is the name of a directory is + executed as if it were the argument to the `cd' command. + This option is only used by interactive shells. + + `cdable_vars' + If this is set, an argument to the `cd' builtin command that + is not a directory is assumed to be the name of a variable + whose value is the directory to change to. + + `cdspell' + If set, minor errors in the spelling of a directory component + in a `cd' command will be corrected. The errors checked for + are transposed characters, a missing character, and a + character too many. If a correction is found, the corrected + path is printed, and the command proceeds. This option is + only used by interactive shells. + + `checkhash' + If this is set, Bash checks that a command found in the hash + table exists before trying to execute it. If a hashed + command no longer exists, a normal path search is performed. + + `checkjobs' + If set, Bash lists the status of any stopped and running jobs + before exiting an interactive shell. If any jobs are + running, this causes the exit to be deferred until a second + exit is attempted without an intervening command (*note Job + Control::). The shell always postpones exiting if any jobs + are stopped. + + `checkwinsize' + If set, Bash checks the window size after each command and, + if necessary, updates the values of `LINES' and `COLUMNS'. + + `cmdhist' + If set, Bash attempts to save all lines of a multiple-line + command in the same history entry. This allows easy + re-editing of multi-line commands. + + `compat31' + If set, Bash changes its behavior to that of version 3.1 with + respect to quoted arguments to the conditional command's =~ + operator. + + `dirspell' + If set, Bash attempts spelling correction on directory names + during word completion if the directory name initially + supplied does not exist. + + `dotglob' + If set, Bash includes filenames beginning with a `.' in the + results of filename expansion. + + `execfail' + If this is set, a non-interactive shell will not exit if it + cannot execute the file specified as an argument to the `exec' + builtin command. An interactive shell does not exit if `exec' + fails. + + `expand_aliases' + If set, aliases are expanded as described below under Aliases, + *note Aliases::. This option is enabled by default for + interactive shells. + + `extdebug' + If set, behavior intended for use by debuggers is enabled: + + 1. The `-F' option to the `declare' builtin (*note Bash + Builtins::) displays the source file name and line + number corresponding to each function name supplied as + an argument. + + 2. If the command run by the `DEBUG' trap returns a + non-zero value, the next command is skipped and not + executed. + + 3. If the command run by the `DEBUG' trap returns a value + of 2, and the shell is executing in a subroutine (a + shell function or a shell script executed by the `.' or + `source' builtins), a call to `return' is simulated. + + 4. `BASH_ARGC' and `BASH_ARGV' are updated as described in + their descriptions (*note Bash Variables::). + + 5. Function tracing is enabled: command substitution, + shell functions, and subshells invoked with `( COMMAND + )' inherit the `DEBUG' and `RETURN' traps. + + 6. Error tracing is enabled: command substitution, shell + functions, and subshells invoked with `( COMMAND )' + inherit the `ERROR' trap. + + `extglob' + If set, the extended pattern matching features described above + (*note Pattern Matching::) are enabled. + + `extquote' + If set, `$'STRING'' and `$"STRING"' quoting is performed + within `${PARAMETER}' expansions enclosed in double quotes. + This option is enabled by default. + + `failglob' + If set, patterns which fail to match filenames during + filename expansion result in an expansion error. + + `force_fignore' + If set, the suffixes specified by the `FIGNORE' shell variable + cause words to be ignored when performing word completion + even if the ignored words are the only possible completions. + *Note Bash Variables::, for a description of `FIGNORE'. This + option is enabled by default. + + `globstar' + If set, the pattern `**' used in a filename expansion context + will match a files and zero or more directories and + subdirectories. If the pattern is followed by a `/', only + directories and subdirectories match. + + `gnu_errfmt' + If set, shell error messages are written in the standard GNU + error message format. + + `histappend' + If set, the history list is appended to the file named by the + value of the `HISTFILE' variable when the shell exits, rather + than overwriting the file. + + `histreedit' + If set, and Readline is being used, a user is given the + opportunity to re-edit a failed history substitution. + + `histverify' + If set, and Readline is being used, the results of history + substitution are not immediately passed to the shell parser. + Instead, the resulting line is loaded into the Readline + editing buffer, allowing further modification. + + `hostcomplete' + If set, and Readline is being used, Bash will attempt to + perform hostname completion when a word containing a `@' is + being completed (*note Commands For Completion::). This + option is enabled by default. + + `huponexit' + If set, Bash will send `SIGHUP' to all jobs when an + interactive login shell exits (*note Signals::). + + `interactive_comments' + Allow a word beginning with `#' to cause that word and all + remaining characters on that line to be ignored in an + interactive shell. This option is enabled by default. + + `lithist' + If enabled, and the `cmdhist' option is enabled, multi-line + commands are saved to the history with embedded newlines + rather than using semicolon separators where possible. + + `login_shell' + The shell sets this option if it is started as a login shell + (*note Invoking Bash::). The value may not be changed. + + `mailwarn' + If set, and a file that Bash is checking for mail has been + accessed since the last time it was checked, the message + `"The mail in MAILFILE has been read"' is displayed. + + `no_empty_cmd_completion' + If set, and Readline is being used, Bash will not attempt to + search the `PATH' for possible completions when completion is + attempted on an empty line. + + `nocaseglob' + If set, Bash matches filenames in a case-insensitive fashion + when performing filename expansion. + + `nocasematch' + If set, Bash matches patterns in a case-insensitive fashion + when performing matching while executing `case' or `[[' + conditional commands. + + `nullglob' + If set, Bash allows filename patterns which match no files to + expand to a null string, rather than themselves. + + `progcomp' + If set, the programmable completion facilities (*note + Programmable Completion::) are enabled. This option is + enabled by default. + + `promptvars' + If set, prompt strings undergo parameter expansion, command + substitution, arithmetic expansion, and quote removal after + being expanded as described below (*note Printing a Prompt::). + This option is enabled by default. + + `restricted_shell' + The shell sets this option if it is started in restricted mode + (*note The Restricted Shell::). The value may not be changed. + This is not reset when the startup files are executed, + allowing the startup files to discover whether or not a shell + is restricted. + + `shift_verbose' + If this is set, the `shift' builtin prints an error message + when the shift count exceeds the number of positional + parameters. + + `sourcepath' + If set, the `source' builtin uses the value of `PATH' to find + the directory containing the file supplied as an argument. + This option is enabled by default. + + `xpg_echo' + If set, the `echo' builtin expands backslash-escape sequences + by default. + + + The return status when listing options is zero if all OPTNAMES are + enabled, non-zero otherwise. When setting or unsetting options, + the return status is zero unless an OPTNAME is not a valid shell + option. + + + +File: bashref.info, Node: Special Builtins, Prev: Modifying Shell Behavior, Up: Shell Builtin Commands + +4.4 Special Builtins +==================== + +For historical reasons, the POSIX standard has classified several +builtin commands as _special_. When Bash is executing in POSIX mode, +the special builtins differ from other builtin commands in three +respects: + + 1. Special builtins are found before shell functions during command + lookup. + + 2. If a special builtin returns an error status, a non-interactive + shell exits. + + 3. Assignment statements preceding the command stay in effect in the + shell environment after the command completes. + + When Bash is not executing in POSIX mode, these builtins behave no +differently than the rest of the Bash builtin commands. The Bash POSIX +mode is described in *note Bash POSIX Mode::. + + These are the POSIX special builtins: + break : . continue eval exec exit export readonly return set + shift trap unset + + +File: bashref.info, Node: Shell Variables, Next: Bash Features, Prev: Shell Builtin Commands, Up: Top + +5 Shell Variables +***************** + +* Menu: + +* Bourne Shell Variables:: Variables which Bash uses in the same way + as the Bourne Shell. +* Bash Variables:: List of variables that exist in Bash. + + This chapter describes the shell variables that Bash uses. Bash +automatically assigns default values to a number of variables. + + +File: bashref.info, Node: Bourne Shell Variables, Next: Bash Variables, Up: Shell Variables + +5.1 Bourne Shell Variables +========================== + +Bash uses certain shell variables in the same way as the Bourne shell. +In some cases, Bash assigns a default value to the variable. + +`CDPATH' + A colon-separated list of directories used as a search path for + the `cd' builtin command. + +`HOME' + The current user's home directory; the default for the `cd' builtin + command. The value of this variable is also used by tilde + expansion (*note Tilde Expansion::). + +`IFS' + A list of characters that separate fields; used when the shell + splits words as part of expansion. + +`MAIL' + If this parameter is set to a filename and the `MAILPATH' variable + is not set, Bash informs the user of the arrival of mail in the + specified file. + +`MAILPATH' + A colon-separated list of filenames which the shell periodically + checks for new mail. Each list entry can specify the message that + is printed when new mail arrives in the mail file by separating + the file name from the message with a `?'. When used in the text + of the message, `$_' expands to the name of the current mail file. + +`OPTARG' + The value of the last option argument processed by the `getopts' + builtin. + +`OPTIND' + The index of the last option argument processed by the `getopts' + builtin. + +`PATH' + A colon-separated list of directories in which the shell looks for + commands. A zero-length (null) directory name in the value of + `PATH' indicates the current directory. A null directory name may + appear as two adjacent colons, or as an initial or trailing colon. + +`PS1' + The primary prompt string. The default value is `\s-\v\$ '. + *Note Printing a Prompt::, for the complete list of escape + sequences that are expanded before `PS1' is displayed. + +`PS2' + The secondary prompt string. The default value is `> '. + + + +File: bashref.info, Node: Bash Variables, Prev: Bourne Shell Variables, Up: Shell Variables + +5.2 Bash Variables +================== + +These variables are set or used by Bash, but other shells do not +normally treat them specially. + + A few variables used by Bash are described in different chapters: +variables for controlling the job control facilities (*note Job Control +Variables::). + +`BASH' + The full pathname used to execute the current instance of Bash. + +`BASHOPTS' + A colon-separated list of enabled shell options. Each word in the + list is a valid argument for the `-s' option to the `shopt' + builtin command (*note The Shopt Builtin::). The options + appearing in `BASHOPTS' are those reported as `on' by `shopt'. If + this variable is in the environment when Bash starts up, each + shell option in the list will be enabled before reading any + startup files. This variable is readonly. + +`BASHPID' + Expands to the process id of the current Bash process. This + differs from `$$' under certain circumstances, such as subshells + that do not require Bash to be re-initialized. + +`BASH_ALIASES' + An associative array variable whose members correspond to the + internal list of aliases as maintained by the `alias' builtin + (*note Bourne Shell Builtins::). Elements added to this array + appear in the alias list; unsetting array elements cause aliases + to be removed from the alias list. + +`BASH_ARGC' + An array variable whose values are the number of parameters in each + frame of the current bash execution call stack. The number of + parameters to the current subroutine (shell function or script + executed with `.' or `source') is at the top of the stack. When a + subroutine is executed, the number of parameters passed is pushed + onto `BASH_ARGC'. The shell sets `BASH_ARGC' only when in + extended debugging mode (see *note The Shopt Builtin:: for a + description of the `extdebug' option to the `shopt' builtin). + +`BASH_ARGV' + An array variable containing all of the parameters in the current + bash execution call stack. The final parameter of the last + subroutine call is at the top of the stack; the first parameter of + the initial call is at the bottom. When a subroutine is executed, + the parameters supplied are pushed onto `BASH_ARGV'. The shell + sets `BASH_ARGV' only when in extended debugging mode (see *note + The Shopt Builtin:: for a description of the `extdebug' option to + the `shopt' builtin). + +`BASH_CMDS' + An associative array variable whose members correspond to the + internal hash table of commands as maintained by the `hash' builtin + (*note Bourne Shell Builtins::). Elements added to this array + appear in the hash table; unsetting array elements cause commands + to be removed from the hash table. + +`BASH_COMMAND' + The command currently being executed or about to be executed, + unless the shell is executing a command as the result of a trap, + in which case it is the command executing at the time of the trap. + +`BASH_ENV' + If this variable is set when Bash is invoked to execute a shell + script, its value is expanded and used as the name of a startup + file to read before executing the script. *Note Bash Startup + Files::. + +`BASH_EXECUTION_STRING' + The command argument to the `-c' invocation option. + +`BASH_LINENO' + An array variable whose members are the line numbers in source + files corresponding to each member of FUNCNAME. + `${BASH_LINENO[$i]}' is the line number in the source file where + `${FUNCNAME[$i]}' was called (or `${BASH_LINENO[$i-1]}' if + referenced within another shell function). The corresponding + source file name is `${BASH_SOURCE[$i]}'. Use `LINENO' to obtain + the current line number. + +`BASH_REMATCH' + An array variable whose members are assigned by the `=~' binary + operator to the `[[' conditional command (*note Conditional + Constructs::). The element with index 0 is the portion of the + string matching the entire regular expression. The element with + index N is the portion of the string matching the Nth + parenthesized subexpression. This variable is read-only. + +`BASH_SOURCE' + An array variable whose members are the source filenames + corresponding to the elements in the `FUNCNAME' array variable. + +`BASH_SUBSHELL' + Incremented by one each time a subshell or subshell environment is + spawned. The initial value is 0. + +`BASH_VERSINFO' + A readonly array variable (*note Arrays::) whose members hold + version information for this instance of Bash. The values + assigned to the array members are as follows: + + `BASH_VERSINFO[0]' + The major version number (the RELEASE). + + `BASH_VERSINFO[1]' + The minor version number (the VERSION). + + `BASH_VERSINFO[2]' + The patch level. + + `BASH_VERSINFO[3]' + The build version. + + `BASH_VERSINFO[4]' + The release status (e.g., BETA1). + + `BASH_VERSINFO[5]' + The value of `MACHTYPE'. + + +`BASH_VERSION' + The version number of the current instance of Bash. + +`BASH_XTRACEFD' + If set to an integer corresponding to a valid file descriptor, Bash + will write the trace output generated when `set -x' is enabled to + that file descriptor. This allows tracing output to be separated + from diagnostic and error messages. The file descriptor is closed + when `BASH_XTRACEFD' is unset or assigned a new value. Unsetting + `BASH_XTRACEFD' or assigning it the empty string causes the trace + output to be sent to the standard error. Note that setting + `BASH_XTRACEFD' to 2 (the standard error file descriptor) and then + unsetting it will result in the standard error being closed. + +`COLUMNS' + Used by the `select' builtin command to determine the terminal + width when printing selection lists. Automatically set upon + receipt of a `SIGWINCH'. + +`COMP_CWORD' + An index into `${COMP_WORDS}' of the word containing the current + cursor position. This variable is available only in shell + functions invoked by the programmable completion facilities (*note + Programmable Completion::). + +`COMP_LINE' + The current command line. This variable is available only in + shell functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +`COMP_POINT' + The index of the current cursor position relative to the beginning + of the current command. If the current cursor position is at the + end of the current command, the value of this variable is equal to + `${#COMP_LINE}'. This variable is available only in shell + functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +`COMP_TYPE' + Set to an integer value corresponding to the type of completion + attempted that caused a completion function to be called: TAB, for + normal completion, `?', for listing completions after successive + tabs, `!', for listing alternatives on partial word completion, + `@', to list completions if the word is not unmodified, or `%', + for menu completion. This variable is available only in shell + functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +`COMP_KEY' + The key (or final key of a key sequence) used to invoke the current + completion function. + +`COMP_WORDBREAKS' + The set of characters that the Readline library treats as word + separators when performing word completion. If `COMP_WORDBREAKS' + is unset, it loses its special properties, even if it is + subsequently reset. + +`COMP_WORDS' + An array variable consisting of the individual words in the + current command line. The line is split into words as Readline + would split it, using `COMP_WORDBREAKS' as described above. This + variable is available only in shell functions invoked by the + programmable completion facilities (*note Programmable + Completion::). + +`COMPREPLY' + An array variable from which Bash reads the possible completions + generated by a shell function invoked by the programmable + completion facility (*note Programmable Completion::). + +`DIRSTACK' + An array variable containing the current contents of the directory + stack. Directories appear in the stack in the order they are + displayed by the `dirs' builtin. Assigning to members of this + array variable may be used to modify directories already in the + stack, but the `pushd' and `popd' builtins must be used to add and + remove directories. Assignment to this variable will not change + the current directory. If `DIRSTACK' is unset, it loses its + special properties, even if it is subsequently reset. + +`EMACS' + If Bash finds this variable in the environment when the shell + starts with value `t', it assumes that the shell is running in an + emacs shell buffer and disables line editing. + +`EUID' + The numeric effective user id of the current user. This variable + is readonly. + +`FCEDIT' + The editor used as a default by the `-e' option to the `fc' + builtin command. + +`FIGNORE' + A colon-separated list of suffixes to ignore when performing + filename completion. A file name whose suffix matches one of the + entries in `FIGNORE' is excluded from the list of matched file + names. A sample value is `.o:~' + +`FUNCNAME' + An array variable containing the names of all shell functions + currently in the execution call stack. The element with index 0 + is the name of any currently-executing shell function. The + bottom-most element is `"main"'. This variable exists only when a + shell function is executing. Assignments to `FUNCNAME' have no + effect and return an error status. If `FUNCNAME' is unset, it + loses its special properties, even if it is subsequently reset. + +`GLOBIGNORE' + A colon-separated list of patterns defining the set of filenames to + be ignored by filename expansion. If a filename matched by a + filename expansion pattern also matches one of the patterns in + `GLOBIGNORE', it is removed from the list of matches. + +`GROUPS' + An array variable containing the list of groups of which the + current user is a member. Assignments to `GROUPS' have no effect + and return an error status. If `GROUPS' is unset, it loses its + special properties, even if it is subsequently reset. + +`histchars' + Up to three characters which control history expansion, quick + substitution, and tokenization (*note History Interaction::). The + first character is the HISTORY EXPANSION character, that is, the + character which signifies the start of a history expansion, + normally `!'. The second character is the character which + signifies `quick substitution' when seen as the first character on + a line, normally `^'. The optional third character is the + character which indicates that the remainder of the line is a + comment when found as the first character of a word, usually `#'. + The history comment character causes history substitution to be + skipped for the remaining words on the line. It does not + necessarily cause the shell parser to treat the rest of the line + as a comment. + +`HISTCMD' + The history number, or index in the history list, of the current + command. If `HISTCMD' is unset, it loses its special properties, + even if it is subsequently reset. + +`HISTCONTROL' + A colon-separated list of values controlling how commands are + saved on the history list. If the list of values includes + `ignorespace', lines which begin with a space character are not + saved in the history list. A value of `ignoredups' causes lines + which match the previous history entry to not be saved. A value + of `ignoreboth' is shorthand for `ignorespace' and `ignoredups'. + A value of `erasedups' causes all previous lines matching the + current line to be removed from the history list before that line + is saved. Any value not in the above list is ignored. If + `HISTCONTROL' is unset, or does not include a valid value, all + lines read by the shell parser are saved on the history list, + subject to the value of `HISTIGNORE'. The second and subsequent + lines of a multi-line compound command are not tested, and are + added to the history regardless of the value of `HISTCONTROL'. + +`HISTFILE' + The name of the file to which the command history is saved. The + default value is `~/.bash_history'. + +`HISTFILESIZE' + The maximum number of lines contained in the history file. When + this variable is assigned a value, the history file is truncated, + if necessary, by removing the oldest entries, to contain no more + than that number of lines. The history file is also truncated to + this size after writing it when an interactive shell exits. The + default value is 500. + +`HISTIGNORE' + A colon-separated list of patterns used to decide which command + lines should be saved on the history list. Each pattern is + anchored at the beginning of the line and must match the complete + line (no implicit `*' is appended). Each pattern is tested + against the line after the checks specified by `HISTCONTROL' are + applied. In addition to the normal shell pattern matching + characters, `&' matches the previous history line. `&' may be + escaped using a backslash; the backslash is removed before + attempting a match. The second and subsequent lines of a + multi-line compound command are not tested, and are added to the + history regardless of the value of `HISTIGNORE'. + + `HISTIGNORE' subsumes the function of `HISTCONTROL'. A pattern of + `&' is identical to `ignoredups', and a pattern of `[ ]*' is + identical to `ignorespace'. Combining these two patterns, + separating them with a colon, provides the functionality of + `ignoreboth'. + +`HISTSIZE' + The maximum number of commands to remember on the history list. + The default value is 500. + +`HISTTIMEFORMAT' + If this variable is set and not null, its value is used as a + format string for STRFTIME to print the time stamp associated with + each history entry displayed by the `history' builtin. If this + variable is set, time stamps are written to the history file so + they may be preserved across shell sessions. This uses the + history comment character to distinguish timestamps from other + history lines. + +`HOSTFILE' + Contains the name of a file in the same format as `/etc/hosts' that + should be read when the shell needs to complete a hostname. The + list of possible hostname completions may be changed while the + shell is running; the next time hostname completion is attempted + after the value is changed, Bash adds the contents of the new file + to the existing list. If `HOSTFILE' is set, but has no value, or + does not name a readable file, Bash attempts to read `/etc/hosts' + to obtain the list of possible hostname completions. When + `HOSTFILE' is unset, the hostname list is cleared. + +`HOSTNAME' + The name of the current host. + +`HOSTTYPE' + A string describing the machine Bash is running on. + +`IGNOREEOF' + Controls the action of the shell on receipt of an `EOF' character + as the sole input. If set, the value denotes the number of + consecutive `EOF' characters that can be read as the first + character on an input line before the shell will exit. If the + variable exists but does not have a numeric value (or has no + value) then the default is 10. If the variable does not exist, + then `EOF' signifies the end of input to the shell. This is only + in effect for interactive shells. + +`INPUTRC' + The name of the Readline initialization file, overriding the + default of `~/.inputrc'. + +`LANG' + Used to determine the locale category for any category not + specifically selected with a variable starting with `LC_'. + +`LC_ALL' + This variable overrides the value of `LANG' and any other `LC_' + variable specifying a locale category. + +`LC_COLLATE' + This variable determines the collation order used when sorting the + results of filename expansion, and determines the behavior of + range expressions, equivalence classes, and collating sequences + within filename expansion and pattern matching (*note Filename + Expansion::). + +`LC_CTYPE' + This variable determines the interpretation of characters and the + behavior of character classes within filename expansion and pattern + matching (*note Filename Expansion::). + +`LC_MESSAGES' + This variable determines the locale used to translate double-quoted + strings preceded by a `$' (*note Locale Translation::). + +`LC_NUMERIC' + This variable determines the locale category used for number + formatting. + +`LINENO' + The line number in the script or shell function currently + executing. + +`LINES' + Used by the `select' builtin command to determine the column length + for printing selection lists. Automatically set upon receipt of a + `SIGWINCH'. + +`MACHTYPE' + A string that fully describes the system type on which Bash is + executing, in the standard GNU CPU-COMPANY-SYSTEM format. + +`MAILCHECK' + How often (in seconds) that the shell should check for mail in the + files specified in the `MAILPATH' or `MAIL' variables. The + default is 60 seconds. When it is time to check for mail, the + shell does so before displaying the primary prompt. If this + variable is unset, or set to a value that is not a number greater + than or equal to zero, the shell disables mail checking. + +`OLDPWD' + The previous working directory as set by the `cd' builtin. + +`OPTERR' + If set to the value 1, Bash displays error messages generated by + the `getopts' builtin command. + +`OSTYPE' + A string describing the operating system Bash is running on. + +`PIPESTATUS' + An array variable (*note Arrays::) containing a list of exit + status values from the processes in the most-recently-executed + foreground pipeline (which may contain only a single command). + +`POSIXLY_CORRECT' + If this variable is in the environment when `bash' starts, the + shell enters POSIX mode (*note Bash POSIX Mode::) before reading + the startup files, as if the `--posix' invocation option had been + supplied. If it is set while the shell is running, `bash' enables + POSIX mode, as if the command + `set -o posix' + had been executed. + +`PPID' + The process ID of the shell's parent process. This variable is + readonly. + +`PROMPT_COMMAND' + If set, the value is interpreted as a command to execute before + the printing of each primary prompt (`$PS1'). + +`PROMPT_DIRTRIM' + If set to a number greater than zero, the value is used as the + number of trailing directory components to retain when expanding + the `\w' and `\W' prompt string escapes (*note Printing a + Prompt::). Characters removed are replaced with an ellipsis. + +`PS3' + The value of this variable is used as the prompt for the `select' + command. If this variable is not set, the `select' command + prompts with `#? ' + +`PS4' + The value is the prompt printed before the command line is echoed + when the `-x' option is set (*note The Set Builtin::). The first + character of `PS4' is replicated multiple times, as necessary, to + indicate multiple levels of indirection. The default is `+ '. + +`PWD' + The current working directory as set by the `cd' builtin. + +`RANDOM' + Each time this parameter is referenced, a random integer between 0 + and 32767 is generated. Assigning a value to this variable seeds + the random number generator. + +`REPLY' + The default variable for the `read' builtin. + +`SECONDS' + This variable expands to the number of seconds since the shell was + started. Assignment to this variable resets the count to the + value assigned, and the expanded value becomes the value assigned + plus the number of seconds since the assignment. + +`SHELL' + The full pathname to the shell is kept in this environment + variable. If it is not set when the shell starts, Bash assigns to + it the full pathname of the current user's login shell. + +`SHELLOPTS' + A colon-separated list of enabled shell options. Each word in the + list is a valid argument for the `-o' option to the `set' builtin + command (*note The Set Builtin::). The options appearing in + `SHELLOPTS' are those reported as `on' by `set -o'. If this + variable is in the environment when Bash starts up, each shell + option in the list will be enabled before reading any startup + files. This variable is readonly. + +`SHLVL' + Incremented by one each time a new instance of Bash is started. + This is intended to be a count of how deeply your Bash shells are + nested. + +`TIMEFORMAT' + The value of this parameter is used as a format string specifying + how the timing information for pipelines prefixed with the `time' + reserved word should be displayed. The `%' character introduces an + escape sequence that is expanded to a time value or other + information. The escape sequences and their meanings are as + follows; the braces denote optional portions. + + `%%' + A literal `%'. + + `%[P][l]R' + The elapsed time in seconds. + + `%[P][l]U' + The number of CPU seconds spent in user mode. + + `%[P][l]S' + The number of CPU seconds spent in system mode. + + `%P' + The CPU percentage, computed as (%U + %S) / %R. + + The optional P is a digit specifying the precision, the number of + fractional digits after a decimal point. A value of 0 causes no + decimal point or fraction to be output. At most three places + after the decimal point may be specified; values of P greater than + 3 are changed to 3. If P is not specified, the value 3 is used. + + The optional `l' specifies a longer format, including minutes, of + the form MMmSS.FFs. The value of P determines whether or not the + fraction is included. + + If this variable is not set, Bash acts as if it had the value + `$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'' + If the value is null, no timing information is displayed. A + trailing newline is added when the format string is displayed. + +`TMOUT' + If set to a value greater than zero, `TMOUT' is treated as the + default timeout for the `read' builtin (*note Bash Builtins::). + The `select' command (*note Conditional Constructs::) terminates + if input does not arrive after `TMOUT' seconds when input is coming + from a terminal. + + In an interactive shell, the value is interpreted as the number of + seconds to wait for input after issuing the primary prompt when + the shell is interactive. Bash terminates after that number of + seconds if input does not arrive. + +`TMPDIR' + If set, Bash uses its value as the name of a directory in which + Bash creates temporary files for the shell's use. + +`UID' + The numeric real user id of the current user. This variable is + readonly. + + + +File: bashref.info, Node: Bash Features, Next: Job Control, Prev: Shell Variables, Up: Top + +6 Bash Features +*************** + +This section describes features unique to Bash. + +* Menu: + +* Invoking Bash:: Command line options that you can give + to Bash. +* Bash Startup Files:: When and how Bash executes scripts. +* Interactive Shells:: What an interactive shell is. +* Bash Conditional Expressions:: Primitives used in composing expressions for + the `test' builtin. +* Shell Arithmetic:: Arithmetic on shell variables. +* Aliases:: Substituting one command for another. +* Arrays:: Array Variables. +* The Directory Stack:: History of visited directories. +* Printing a Prompt:: Controlling the PS1 string. +* The Restricted Shell:: A more controlled mode of shell execution. +* Bash POSIX Mode:: Making Bash behave more closely to what + the POSIX standard specifies. + + +File: bashref.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features + +6.1 Invoking Bash +================= + + bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...] + bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] -c STRING [ARGUMENT ...] + bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...] + + In addition to the single-character shell command-line options +(*note The Set Builtin::), there are several multi-character options +that you can use. These options must appear on the command line before +the single-character options to be recognized. + +`--debugger' + Arrange for the debugger profile to be executed before the shell + starts. Turns on extended debugging mode (see *note The Shopt + Builtin:: for a description of the `extdebug' option to the `shopt' + builtin) and shell function tracing (see *note The Set Builtin:: + for a description of the `-o functrace' option). + +`--dump-po-strings' + A list of all double-quoted strings preceded by `$' is printed on + the standard output in the GNU `gettext' PO (portable object) file + format. Equivalent to `-D' except for the output format. + +`--dump-strings' + Equivalent to `-D'. + +`--help' + Display a usage message on standard output and exit successfully. + +`--init-file FILENAME' +`--rcfile FILENAME' + Execute commands from FILENAME (instead of `~/.bashrc') in an + interactive shell. + +`--login' + Equivalent to `-l'. + +`--noediting' + Do not use the GNU Readline library (*note Command Line Editing::) + to read command lines when the shell is interactive. + +`--noprofile' + Don't load the system-wide startup file `/etc/profile' or any of + the personal initialization files `~/.bash_profile', + `~/.bash_login', or `~/.profile' when Bash is invoked as a login + shell. + +`--norc' + Don't read the `~/.bashrc' initialization file in an interactive + shell. This is on by default if the shell is invoked as `sh'. + +`--posix' + Change the behavior of Bash where the default operation differs + from the POSIX standard to match the standard. This is intended + to make Bash behave as a strict superset of that standard. *Note + Bash POSIX Mode::, for a description of the Bash POSIX mode. + +`--restricted' + Make the shell a restricted shell (*note The Restricted Shell::). + +`--verbose' + Equivalent to `-v'. Print shell input lines as they're read. + +`--version' + Show version information for this instance of Bash on the standard + output and exit successfully. + + + There are several single-character options that may be supplied at +invocation which are not available with the `set' builtin. + +`-c STRING' + Read and execute commands from STRING after processing the + options, then exit. Any remaining arguments are assigned to the + positional parameters, starting with `$0'. + +`-i' + Force the shell to run interactively. Interactive shells are + described in *note Interactive Shells::. + +`-l' + Make this shell act as if it had been directly invoked by login. + When the shell is interactive, this is equivalent to starting a + login shell with `exec -l bash'. When the shell is not + interactive, the login shell startup files will be executed. + `exec bash -l' or `exec bash --login' will replace the current + shell with a Bash login shell. *Note Bash Startup Files::, for a + description of the special behavior of a login shell. + +`-r' + Make the shell a restricted shell (*note The Restricted Shell::). + +`-s' + If this option is present, or if no arguments remain after option + processing, then commands are read from the standard input. This + option allows the positional parameters to be set when invoking an + interactive shell. + +`-D' + A list of all double-quoted strings preceded by `$' is printed on + the standard output. These are the strings that are subject to + language translation when the current locale is not `C' or `POSIX' + (*note Locale Translation::). This implies the `-n' option; no + commands will be executed. + +`[-+]O [SHOPT_OPTION]' + SHOPT_OPTION is one of the shell options accepted by the `shopt' + builtin (*note The Shopt Builtin::). If SHOPT_OPTION is present, + `-O' sets the value of that option; `+O' unsets it. If + SHOPT_OPTION is not supplied, the names and values of the shell + options accepted by `shopt' are printed on the standard output. + If the invocation option is `+O', the output is displayed in a + format that may be reused as input. + +`--' + A `--' signals the end of options and disables further option + processing. Any arguments after the `--' are treated as filenames + and arguments. + + + A _login_ shell is one whose first character of argument zero is +`-', or one invoked with the `--login' option. + + An _interactive_ shell is one started without non-option arguments, +unless `-s' is specified, without specifying the `-c' option, and whose +input and output are both connected to terminals (as determined by +`isatty(3)'), or one started with the `-i' option. *Note Interactive +Shells::, for more information. + + If arguments remain after option processing, and neither the `-c' +nor the `-s' option has been supplied, the first argument is assumed to +be the name of a file containing shell commands (*note Shell Scripts::). +When Bash is invoked in this fashion, `$0' is set to the name of the +file, and the positional parameters are set to the remaining arguments. +Bash reads and executes commands from this file, then exits. Bash's +exit status is the exit status of the last command executed in the +script. If no commands are executed, the exit status is 0. + + +File: bashref.info, Node: Bash Startup Files, Next: Interactive Shells, Prev: Invoking Bash, Up: Bash Features + +6.2 Bash Startup Files +====================== + +This section describes how Bash executes its startup files. If any of +the files exist but cannot be read, Bash reports an error. Tildes are +expanded in file names as described above under Tilde Expansion (*note +Tilde Expansion::). + + Interactive shells are described in *note Interactive Shells::. + +Invoked as an interactive login shell, or with `--login' +........................................................ + +When Bash is invoked as an interactive login shell, or as a +non-interactive shell with the `--login' option, it first reads and +executes commands from the file `/etc/profile', if that file exists. +After reading that file, it looks for `~/.bash_profile', +`~/.bash_login', and `~/.profile', in that order, and reads and +executes commands from the first one that exists and is readable. The +`--noprofile' option may be used when the shell is started to inhibit +this behavior. + + When a login shell exits, Bash reads and executes commands from the +file `~/.bash_logout', if it exists. + +Invoked as an interactive non-login shell +......................................... + +When an interactive shell that is not a login shell is started, Bash +reads and executes commands from `~/.bashrc', if that file exists. +This may be inhibited by using the `--norc' option. The `--rcfile +FILE' option will force Bash to read and execute commands from FILE +instead of `~/.bashrc'. + + So, typically, your `~/.bash_profile' contains the line + `if [ -f ~/.bashrc ]; then . ~/.bashrc; fi' + after (or before) any login-specific initializations. + +Invoked non-interactively +......................... + +When Bash is started non-interactively, to run a shell script, for +example, it looks for the variable `BASH_ENV' in the environment, +expands its value if it appears there, and uses the expanded value as +the name of a file to read and execute. Bash behaves as if the +following command were executed: + `if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi' + but the value of the `PATH' variable is not used to search for the +file name. + + As noted above, if a non-interactive shell is invoked with the +`--login' option, Bash attempts to read and execute commands from the +login shell startup files. + +Invoked with name `sh' +...................... + +If Bash is invoked with the name `sh', it tries to mimic the startup +behavior of historical versions of `sh' as closely as possible, while +conforming to the POSIX standard as well. + + When invoked as an interactive login shell, or as a non-interactive +shell with the `--login' option, it first attempts to read and execute +commands from `/etc/profile' and `~/.profile', in that order. The +`--noprofile' option may be used to inhibit this behavior. When +invoked as an interactive shell with the name `sh', Bash looks for the +variable `ENV', expands its value if it is defined, and uses the +expanded value as the name of a file to read and execute. Since a +shell invoked as `sh' does not attempt to read and execute commands +from any other startup files, the `--rcfile' option has no effect. A +non-interactive shell invoked with the name `sh' does not attempt to +read any other startup files. + + When invoked as `sh', Bash enters POSIX mode after the startup files +are read. + +Invoked in POSIX mode +..................... + +When Bash is started in POSIX mode, as with the `--posix' command line +option, it follows the POSIX standard for startup files. In this mode, +interactive shells expand the `ENV' variable and commands are read and +executed from the file whose name is the expanded value. No other +startup files are read. + +Invoked by remote shell daemon +.............................. + +Bash attempts to determine when it is being run with its standard input +connected to a a network connection, as if by the remote shell daemon, +usually `rshd', or the secure shell daemon `sshd'. If Bash determines +it is being run in this fashion, it reads and executes commands from +`~/.bashrc', if that file exists and is readable. It will not do this +if invoked as `sh'. The `--norc' option may be used to inhibit this +behavior, and the `--rcfile' option may be used to force another file +to be read, but `rshd' does not generally invoke the shell with those +options or allow them to be specified. + +Invoked with unequal effective and real UID/GIDs +................................................ + +If Bash is started with the effective user (group) id not equal to the +real user (group) id, and the `-p' option is not supplied, no startup +files are read, shell functions are not inherited from the environment, +the `SHELLOPTS', `BASHOPTS', `CDPATH', and `GLOBIGNORE' variables, if +they appear in the environment, are ignored, and the effective user id +is set to the real user id. If the `-p' option is supplied at +invocation, the startup behavior is the same, but the effective user id +is not reset. + + +File: bashref.info, Node: Interactive Shells, Next: Bash Conditional Expressions, Prev: Bash Startup Files, Up: Bash Features + +6.3 Interactive Shells +====================== + +* Menu: + +* What is an Interactive Shell?:: What determines whether a shell is Interactive. +* Is this Shell Interactive?:: How to tell if a shell is interactive. +* Interactive Shell Behavior:: What changes in a interactive shell? + + +File: bashref.info, Node: What is an Interactive Shell?, Next: Is this Shell Interactive?, Up: Interactive Shells + +6.3.1 What is an Interactive Shell? +----------------------------------- + +An interactive shell is one started without non-option arguments, +unless `-s' is specified, without specifying the `-c' option, and whose +input and error output are both connected to terminals (as determined +by `isatty(3)'), or one started with the `-i' option. + + An interactive shell generally reads from and writes to a user's +terminal. + + The `-s' invocation option may be used to set the positional +parameters when an interactive shell is started. + + +File: bashref.info, Node: Is this Shell Interactive?, Next: Interactive Shell Behavior, Prev: What is an Interactive Shell?, Up: Interactive Shells + +6.3.2 Is this Shell Interactive? +-------------------------------- + +To determine within a startup script whether or not Bash is running +interactively, test the value of the `-' special parameter. It +contains `i' when the shell is interactive. For example: + + case "$-" in + *i*) echo This shell is interactive ;; + *) echo This shell is not interactive ;; + esac + + Alternatively, startup scripts may examine the variable `PS1'; it is +unset in non-interactive shells, and set in interactive shells. Thus: + + if [ -z "$PS1" ]; then + echo This shell is not interactive + else + echo This shell is interactive + fi + + +File: bashref.info, Node: Interactive Shell Behavior, Prev: Is this Shell Interactive?, Up: Interactive Shells + +6.3.3 Interactive Shell Behavior +-------------------------------- + +When the shell is running interactively, it changes its behavior in +several ways. + + 1. Startup files are read and executed as described in *note Bash + Startup Files::. + + 2. Job Control (*note Job Control::) is enabled by default. When job + control is in effect, Bash ignores the keyboard-generated job + control signals `SIGTTIN', `SIGTTOU', and `SIGTSTP'. + + 3. Bash expands and displays `PS1' before reading the first line of a + command, and expands and displays `PS2' before reading the second + and subsequent lines of a multi-line command. + + 4. Bash executes the value of the `PROMPT_COMMAND' variable as a + command before printing the primary prompt, `$PS1' (*note Bash + Variables::). + + 5. Readline (*note Command Line Editing::) is used to read commands + from the user's terminal. + + 6. Bash inspects the value of the `ignoreeof' option to `set -o' + instead of exiting immediately when it receives an `EOF' on its + standard input when reading a command (*note The Set Builtin::). + + 7. Command history (*note Bash History Facilities::) and history + expansion (*note History Interaction::) are enabled by default. + Bash will save the command history to the file named by `$HISTFILE' + when an interactive shell exits. + + 8. Alias expansion (*note Aliases::) is performed by default. + + 9. In the absence of any traps, Bash ignores `SIGTERM' (*note + Signals::). + + 10. In the absence of any traps, `SIGINT' is caught and handled + ((*note Signals::). `SIGINT' will interrupt some shell builtins. + + 11. An interactive login shell sends a `SIGHUP' to all jobs on exit if + the `huponexit' shell option has been enabled (*note Signals::). + + 12. The `-n' invocation option is ignored, and `set -n' has no effect + (*note The Set Builtin::). + + 13. Bash will check for mail periodically, depending on the values of + the `MAIL', `MAILPATH', and `MAILCHECK' shell variables (*note + Bash Variables::). + + 14. Expansion errors due to references to unbound shell variables after + `set -u' has been enabled will not cause the shell to exit (*note + The Set Builtin::). + + 15. The shell will not exit on expansion errors caused by VAR being + unset or null in `${VAR:?WORD}' expansions (*note Shell Parameter + Expansion::). + + 16. Redirection errors encountered by shell builtins will not cause the + shell to exit. + + 17. When running in POSIX mode, a special builtin returning an error + status will not cause the shell to exit (*note Bash POSIX Mode::). + + 18. A failed `exec' will not cause the shell to exit (*note Bourne + Shell Builtins::). + + 19. Parser syntax errors will not cause the shell to exit. + + 20. Simple spelling correction for directory arguments to the `cd' + builtin is enabled by default (see the description of the `cdspell' + option to the `shopt' builtin in *note The Shopt Builtin::). + + 21. The shell will check the value of the `TMOUT' variable and exit if + a command is not read within the specified number of seconds after + printing `$PS1' (*note Bash Variables::). + + + +File: bashref.info, Node: Bash Conditional Expressions, Next: Shell Arithmetic, Prev: Interactive Shells, Up: Bash Features + +6.4 Bash Conditional Expressions +================================ + +Conditional expressions are used by the `[[' compound command and the +`test' and `[' builtin commands. + + Expressions may be unary or binary. Unary expressions are often +used to examine the status of a file. There are string operators and +numeric comparison operators as well. If the FILE argument to one of +the primaries is of the form `/dev/fd/N', then file descriptor N is +checked. If the FILE argument to one of the primaries is one of +`/dev/stdin', `/dev/stdout', or `/dev/stderr', file descriptor 0, 1, or +2, respectively, is checked. + + When used with `[[', The `<' and `>' operators sort +lexicographically using the current locale. + + Unless otherwise specified, primaries that operate on files follow +symbolic links and operate on the target of the link, rather than the +link itself. + +`-a FILE' + True if FILE exists. + +`-b FILE' + True if FILE exists and is a block special file. + +`-c FILE' + True if FILE exists and is a character special file. + +`-d FILE' + True if FILE exists and is a directory. + +`-e FILE' + True if FILE exists. + +`-f FILE' + True if FILE exists and is a regular file. + +`-g FILE' + True if FILE exists and its set-group-id bit is set. + +`-h FILE' + True if FILE exists and is a symbolic link. + +`-k FILE' + True if FILE exists and its "sticky" bit is set. + +`-p FILE' + True if FILE exists and is a named pipe (FIFO). + +`-r FILE' + True if FILE exists and is readable. + +`-s FILE' + True if FILE exists and has a size greater than zero. + +`-t FD' + True if file descriptor FD is open and refers to a terminal. + +`-u FILE' + True if FILE exists and its set-user-id bit is set. + +`-w FILE' + True if FILE exists and is writable. + +`-x FILE' + True if FILE exists and is executable. + +`-O FILE' + True if FILE exists and is owned by the effective user id. + +`-G FILE' + True if FILE exists and is owned by the effective group id. + +`-L FILE' + True if FILE exists and is a symbolic link. + +`-S FILE' + True if FILE exists and is a socket. + +`-N FILE' + True if FILE exists and has been modified since it was last read. + +`FILE1 -nt FILE2' + True if FILE1 is newer (according to modification date) than + FILE2, or if FILE1 exists and FILE2 does not. + +`FILE1 -ot FILE2' + True if FILE1 is older than FILE2, or if FILE2 exists and FILE1 + does not. + +`FILE1 -ef FILE2' + True if FILE1 and FILE2 refer to the same device and inode numbers. + +`-o OPTNAME' + True if shell option OPTNAME is enabled. The list of options + appears in the description of the `-o' option to the `set' builtin + (*note The Set Builtin::). + +`-z STRING' + True if the length of STRING is zero. + +`-n STRING' +`STRING' + True if the length of STRING is non-zero. + +`STRING1 == STRING2' +`STRING1 = STRING2' + True if the strings are equal. `=' should be used with the `test' + command for POSIX conformance. + +`STRING1 != STRING2' + True if the strings are not equal. + +`STRING1 < STRING2' + True if STRING1 sorts before STRING2 lexicographically. + +`STRING1 > STRING2' + True if STRING1 sorts after STRING2 lexicographically. + +`ARG1 OP ARG2' + `OP' is one of `-eq', `-ne', `-lt', `-le', `-gt', or `-ge'. These + arithmetic binary operators return true if ARG1 is equal to, not + equal to, less than, less than or equal to, greater than, or + greater than or equal to ARG2, respectively. ARG1 and ARG2 may be + positive or negative integers. + + + +File: bashref.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features + +6.5 Shell Arithmetic +==================== + +The shell allows arithmetic expressions to be evaluated, as one of the +shell expansions or by the `let' and the `-i' option to the `declare' +builtins. + + Evaluation is done in fixed-width integers with no check for +overflow, though division by 0 is trapped and flagged as an error. The +operators and their precedence, associativity, and values are the same +as in the C language. The following list of operators is grouped into +levels of equal-precedence operators. The levels are listed in order +of decreasing precedence. + +`ID++ ID--' + variable post-increment and post-decrement + +`++ID --ID' + variable pre-increment and pre-decrement + +`- +' + unary minus and plus + +`! ~' + logical and bitwise negation + +`**' + exponentiation + +`* / %' + multiplication, division, remainder + +`+ -' + addition, subtraction + +`<< >>' + left and right bitwise shifts + +`<= >= < >' + comparison + +`== !=' + equality and inequality + +`&' + bitwise AND + +`^' + bitwise exclusive OR + +`|' + bitwise OR + +`&&' + logical AND + +`||' + logical OR + +`expr ? expr : expr' + conditional operator + +`= *= /= %= += -= <<= >>= &= ^= |=' + assignment + +`expr1 , expr2' + comma + + Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. Within an expression, +shell variables may also be referenced by name without using the +parameter expansion syntax. A shell variable that is null or unset +evaluates to 0 when referenced by name without using the parameter +expansion syntax. The value of a variable is evaluated as an +arithmetic expression when it is referenced, or when a variable which +has been given the INTEGER attribute using `declare -i' is assigned a +value. A null value evaluates to 0. A shell variable need not have +its integer attribute turned on to be used in an expression. + + Constants with a leading 0 are interpreted as octal numbers. A +leading `0x' or `0X' denotes hexadecimal. Otherwise, numbers take the +form [BASE`#']N, where BASE is a decimal number between 2 and 64 +representing the arithmetic base, and N is a number in that base. If +BASE`#' is omitted, then base 10 is used. The digits greater than 9 +are represented by the lowercase letters, the uppercase letters, `@', +and `_', in that order. If BASE is less than or equal to 36, lowercase +and uppercase letters may be used interchangeably to represent numbers +between 10 and 35. + + Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence rules +above. + + +File: bashref.info, Node: Aliases, Next: Arrays, Prev: Shell Arithmetic, Up: Bash Features + +6.6 Aliases +=========== + +ALIASES allow a string to be substituted for a word when it is used as +the first word of a simple command. The shell maintains a list of +aliases that may be set and unset with the `alias' and `unalias' +builtin commands. + + The first word of each simple command, if unquoted, is checked to see +if it has an alias. If so, that word is replaced by the text of the +alias. The characters `/', `$', ``', `=' and any of the shell +metacharacters or quoting characters listed above may not appear in an +alias name. The replacement text may contain any valid shell input, +including shell metacharacters. The first word of the replacement text +is tested for aliases, but a word that is identical to an alias being +expanded is not expanded a second time. This means that one may alias +`ls' to `"ls -F"', for instance, and Bash does not try to recursively +expand the replacement text. If the last character of the alias value +is a space or tab character, then the next command word following the +alias is also checked for alias expansion. + + Aliases are created and listed with the `alias' command, and removed +with the `unalias' command. + + There is no mechanism for using arguments in the replacement text, +as in `csh'. If arguments are needed, a shell function should be used +(*note Shell Functions::). + + Aliases are not expanded when the shell is not interactive, unless +the `expand_aliases' shell option is set using `shopt' (*note The Shopt +Builtin::). + + The rules concerning the definition and use of aliases are somewhat +confusing. Bash always reads at least one complete line of input +before executing any of the commands on that line. Aliases are +expanded when a command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another command does not +take effect until the next line of input is read. The commands +following the alias definition on that line are not affected by the new +alias. This behavior is also an issue when functions are executed. +Aliases are expanded when a function definition is read, not when the +function is executed, because a function definition is itself a +compound command. As a consequence, aliases defined in a function are +not available until after that function is executed. To be safe, +always put alias definitions on a separate line, and do not use `alias' +in compound commands. + + For almost every purpose, shell functions are preferred over aliases. + + +File: bashref.info, Node: Arrays, Next: The Directory Stack, Prev: Aliases, Up: Bash Features + +6.7 Arrays +========== + +Bash provides one-dimensional indexed and associative array variables. +Any variable may be used as an indexed array; the `declare' builtin +will explicitly declare an array. There is no maximum limit on the +size of an array, nor any requirement that members be indexed or +assigned contiguously. Indexed arrays are referenced using integers +(including arithmetic expressions (*note Shell Arithmetic::) and are +zero-based; associative arrays use arbitrary strings. + + An indexed array is created automatically if any variable is +assigned to using the syntax + name[SUBSCRIPT]=VALUE + +The SUBSCRIPT is treated as an arithmetic expression that must evaluate +to a number greater than or equal to zero. To explicitly declare an +array, use + declare -a NAME + The syntax + declare -a NAME[SUBSCRIPT] + is also accepted; the SUBSCRIPT is ignored. + + Associative arrays are created using + declare -A NAME. + + Attributes may be specified for an array variable using the +`declare' and `readonly' builtins. Each attribute applies to all +members of an array. + + Arrays are assigned to using compound assignments of the form + name=(value1 ... valueN) + where each VALUE is of the form `[SUBSCRIPT]='STRING. Indexed array +assignments do not require the bracket and subscript. When assigning +to indexed arrays, if the optional subscript is supplied, that index is +assigned to; otherwise the index of the element assigned is the last +index assigned to by the statement plus one. Indexing starts at zero. + + When assigning to an associative array, the subscript is required. + + This syntax is also accepted by the `declare' builtin. Individual +array elements may be assigned to using the `name['SUBSCRIPT`]='VALUE +syntax introduced above. + + Any element of an array may be referenced using +`${name['SUBSCRIPT`]}'. The braces are required to avoid conflicts +with the shell's filename expansion operators. If the SUBSCRIPT is `@' +or `*', the word expands to all members of the array NAME. These +subscripts differ only when the word appears within double quotes. If +the word is double-quoted, `${name[*]}' expands to a single word with +the value of each array member separated by the first character of the +`IFS' variable, and `${name[@]}' expands each element of NAME to a +separate word. When there are no array members, `${name[@]}' expands +to nothing. If the double-quoted expansion occurs within a word, the +expansion of the first parameter is joined with the beginning part of +the original word, and the expansion of the last parameter is joined +with the last part of the original word. This is analogous to the +expansion of the special parameters `@' and `*'. +`${#name['SUBSCRIPT`]}' expands to the length of `${name['SUBSCRIPT`]}'. +If SUBSCRIPT is `@' or `*', the expansion is the number of elements in +the array. Referencing an array variable without a subscript is +equivalent to referencing with a subscript of 0. + + An array variable is considered set if a subscript has been assigned +a value. The null string is a valid value. + + The `unset' builtin is used to destroy arrays. `unset' +NAME[SUBSCRIPT] destroys the array element at index SUBSCRIPT. Care +must be taken to avoid unwanted side effects caused by filename +expansion. `unset' NAME, where NAME is an array, removes the entire +array. A subscript of `*' or `@' also removes the entire array. + + The `declare', `local', and `readonly' builtins each accept a `-a' +option to specify an indexed array and a `-A' option to specify an +associative array. The `read' builtin accepts a `-a' option to assign +a list of words read from the standard input to an array, and can read +values from the standard input into individual array elements. The +`set' and `declare' builtins display array values in a way that allows +them to be reused as input. + + +File: bashref.info, Node: The Directory Stack, Next: Printing a Prompt, Prev: Arrays, Up: Bash Features + +6.8 The Directory Stack +======================= + +* Menu: + +* Directory Stack Builtins:: Bash builtin commands to manipulate + the directory stack. + + The directory stack is a list of recently-visited directories. The +`pushd' builtin adds directories to the stack as it changes the current +directory, and the `popd' builtin removes specified directories from +the stack and changes the current directory to the directory removed. +The `dirs' builtin displays the contents of the directory stack. + + The contents of the directory stack are also visible as the value of +the `DIRSTACK' shell variable. + + +File: bashref.info, Node: Directory Stack Builtins, Up: The Directory Stack + +6.8.1 Directory Stack Builtins +------------------------------ + +`dirs' + dirs [+N | -N] [-clpv] + Display the list of currently remembered directories. Directories + are added to the list with the `pushd' command; the `popd' command + removes directories from the list. + `+N' + Displays the Nth directory (counting from the left of the + list printed by `dirs' when invoked without options), starting + with zero. + + `-N' + Displays the Nth directory (counting from the right of the + list printed by `dirs' when invoked without options), starting + with zero. + + `-c' + Clears the directory stack by deleting all of the elements. + + `-l' + Produces a longer listing; the default listing format uses a + tilde to denote the home directory. + + `-p' + Causes `dirs' to print the directory stack with one entry per + line. + + `-v' + Causes `dirs' to print the directory stack with one entry per + line, prefixing each entry with its index in the stack. + +`popd' + popd [+N | -N] [-n] + + Remove the top entry from the directory stack, and `cd' to the new + top directory. When no arguments are given, `popd' removes the + top directory from the stack and performs a `cd' to the new top + directory. The elements are numbered from 0 starting at the first + directory listed with `dirs'; i.e., `popd' is equivalent to `popd + +0'. + `+N' + Removes the Nth directory (counting from the left of the list + printed by `dirs'), starting with zero. + + `-N' + Removes the Nth directory (counting from the right of the + list printed by `dirs'), starting with zero. + + `-n' + Suppresses the normal change of directory when removing + directories from the stack, so that only the stack is + manipulated. + +`pushd' + pushd [-n] [+N | -N | DIR ] + + Save the current directory on the top of the directory stack and + then `cd' to DIR. With no arguments, `pushd' exchanges the top + two directories. + + `-n' + Suppresses the normal change of directory when adding + directories to the stack, so that only the stack is + manipulated. + + `+N' + Brings the Nth directory (counting from the left of the list + printed by `dirs', starting with zero) to the top of the list + by rotating the stack. + + `-N' + Brings the Nth directory (counting from the right of the list + printed by `dirs', starting with zero) to the top of the list + by rotating the stack. + + `DIR' + Makes the current working directory be the top of the stack, + and then executes the equivalent of ``cd' DIR'. `cd's to DIR. + + + +File: bashref.info, Node: Printing a Prompt, Next: The Restricted Shell, Prev: The Directory Stack, Up: Bash Features + +6.9 Controlling the Prompt +========================== + +The value of the variable `PROMPT_COMMAND' is examined just before Bash +prints each primary prompt. If `PROMPT_COMMAND' is set and has a +non-null value, then the value is executed just as if it had been typed +on the command line. + + In addition, the following table describes the special characters +which can appear in the prompt variables: + +`\a' + A bell character. + +`\d' + The date, in "Weekday Month Date" format (e.g., "Tue May 26"). + +`\D{FORMAT}' + The FORMAT is passed to `strftime'(3) and the result is inserted + into the prompt string; an empty FORMAT results in a + locale-specific time representation. The braces are required. + +`\e' + An escape character. + +`\h' + The hostname, up to the first `.'. + +`\H' + The hostname. + +`\j' + The number of jobs currently managed by the shell. + +`\l' + The basename of the shell's terminal device name. + +`\n' + A newline. + +`\r' + A carriage return. + +`\s' + The name of the shell, the basename of `$0' (the portion following + the final slash). + +`\t' + The time, in 24-hour HH:MM:SS format. + +`\T' + The time, in 12-hour HH:MM:SS format. + +`\@' + The time, in 12-hour am/pm format. + +`\A' + The time, in 24-hour HH:MM format. + +`\u' + The username of the current user. + +`\v' + The version of Bash (e.g., 2.00) + +`\V' + The release of Bash, version + patchlevel (e.g., 2.00.0) + +`\w' + The current working directory, with `$HOME' abbreviated with a + tilde (uses the `$PROMPT_DIRTRIM' variable). + +`\W' + The basename of `$PWD', with `$HOME' abbreviated with a tilde. + +`\!' + The history number of this command. + +`\#' + The command number of this command. + +`\$' + If the effective uid is 0, `#', otherwise `$'. + +`\NNN' + The character whose ASCII code is the octal value NNN. + +`\\' + A backslash. + +`\[' + Begin a sequence of non-printing characters. This could be used to + embed a terminal control sequence into the prompt. + +`\]' + End a sequence of non-printing characters. + + The command number and the history number are usually different: the +history number of a command is its position in the history list, which +may include commands restored from the history file (*note Bash History +Facilities::), while the command number is the position in the sequence +of commands executed during the current shell session. + + After the string is decoded, it is expanded via parameter expansion, +command substitution, arithmetic expansion, and quote removal, subject +to the value of the `promptvars' shell option (*note Bash Builtins::). + + +File: bashref.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Printing a Prompt, Up: Bash Features + +6.10 The Restricted Shell +========================= + +If Bash is started with the name `rbash', or the `--restricted' or `-r' +option is supplied at invocation, the shell becomes restricted. A +restricted shell is used to set up an environment more controlled than +the standard shell. A restricted shell behaves identically to `bash' +with the exception that the following are disallowed or not performed: + + * Changing directories with the `cd' builtin. + + * Setting or unsetting the values of the `SHELL', `PATH', `ENV', or + `BASH_ENV' variables. + + * Specifying command names containing slashes. + + * Specifying a filename containing a slash as an argument to the `.' + builtin command. + + * Specifying a filename containing a slash as an argument to the `-p' + option to the `hash' builtin command. + + * Importing function definitions from the shell environment at + startup. + + * Parsing the value of `SHELLOPTS' from the shell environment at + startup. + + * Redirecting output using the `>', `>|', `<>', `>&', `&>', and `>>' + redirection operators. + + * Using the `exec' builtin to replace the shell with another command. + + * Adding or deleting builtin commands with the `-f' and `-d' options + to the `enable' builtin. + + * Using the `enable' builtin command to enable disabled shell + builtins. + + * Specifying the `-p' option to the `command' builtin. + + * Turning off restricted mode with `set +r' or `set +o restricted'. + + These restrictions are enforced after any startup files are read. + + When a command that is found to be a shell script is executed (*note +Shell Scripts::), `rbash' turns off any restrictions in the shell +spawned to execute the script. + + +File: bashref.info, Node: Bash POSIX Mode, Prev: The Restricted Shell, Up: Bash Features + +6.11 Bash POSIX Mode +==================== + +Starting Bash with the `--posix' command-line option or executing `set +-o posix' while Bash is running will cause Bash to conform more closely +to the POSIX standard by changing the behavior to match that specified +by POSIX in areas where the Bash default differs. + + When invoked as `sh', Bash enters POSIX mode after reading the +startup files. + + The following list is what's changed when `POSIX mode' is in effect: + + 1. When a command in the hash table no longer exists, Bash will + re-search `$PATH' to find the new location. This is also + available with `shopt -s checkhash'. + + 2. The message printed by the job control code and builtins when a job + exits with a non-zero status is `Done(status)'. + + 3. The message printed by the job control code and builtins when a job + is stopped is `Stopped(SIGNAME)', where SIGNAME is, for example, + `SIGTSTP'. + + 4. The `bg' builtin uses the required format to describe each job + placed in the background, which does not include an indication of + whether the job is the current or previous job. + + 5. Reserved words appearing in a context where reserved words are + recognized do not undergo alias expansion. + + 6. The POSIX `PS1' and `PS2' expansions of `!' to the history number + and `!!' to `!' are enabled, and parameter expansion is performed + on the values of `PS1' and `PS2' regardless of the setting of the + `promptvars' option. + + 7. The POSIX startup files are executed (`$ENV') rather than the + normal Bash files. + + 8. Tilde expansion is only performed on assignments preceding a + command name, rather than on all assignment statements on the line. + + 9. The default history file is `~/.sh_history' (this is the default + value of `$HISTFILE'). + + 10. The output of `kill -l' prints all the signal names on a single + line, separated by spaces, without the `SIG' prefix. + + 11. The `kill' builtin does not accept signal names with a `SIG' + prefix. + + 12. Non-interactive shells exit if FILENAME in `.' FILENAME is not + found. + + 13. Non-interactive shells exit if a syntax error in an arithmetic + expansion results in an invalid expression. + + 14. Redirection operators do not perform filename expansion on the word + in the redirection unless the shell is interactive. + + 15. Redirection operators do not perform word splitting on the word in + the redirection. + + 16. Function names must be valid shell `name's. That is, they may not + contain characters other than letters, digits, and underscores, and + may not start with a digit. Declaring a function with an invalid + name causes a fatal syntax error in non-interactive shells. + + 17. POSIX special builtins are found before shell functions during + command lookup. + + 18. If a POSIX special builtin returns an error status, a + non-interactive shell exits. The fatal errors are those listed in + the POSIX standard, and include things like passing incorrect + options, redirection errors, variable assignment errors for + assignments preceding the command name, and so on. + + 19. If `CDPATH' is set, the `cd' builtin will not implicitly append + the current directory to it. This means that `cd' will fail if no + valid directory name can be constructed from any of the entries in + `$CDPATH', even if the a directory with the same name as the name + given as an argument to `cd' exists in the current directory. + + 20. A non-interactive shell exits with an error status if a variable + assignment error occurs when no command name follows the assignment + statements. A variable assignment error occurs, for example, when + trying to assign a value to a readonly variable. + + 21. A non-interactive shell exits with an error status if the iteration + variable in a `for' statement or the selection variable in a + `select' statement is a readonly variable. + + 22. Process substitution is not available. + + 23. Assignment statements preceding POSIX special builtins persist in + the shell environment after the builtin completes. + + 24. Assignment statements preceding shell function calls persist in the + shell environment after the function returns, as if a POSIX + special builtin command had been executed. + + 25. The `export' and `readonly' builtin commands display their output + in the format required by POSIX. + + 26. The `trap' builtin displays signal names without the leading `SIG'. + + 27. The `trap' builtin doesn't check the first argument for a possible + signal specification and revert the signal handling to the original + disposition if it is, unless that argument consists solely of + digits and is a valid signal number. If users want to reset the + handler for a given signal to the original disposition, they + should use `-' as the first argument. + + 28. The `.' and `source' builtins do not search the current directory + for the filename argument if it is not found by searching `PATH'. + + 29. Subshells spawned to execute command substitutions inherit the + value of the `-e' option from the parent shell. When not in POSIX + mode, Bash clears the `-e' option in such subshells. + + 30. Alias expansion is always enabled, even in non-interactive shells. + + 31. When the `alias' builtin displays alias definitions, it does not + display them with a leading `alias ' unless the `-p' option is + supplied. + + 32. When the `set' builtin is invoked without options, it does not + display shell function names and definitions. + + 33. When the `set' builtin is invoked without options, it displays + variable values without quotes, unless they contain shell + metacharacters, even if the result contains nonprinting characters. + + 34. When the `cd' builtin is invoked in LOGICAL mode, and the pathname + constructed from `$PWD' and the directory name supplied as an + argument does not refer to an existing directory, `cd' will fail + instead of falling back to PHYSICAL mode. + + 35. When the `pwd' builtin is supplied the `-P' option, it resets + `$PWD' to a pathname containing no symlinks. + + 36. The `pwd' builtin verifies that the value it prints is the same as + the current directory, even if it is not asked to check the file + system with the `-P' option. + + 37. When listing the history, the `fc' builtin does not include an + indication of whether or not a history entry has been modified. + + 38. The default editor used by `fc' is `ed'. + + 39. The `type' and `command' builtins will not report a non-executable + file as having been found, though the shell will attempt to + execute such a file if it is the only so-named file found in + `$PATH'. + + 40. The `vi' editing mode will invoke the `vi' editor directly when + the `v' command is run, instead of checking `$VISUAL' and + `$EDITOR'. + + 41. When the `xpg_echo' option is enabled, Bash does not attempt to + interpret any arguments to `echo' as options. Each argument is + displayed, after escape characters are converted. + + 42. The `ulimit' builtin uses a block size of 512 bytes for the `-c' + and `-f' options. + + 43. The arrival of `SIGCHLD' when a trap is set on `SIGCHLD' does not + interrupt the `wait' builtin and cause it to return immediately. + The trap command is run once for each child that exits. + + + There is other POSIX behavior that Bash does not implement by +default even when in POSIX mode. Specifically: + + 1. The `fc' builtin checks `$EDITOR' as a program to edit history + entries if `FCEDIT' is unset, rather than defaulting directly to + `ed'. `fc' uses `ed' if `EDITOR' is unset. + + 2. As noted above, Bash requires the `xpg_echo' option to be enabled + for the `echo' builtin to be fully conformant. + + + Bash can be configured to be POSIX-conformant by default, by +specifying the `--enable-strict-posix-default' to `configure' when +building (*note Optional Features::). + + +File: bashref.info, Node: Job Control, Next: Command Line Editing, Prev: Bash Features, Up: Top + +7 Job Control +************* + +This chapter discusses what job control is, how it works, and how Bash +allows you to access its facilities. + +* Menu: + +* Job Control Basics:: How job control works. +* Job Control Builtins:: Bash builtin commands used to interact + with job control. +* Job Control Variables:: Variables Bash uses to customize job + control. + + +File: bashref.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control + +7.1 Job Control Basics +====================== + +Job control refers to the ability to selectively stop (suspend) the +execution of processes and continue (resume) their execution at a later +point. A user typically employs this facility via an interactive +interface supplied jointly by the operating system kernel's terminal +driver and Bash. + + The shell associates a JOB with each pipeline. It keeps a table of +currently executing jobs, which may be listed with the `jobs' command. +When Bash starts a job asynchronously, it prints a line that looks like: + [1] 25647 + indicating that this job is job number 1 and that the process ID of +the last process in the pipeline associated with this job is 25647. +All of the processes in a single pipeline are members of the same job. +Bash uses the JOB abstraction as the basis for job control. + + To facilitate the implementation of the user interface to job +control, the operating system maintains the notion of a current terminal +process group ID. Members of this process group (processes whose +process group ID is equal to the current terminal process group ID) +receive keyboard-generated signals such as `SIGINT'. These processes +are said to be in the foreground. Background processes are those whose +process group ID differs from the terminal's; such processes are immune +to keyboard-generated signals. Only foreground processes are allowed +to read from or, if the user so specifies with `stty tostop', write to +the terminal. Background processes which attempt to read from (write +to when `stty tostop' is in effect) the terminal are sent a `SIGTTIN' +(`SIGTTOU') signal by the kernel's terminal driver, which, unless +caught, suspends the process. + + If the operating system on which Bash is running supports job +control, Bash contains facilities to use it. Typing the SUSPEND +character (typically `^Z', Control-Z) while a process is running causes +that process to be stopped and returns control to Bash. Typing the +DELAYED SUSPEND character (typically `^Y', Control-Y) causes the +process to be stopped when it attempts to read input from the terminal, +and control to be returned to Bash. The user then manipulates the +state of this job, using the `bg' command to continue it in the +background, the `fg' command to continue it in the foreground, or the +`kill' command to kill it. A `^Z' takes effect immediately, and has +the additional side effect of causing pending output and typeahead to +be discarded. + + There are a number of ways to refer to a job in the shell. The +character `%' introduces a job specification (JOBSPEC). + + Job number `n' may be referred to as `%n'. The symbols `%%' and +`%+' refer to the shell's notion of the current job, which is the last +job stopped while it was in the foreground or started in the background. +A single `%' (with no accompanying job specification) also refers to +the current job. The previous job may be referenced using `%-'. If +there is only a single job, `%+' and `%-' can both be used to refer to +that job. In output pertaining to jobs (e.g., the output of the `jobs' +command), the current job is always flagged with a `+', and the +previous job with a `-'. + + A job may also be referred to using a prefix of the name used to +start it, or using a substring that appears in its command line. For +example, `%ce' refers to a stopped `ce' job. Using `%?ce', on the other +hand, refers to any job containing the string `ce' in its command line. +If the prefix or substring matches more than one job, Bash reports an +error. + + Simply naming a job can be used to bring it into the foreground: +`%1' is a synonym for `fg %1', bringing job 1 from the background into +the foreground. Similarly, `%1 &' resumes job 1 in the background, +equivalent to `bg %1' + + The shell learns immediately whenever a job changes state. +Normally, Bash waits until it is about to print a prompt before +reporting changes in a job's status so as to not interrupt any other +output. If the `-b' option to the `set' builtin is enabled, Bash +reports such changes immediately (*note The Set Builtin::). Any trap +on `SIGCHLD' is executed for each child process that exits. + + If an attempt to exit Bash is made while jobs are stopped, (or +running, if the `checkjobs' option is enabled - see *note The Shopt +Builtin::), the shell prints a warning message, and if the `checkjobs' +option is enabled, lists the jobs and their statuses. The `jobs' +command may then be used to inspect their status. If a second attempt +to exit is made without an intervening command, Bash does not print +another warning, and any stopped jobs are terminated. + + +File: bashref.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control + +7.2 Job Control Builtins +======================== + +`bg' + bg [JOBSPEC ...] + Resume each suspended job JOBSPEC in the background, as if it had + been started with `&'. If JOBSPEC is not supplied, the current + job is used. The return status is zero unless it is run when job + control is not enabled, or, when run with job control enabled, any + JOBSPEC was not found or specifies a job that was started without + job control. + +`fg' + fg [JOBSPEC] + Resume the job JOBSPEC in the foreground and make it the current + job. If JOBSPEC is not supplied, the current job is used. The + return status is that of the command placed into the foreground, + or non-zero if run when job control is disabled or, when run with + job control enabled, JOBSPEC does not specify a valid job or + JOBSPEC specifies a job that was started without job control. + +`jobs' + jobs [-lnprs] [JOBSPEC] + jobs -x COMMAND [ARGUMENTS] + + The first form lists the active jobs. The options have the + following meanings: + + `-l' + List process IDs in addition to the normal information. + + `-n' + Display information only about jobs that have changed status + since the user was last notified of their status. + + `-p' + List only the process ID of the job's process group leader. + + `-r' + Restrict output to running jobs. + + `-s' + Restrict output to stopped jobs. + + If JOBSPEC is given, output is restricted to information about + that job. If JOBSPEC is not supplied, the status of all jobs is + listed. + + If the `-x' option is supplied, `jobs' replaces any JOBSPEC found + in COMMAND or ARGUMENTS with the corresponding process group ID, + and executes COMMAND, passing it ARGUMENTs, returning its exit + status. + +`kill' + kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID + kill -l [EXIT_STATUS] + Send a signal specified by SIGSPEC or SIGNUM to the process named + by job specification JOBSPEC or process ID PID. SIGSPEC is either + a case-insensitive signal name such as `SIGINT' (with or without + the `SIG' prefix) or a signal number; SIGNUM is a signal number. + If SIGSPEC and SIGNUM are not present, `SIGTERM' is used. The + `-l' option lists the signal names. If any arguments are supplied + when `-l' is given, the names of the signals corresponding to the + arguments are listed, and the return status is zero. EXIT_STATUS + is a number specifying a signal number or the exit status of a + process terminated by a signal. The return status is zero if at + least one signal was successfully sent, or non-zero if an error + occurs or an invalid option is encountered. + +`wait' + wait [JOBSPEC or PID ...] + Wait until the child process specified by each process ID PID or + job specification JOBSPEC exits and return the exit status of the + last command waited for. If a job spec is given, all processes in + the job are waited for. If no arguments are given, all currently + active child processes are waited for, and the return status is + zero. If neither JOBSPEC nor PID specifies an active child process + of the shell, the return status is 127. + +`disown' + disown [-ar] [-h] [JOBSPEC ...] + Without options, each JOBSPEC is removed from the table of active + jobs. If the `-h' option is given, the job is not removed from + the table, but is marked so that `SIGHUP' is not sent to the job + if the shell receives a `SIGHUP'. If JOBSPEC is not present, and + neither the `-a' nor `-r' option is supplied, the current job is + used. If no JOBSPEC is supplied, the `-a' option means to remove + or mark all jobs; the `-r' option without a JOBSPEC argument + restricts operation to running jobs. + +`suspend' + suspend [-f] + Suspend the execution of this shell until it receives a `SIGCONT' + signal. A login shell cannot be suspended; the `-f' option can be + used to override this and force the suspension. + + + When job control is not active, the `kill' and `wait' builtins do +not accept JOBSPEC arguments. They must be supplied process IDs. + + +File: bashref.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control + +7.3 Job Control Variables +========================= + +`auto_resume' + This variable controls how the shell interacts with the user and + job control. If this variable exists then single word simple + commands without redirections are treated as candidates for + resumption of an existing job. There is no ambiguity allowed; if + there is more than one job beginning with the string typed, then + the most recently accessed job will be selected. The name of a + stopped job, in this context, is the command line used to start + it. If this variable is set to the value `exact', the string + supplied must match the name of a stopped job exactly; if set to + `substring', the string supplied needs to match a substring of the + name of a stopped job. The `substring' value provides + functionality analogous to the `%?' job ID (*note Job Control + Basics::). If set to any other value, the supplied string must be + a prefix of a stopped job's name; this provides functionality + analogous to the `%' job ID. + + + +File: bashref.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Job Control, Up: Top + +8 Command Line Editing +********************** + +This chapter describes the basic features of the GNU command line +editing interface. Command line editing is provided by the Readline +library, which is used by several different programs, including Bash. +Command line editing is enabled by default when using an interactive +shell, unless the `--noediting' option is supplied at shell invocation. +Line editing is also used when using the `-e' option to the `read' +builtin command (*note Bash Builtins::). By default, the line editing +commands are similar to those of emacs. A vi-style line editing +interface is also available. Line editing can be enabled at any time +using the `-o emacs' or `-o vi' options to the `set' builtin command +(*note The Set Builtin::), or disabled using the `+o emacs' or `+o vi' +options to `set'. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + +* Programmable Completion:: How to specify the possible completions for + a specific command. +* Programmable Completion Builtins:: Builtin commands to specify how to + complete arguments for a particular command. + + +File: bashref.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +8.1 Introduction to Line Editing +================================ + +The following paragraphs describe the notation used to represent +keystrokes. + + The text `C-k' is read as `Control-K' and describes the character +produced when the <k> key is pressed while the Control key is depressed. + + The text `M-k' is read as `Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the <k> +key is pressed. The Meta key is labeled <ALT> on many keyboards. On +keyboards with two keys labeled <ALT> (usually to either side of the +space bar), the <ALT> on the left side is generally set to work as a +Meta key. The <ALT> key on the right may also be configured to work as +a Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + + If you do not have a Meta or <ALT> key, or another key working as a +Meta key, the identical keystroke can be generated by typing <ESC> +_first_, and then typing <k>. Either process is known as "metafying" +the <k> key. + + The text `M-C-k' is read as `Meta-Control-k' and describes the +character produced by "metafying" `C-k'. + + In addition, several keys have their own names. Specifically, +<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves +when seen in this text, or in an init file (*note Readline Init File::). +If your keyboard lacks a <LFD> key, typing <C-j> will produce the +desired character. The <RET> key may be labeled <Return> or <Enter> on +some keyboards. + + +File: bashref.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +8.2 Readline Interaction +======================== + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press <RET>. You do not have to be at the end of +the line to press <RET>; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: bashref.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +8.2.1 Readline Bare Essentials +------------------------------ + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your erase +character to back up and delete the mistyped character. + + Sometimes you may mistype a character, and not notice the error +until you have typed several other characters. In that case, you can +type `C-b' to move the cursor to the left, and then correct your +mistake. Afterwards, you can move the cursor to the right with `C-f'. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are `pushed over' to make room +for the text that you have inserted. Likewise, when you delete text +behind the cursor, characters to the right of the cursor are `pulled +back' to fill in the blank space created by the removal of the text. A +list of the bare essentials for editing the text of an input line +follows. + +`C-b' + Move back one character. + +`C-f' + Move forward one character. + +<DEL> or <Backspace> + Delete the character to the left of the cursor. + +`C-d' + Delete the character underneath the cursor. + +Printing characters + Insert the character into the line at the cursor. + +`C-_' or `C-x C-u' + Undo the last editing command. You can undo all the way back to an + empty line. + +(Depending on your configuration, the <Backspace> key be set to delete +the character to the left of the cursor and the <DEL> key set to delete +the character underneath the cursor, like `C-d', rather than the +character to the left of the cursor.) + + +File: bashref.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +8.2.2 Readline Movement Commands +-------------------------------- + +The above table describes the most basic keystrokes that you need in +order to do editing of the input line. For your convenience, many +other commands have been added in addition to `C-b', `C-f', `C-d', and +<DEL>. Here are some commands for moving more rapidly about the line. + +`C-a' + Move to the start of the line. + +`C-e' + Move to the end of the line. + +`M-f' + Move forward a word, where a word is composed of letters and + digits. + +`M-b' + Move backward a word. + +`C-l' + Clear the screen, reprinting the current line at the top. + + Notice how `C-f' moves forward a character, while `M-f' moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. + + +File: bashref.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +8.2.3 Readline Killing Commands +------------------------------- + +"Killing" text means to delete the text from the line, but to save it +away for later use, usually by "yanking" (re-inserting) it back into +the line. (`Cut' and `paste' are more recent jargon for `kill' and +`yank'.) + + If the description for a command says that it `kills' text, then you +can be sure that you can get the text back in a different (or the same) +place later. + + When you use a kill command, the text is saved in a "kill-ring". +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +`C-k' + Kill the text from the current cursor position to the end of the + line. + +`M-d' + Kill from the cursor to the end of the current word, or, if between + words, to the end of the next word. Word boundaries are the same + as those used by `M-f'. + +`M-<DEL>' + Kill from the cursor the start of the current word, or, if between + words, to the start of the previous word. Word boundaries are the + same as those used by `M-b'. + +`C-w' + Kill from the cursor to the previous whitespace. This is + different than `M-<DEL>' because the word boundaries differ. + + + Here is how to "yank" the text back into the line. Yanking means to +copy the most-recently-killed text from the kill buffer. + +`C-y' + Yank the most recently killed text back into the buffer at the + cursor. + +`M-y' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is `C-y' or `M-y'. + + +File: bashref.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +8.2.4 Readline Arguments +------------------------ + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type `M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first `digit' typed is a minus +sign (`-'), then the sign of the argument will be negative. Once you +have typed one meta digit to get the argument started, you can type the +remainder of the digits, and then the command. For example, to give +the `C-d' command an argument of 10, you could type `M-1 0 C-d', which +will delete the next ten characters on the input line. + + +File: bashref.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +8.2.5 Searching for Commands in the History +------------------------------------------- + +Readline provides commands for searching through the command history +(*note Bash History Facilities::) for lines containing a specified +string. There are two search modes: "incremental" and +"non-incremental". + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +Readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters +as needed to find the desired history entry. To search backward in the +history for a particular string, type `C-r'. Typing `C-s' searches +forward through the history. The characters present in the value of +the `isearch-terminators' variable are used to terminate an incremental +search. If that variable has not been assigned a value, the <ESC> and +`C-J' characters will terminate an incremental search. `C-g' will +abort an incremental search and restore the original line. When the +search is terminated, the history entry containing the search string +becomes the current line. + + To find other matching entries in the history list, type `C-r' or +`C-s' as appropriate. This will search backward or forward in the +history for the next entry matching the search string typed so far. +Any other key sequence bound to a Readline command will terminate the +search and execute that command. For instance, a <RET> will terminate +the search and accept the line, thereby executing the command from the +history list. A movement command will terminate the search, make the +last line found the current line, and begin editing. + + Readline remembers the last incremental search string. If two +`C-r's are typed without any intervening characters defining a new +search string, any remembered search string is used. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + + +File: bashref.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +8.3 Readline Init File +====================== + +Although the Readline library comes with a set of Emacs-like +keybindings installed by default, it is possible to use a different set +of keybindings. Any user can customize programs that use Readline by +putting commands in an "inputrc" file, conventionally in his home +directory. The name of this file is taken from the value of the shell +variable `INPUTRC'. If that variable is unset, the default is +`~/.inputrc'. If that file does not exist or cannot be read, the +ultimate default is `/etc/inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the `C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: bashref.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +8.3.1 Readline Init File Syntax +------------------------------- + +There are only a few basic constructs allowed in the Readline init +file. Blank lines are ignored. Lines beginning with a `#' are +comments. Lines beginning with a `$' indicate conditional constructs +(*note Conditional Init Constructs::). Other lines denote variable +settings and key bindings. + +Variable Settings + You can modify the run-time behavior of Readline by altering the + values of variables in Readline using the `set' command within the + init file. The syntax is simple: + + set VARIABLE VALUE + + Here, for example, is how to change from the default Emacs-like + key binding to use `vi' line editing commands: + + set editing-mode vi + + Variable names and values, where appropriate, are recognized + without regard to case. Unrecognized variable names are ignored. + + Boolean variables (those that can be set to on or off) are set to + on if the value is null or empty, ON (case-insensitive), or 1. + Any other value results in the variable being set to off. + + The `bind -V' command lists the current Readline variable names + and values. *Note Bash Builtins::. + + A great deal of run-time behavior is changeable with the following + variables. + + `bell-style' + Controls what happens when Readline wants to ring the + terminal bell. If set to `none', Readline never rings the + bell. If set to `visible', Readline uses a visible bell if + one is available. If set to `audible' (the default), + Readline attempts to ring the terminal's bell. + + `bind-tty-special-chars' + If set to `on', Readline attempts to bind the control + characters treated specially by the kernel's terminal driver + to their Readline equivalents. + + `comment-begin' + The string to insert at the beginning of the line when the + `insert-comment' command is executed. The default value is + `"#"'. + + `completion-ignore-case' + If set to `on', Readline performs filename matching and + completion in a case-insensitive fashion. The default value + is `off'. + + `completion-prefix-display-length' + The length in characters of the common prefix of a list of + possible completions that is displayed without modification. + When set to a value greater than zero, common prefixes longer + than this value are replaced with an ellipsis when displaying + possible completions. + + `completion-query-items' + The number of possible completions that determines when the + user is asked whether the list of possibilities should be + displayed. If the number of possible completions is greater + than this value, Readline will ask the user whether or not he + wishes to view them; otherwise, they are simply listed. This + variable must be set to an integer value greater than or + equal to 0. A negative value means Readline should never ask. + The default limit is `100'. + + `convert-meta' + If set to `on', Readline will convert characters with the + eighth bit set to an ASCII key sequence by stripping the + eighth bit and prefixing an <ESC> character, converting them + to a meta-prefixed key sequence. The default value is `on'. + + `disable-completion' + If set to `On', Readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to `self-insert'. The default is `off'. + + `editing-mode' + The `editing-mode' variable controls which default set of key + bindings is used. By default, Readline starts up in Emacs + editing mode, where the keystrokes are most similar to Emacs. + This variable can be set to either `emacs' or `vi'. + + `echo-control-characters' + When set to `on', on operating systems that indicate they + support it, readline echoes a character corresponding to a + signal generated from the keyboard. The default is `on'. + + `enable-keypad' + When set to `on', Readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is `off'. + + `enable-meta-key' + When set to `on', Readline will try to enable any meta + modifier key the terminal claims to support when it is + called. On many terminals, the meta key is used to send + eight-bit characters. The default is `on'. + + `expand-tilde' + If set to `on', tilde expansion is performed when Readline + attempts word completion. The default is `off'. + + `history-preserve-point' + If set to `on', the history code attempts to place the point + (the current cursor position) at the same location on each + history line retrieved with `previous-history' or + `next-history'. The default is `off'. + + `history-size' + Set the maximum number of history entries saved in the + history list. If set to zero, the number of entries in the + history list is not limited. + + `horizontal-scroll-mode' + This variable can be set to either `on' or `off'. Setting it + to `on' means that the text of the lines being edited will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. By default, this variable is set to `off'. + + `input-meta' + If set to `on', Readline will enable eight-bit input (it will + not clear the eighth bit in the characters it reads), + regardless of what the terminal claims it can support. The + default value is `off'. The name `meta-flag' is a synonym + for this variable. + + `isearch-terminators' + The string of characters that should terminate an incremental + search without subsequently executing the character as a + command (*note Searching::). If this variable has not been + given a value, the characters <ESC> and `C-J' will terminate + an incremental search. + + `keymap' + Sets Readline's idea of the current keymap for key binding + commands. Acceptable `keymap' names are `emacs', + `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', + `vi-command', and `vi-insert'. `vi' is equivalent to + `vi-command'; `emacs' is equivalent to `emacs-standard'. The + default value is `emacs'. The value of the `editing-mode' + variable also affects the default keymap. + + `mark-directories' + If set to `on', completed directory names have a slash + appended. The default is `on'. + + `mark-modified-lines' + This variable, when set to `on', causes Readline to display an + asterisk (`*') at the start of history lines which have been + modified. This variable is `off' by default. + + `mark-symlinked-directories' + If set to `on', completed names which are symbolic links to + directories have a slash appended (subject to the value of + `mark-directories'). The default is `off'. + + `match-hidden-files' + This variable, when set to `on', causes Readline to match + files whose names begin with a `.' (hidden files) when + performing filename completion, unless the leading `.' is + supplied by the user in the filename to be completed. This + variable is `on' by default. + + `output-meta' + If set to `on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is `off'. + + `page-completions' + If set to `on', Readline uses an internal `more'-like pager + to display a screenful of possible completions at a time. + This variable is `on' by default. + + `print-completions-horizontally' + If set to `on', Readline will display completions with matches + sorted horizontally in alphabetical order, rather than down + the screen. The default is `off'. + + `revert-all-at-newline' + If set to `on', Readline will undo all changes to history + lines before returning when `accept-line' is executed. By + default, history lines may be modified and retain individual + undo lists across calls to `readline'. The default is `off'. + + `show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to `on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is `off'. + + `show-all-if-unmodified' + This alters the default behavior of the completion functions + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to + `on', words which have more than one possible completion + without any possible partial completion (the possible + completions don't share a common prefix) cause the matches to + be listed immediately instead of ringing the bell. The + default value is `off'. + + `skip-completed-text' + If set to `on', this alters the default completion behavior + when inserting a single match into the line. It's only + active when performing completion in the middle of a word. + If enabled, readline does not insert characters from the + completion that match characters after point in the word + being completed, so portions of the word following the cursor + are not duplicated. For instance, if this is enabled, + attempting completion when the cursor is after the `e' in + `Makefile' will result in `Makefile' rather than + `Makefilefile', assuming there is a single possible + completion. The default value is `off'. + + `visible-stats' + If set to `on', a character denoting a file's type is + appended to the filename when listing possible completions. + The default is `off'. + + +Key Bindings + The syntax for controlling key bindings in the init file is + simple. First you need to find the name of the command that you + want to change. The following sections contain tables of the + command name, the default keybinding, if any, and a short + description of what the command does. + + Once you know the name of the command, simply place on a line in + the init file the name of the key you wish to bind the command to, + a colon, and then the name of the command. There can be no space + between the key name and the colon - that will be interpreted as + part of the key name. The name of the key can be expressed in + different ways, depending on what you find most comfortable. + + In addition to command names, readline allows keys to be bound to + a string that is inserted when the key is pressed (a MACRO). + + The `bind -p' command displays Readline function names and + bindings in a format that can put directly into an initialization + file. *Note Bash Builtins::. + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the above example, `C-u' is bound to the function + `universal-argument', `M-DEL' is bound to the function + `backward-kill-word', and `C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + `> output' into the line). + + A number of symbolic character names are recognized while + processing this key binding syntax: DEL, ESC, ESCAPE, LFD, + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, `C-u' is again bound to the function + `universal-argument' (just as it was in the first example), + `C-x C-r' is bound to the function `re-read-init-file', and + `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function + Key 1'. + + + The following GNU Emacs style escape sequences are available when + specifying key sequences: + + `\C-' + control prefix + + `\M-' + meta prefix + + `\e' + an escape character + + `\\' + backslash + + `\"' + <">, a double quotation mark + + `\'' + <'>, a single quote or apostrophe + + In addition to the GNU Emacs style escape sequences, a second set + of backslash escapes is available: + + `\a' + alert (bell) + + `\b' + backspace + + `\d' + delete + + `\f' + form feed + + `\n' + newline + + `\r' + carriage return + + `\t' + horizontal tab + + `\v' + vertical tab + + `\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) + + When entering the text of a macro, single or double quotes must be + used to indicate a macro definition. Unquoted text is assumed to + be a function name. In the macro body, the backslash escapes + described above are expanded. Backslash will quote any other + character in the macro text, including `"' and `''. For example, + the following binding will make `C-x \' insert a single `\' into + the line: + "\C-x\\": "\\" + + + +File: bashref.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +8.3.2 Conditional Init Constructs +--------------------------------- + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings +and variable settings to be performed as the result of tests. There +are four parser directives used. + +`$if' + The `$if' construct allows bindings to be made based on the + editing mode, the terminal being used, or the application using + Readline. The text of the test extends to the end of the line; no + characters are required to isolate it. + + `mode' + The `mode=' form of the `$if' directive is used to test + whether Readline is in `emacs' or `vi' mode. This may be + used in conjunction with the `set keymap' command, for + instance, to set bindings in the `emacs-standard' and + `emacs-ctlx' keymaps only if Readline is starting out in + `emacs' mode. + + `term' + The `term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + `=' is tested against both the full name of the terminal and + the portion of the terminal name before the first `-'. This + allows `sun' to match both `sun' and `sun-cmd', for instance. + + `application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for a particular value. This could be used to bind key + sequences to functions useful for a specific program. For + instance, the following command adds a key sequence that + quotes the current or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + +`$endif' + This command, as seen in the previous example, terminates an `$if' + command. + +`$else' + Commands in this branch of the `$if' directive are executed if the + test fails. + +`$include' + This directive takes a single filename as an argument and reads + commands and bindings from that file. For example, the following + directive reads from `/etc/inputrc': + $include /etc/inputrc + + +File: bashref.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +8.3.3 Sample Init File +---------------------- + +Here is an example of an INPUTRC file. This illustrates key binding, +variable assignment, and conditional syntax. + + + # This file controls the behaviour of line input editing for + # programs that use the GNU Readline library. Existing + # programs include FTP, Bash, and GDB. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # First, include any systemwide bindings and variable + # assignments from /etc/Inputrc + $include /etc/Inputrc + + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD": backward-char + #"\M-OC": forward-char + #"\M-OA": previous-history + #"\M-OB": next-history + # + # Arrow keys in ANSI mode + # + "\M-[D": backward-char + "\M-[C": forward-char + "\M-[A": previous-history + "\M-[B": next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD": backward-char + #"\M-\C-OC": forward-char + #"\M-\C-OA": previous-history + #"\M-\C-OB": next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D": backward-char + #"\M-\C-[C": forward-char + #"\M-\C-[A": previous-history + #"\M-\C-[B": next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- + # insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes + # in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather + # than converted to prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly + # rather than as meta-prefixed characters + set output-meta on + + # if there are more than 150 possible completions for + # a word, ask the user if he wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: bashref.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +8.4 Bindable Readline Commands +============================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + + This section describes Readline commands that may be bound to key +sequences. You can list your key bindings by executing `bind -P' or, +for a more terse format, suitable for an INPUTRC file, `bind -p'. +(*Note Bash Builtins::.) Command names without an accompanying key +sequence are unbound by default. + + In the following descriptions, "point" refers to the current cursor +position, and "mark" refers to a cursor position saved by the +`set-mark' command. The text between the point and mark is referred to +as the "region". + + +File: bashref.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +8.4.1 Commands For Moving +------------------------- + +`beginning-of-line (C-a)' + Move to the start of the current line. + +`end-of-line (C-e)' + Move to the end of the line. + +`forward-char (C-f)' + Move forward a character. + +`backward-char (C-b)' + Move back a character. + +`forward-word (M-f)' + Move forward to the end of the next word. Words are composed of + letters and digits. + +`backward-word (M-b)' + Move back to the start of the current or previous word. Words are + composed of letters and digits. + +`shell-forward-word ()' + Move forward to the end of the next word. Words are delimited by + non-quoted shell metacharacters. + +`shell-backward-word ()' + Move back to the start of the current or previous word. Words are + delimited by non-quoted shell metacharacters. + +`clear-screen (C-l)' + Clear the screen and redraw the current line, leaving the current + line at the top of the screen. + +`redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + + +File: bashref.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +8.4.2 Commands For Manipulating The History +------------------------------------------- + +`accept-line (Newline or Return)' + Accept the line regardless of where the cursor is. If this line is + non-empty, add it to the history list according to the setting of + the `HISTCONTROL' and `HISTIGNORE' variables. If this line is a + modified history line, then restore the history line to its + original state. + +`previous-history (C-p)' + Move `back' through the history list, fetching the previous + command. + +`next-history (C-n)' + Move `forward' through the history list, fetching the next command. + +`beginning-of-history (M-<)' + Move to the first line in the history. + +`end-of-history (M->)' + Move to the end of the input history, i.e., the line currently + being entered. + +`reverse-search-history (C-r)' + Search backward starting at the current line and moving `up' + through the history as necessary. This is an incremental search. + +`forward-search-history (C-s)' + Search forward starting at the current line and moving `down' + through the the history as necessary. This is an incremental + search. + +`non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving `up' + through the history as necessary using a non-incremental search + for a string supplied by the user. + +`non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving `down' + through the the history as necessary using a non-incremental search + for a string supplied by the user. + +`history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +`history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +`yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument N, + insert the Nth word from the previous command (the words in the + previous command begin with word 0). A negative argument inserts + the Nth word from the end of the previous command. Once the + argument N is computed, the argument is extracted as if the `!N' + history expansion had been specified. + +`yank-last-arg (M-. or M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With an argument, behave exactly like + `yank-nth-arg'. Successive calls to `yank-last-arg' move back + through the history list, inserting the last argument of each line + in turn. The history expansion facilities are used to extract the + last argument, as if the `!$' history expansion had been specified. + + + +File: bashref.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +8.4.3 Commands For Changing Text +-------------------------------- + +`delete-char (C-d)' + Delete the character at point. If point is at the beginning of + the line, there are no characters in the line, and the last + character typed was not bound to `delete-char', then return EOF. + +`backward-delete-char (Rubout)' + Delete the character behind the cursor. A numeric argument means + to kill the characters instead of deleting them. + +`forward-backward-delete-char ()' + Delete the character under the cursor, unless the cursor is at the + end of the line, in which case the character behind the cursor is + deleted. By default, this is not bound to a key. + +`quoted-insert (C-q or C-v)' + Add the next character typed to the line verbatim. This is how to + insert key sequences like `C-q', for example. + +`self-insert (a, b, A, 1, !, ...)' + Insert yourself. + +`transpose-chars (C-t)' + Drag the character before the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative arguments have no effect. + +`transpose-words (M-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. + +`upcase-word (M-u)' + Uppercase the current (or following) word. With a negative + argument, uppercase the previous word, but do not move the cursor. + +`downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, lowercase the previous word, but do not move the cursor. + +`capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, capitalize the previous word, but do not move the cursor. + +`overwrite-mode ()' + Toggle overwrite mode. With an explicit positive numeric argument, + switches to overwrite mode. With an explicit non-positive numeric + argument, switches to insert mode. This command affects only + `emacs' mode; `vi' mode does overwrite differently. Each call to + `readline()' starts in insert mode. + + In overwrite mode, characters bound to `self-insert' replace the + text at point rather than pushing the text to the right. + Characters bound to `backward-delete-char' replace the character + before point with a space. + + By default, this command is unbound. + + + +File: bashref.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +8.4.4 Killing And Yanking +------------------------- + +`kill-line (C-k)' + Kill the text from point to the end of the line. + +`backward-kill-line (C-x Rubout)' + Kill backward to the beginning of the line. + +`unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + +`kill-whole-line ()' + Kill all characters on the current line, no matter where point is. + By default, this is unbound. + +`kill-word (M-d)' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as `forward-word'. + +`backward-kill-word (M-<DEL>)' + Kill the word behind point. Word boundaries are the same as + `backward-word'. + +`shell-kill-word ()' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as `shell-forward-word'. + +`backward-kill-word ()' + Kill the word behind point. Word boundaries are the same as + `shell-backward-word'. + +`unix-word-rubout (C-w)' + Kill the word behind point, using white space as a word boundary. + The killed text is saved on the kill-ring. + +`unix-filename-rubout ()' + Kill the word behind point, using white space and the slash + character as the word boundaries. The killed text is saved on the + kill-ring. + +`delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +`kill-region ()' + Kill the text in the current region. By default, this command is + unbound. + +`copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so it can be yanked + right away. By default, this command is unbound. + +`copy-backward-word ()' + Copy the word before point to the kill buffer. The word + boundaries are the same as `backward-word'. By default, this + command is unbound. + +`copy-forward-word ()' + Copy the word following point to the kill buffer. The word + boundaries are the same as `forward-word'. By default, this + command is unbound. + +`yank (C-y)' + Yank the top of the kill ring into the buffer at point. + +`yank-pop (M-y)' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is `yank' or `yank-pop'. + + +File: bashref.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +8.4.5 Specifying Numeric Arguments +---------------------------------- + +`digit-argument (M-0, M-1, ... M--)' + Add this digit to the argument already accumulating, or start a new + argument. `M--' starts a negative argument. + +`universal-argument ()' + This is another way to specify an argument. If this command is + followed by one or more digits, optionally with a leading minus + sign, those digits define the argument. If the command is + followed by digits, executing `universal-argument' again ends the + numeric argument, but is otherwise ignored. As a special case, if + this command is immediately followed by a character that is + neither a digit or minus sign, the argument count for the next + command is multiplied by four. The argument count is initially + one, so executing this function the first time makes the argument + count four, a second time makes the argument count sixteen, and so + on. By default, this is not bound to a key. + + +File: bashref.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +8.4.6 Letting Readline Type For You +----------------------------------- + +`complete (<TAB>)' + Attempt to perform completion on the text before point. The + actual completion performed is application-specific. Bash + attempts completion treating the text as a variable (if the text + begins with `$'), username (if the text begins with `~'), hostname + (if the text begins with `@'), or command (including aliases and + functions) in turn. If none of these produces a match, filename + completion is attempted. + +`possible-completions (M-?)' + List the possible completions of the text before point. + +`insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by `possible-completions'. + +`menu-complete ()' + Similar to `complete', but replaces the word to be completed with + a single match from the list of possible completions. Repeated + execution of `menu-complete' steps through the list of possible + completions, inserting each match in turn. At the end of the list + of completions, the bell is rung (subject to the setting of + `bell-style') and the original text is restored. An argument of N + moves N positions forward in the list of matches; a negative + argument may be used to move backward through the list. This + command is intended to be bound to <TAB>, but is unbound by + default. + +`menu-complete-backward ()' + Identical to `menu-complete', but moves backward through the list + of possible completions, as if `menu-complete' had been given a + negative argument. + +`delete-char-or-list ()' + Deletes the character under the cursor if not at the beginning or + end of the line (like `delete-char'). If at the end of the line, + behaves identically to `possible-completions'. This command is + unbound by default. + +`complete-filename (M-/)' + Attempt filename completion on the text before point. + +`possible-filename-completions (C-x /)' + List the possible completions of the text before point, treating + it as a filename. + +`complete-username (M-~)' + Attempt completion on the text before point, treating it as a + username. + +`possible-username-completions (C-x ~)' + List the possible completions of the text before point, treating + it as a username. + +`complete-variable (M-$)' + Attempt completion on the text before point, treating it as a + shell variable. + +`possible-variable-completions (C-x $)' + List the possible completions of the text before point, treating + it as a shell variable. + +`complete-hostname (M-@)' + Attempt completion on the text before point, treating it as a + hostname. + +`possible-hostname-completions (C-x @)' + List the possible completions of the text before point, treating + it as a hostname. + +`complete-command (M-!)' + Attempt completion on the text before point, treating it as a + command name. Command completion attempts to match the text + against aliases, reserved words, shell functions, shell builtins, + and finally executable filenames, in that order. + +`possible-command-completions (C-x !)' + List the possible completions of the text before point, treating + it as a command name. + +`dynamic-complete-history (M-<TAB>)' + Attempt completion on the text before point, comparing the text + against lines from the history list for possible completion + matches. + +`dabbrev-expand ()' + Attempt menu completion on the text before point, comparing the + text against lines from the history list for possible completion + matches. + +`complete-into-braces (M-{)' + Perform filename completion and insert the list of possible + completions enclosed within braces so the list is available to the + shell (*note Brace Expansion::). + + + +File: bashref.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +8.4.7 Keyboard Macros +--------------------- + +`start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +`end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +`call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + + + +File: bashref.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +8.4.8 Some Miscellaneous Commands +--------------------------------- + +`re-read-init-file (C-x C-r)' + Read in the contents of the INPUTRC file, and incorporate any + bindings or variable assignments found there. + +`abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of `bell-style'). + +`do-uppercase-version (M-a, M-b, M-X, ...)' + If the metafied character X is lowercase, run the command that is + bound to the corresponding uppercase character. + +`prefix-meta (<ESC>)' + Metafy the next character typed. This is for keyboards without a + meta key. Typing `<ESC> f' is equivalent to typing `M-f'. + +`undo (C-_ or C-x C-u)' + Incremental undo, separately remembered for each line. + +`revert-line (M-r)' + Undo all changes made to this line. This is like executing the + `undo' command enough times to get back to the beginning. + +`tilde-expand (M-&)' + Perform tilde expansion on the current word. + +`set-mark (C-@)' + Set the mark to the point. If a numeric argument is supplied, the + mark is set to that position. + +`exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +`character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative count searches for previous + occurrences. + +`character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative count searches for subsequent + occurrences. + +`skip-csi-sequence ()' + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. Such sequences begin + with a Control Sequence Indicator (CSI), usually ESC-[. If this + sequence is bound to "\e[", keys producing such sequences will + have no effect unless explicitly bound to a readline command, + instead of inserting stray characters into the editing buffer. + This is unbound by default, but usually bound to ESC-[. + +`insert-comment (M-#)' + Without a numeric argument, the value of the `comment-begin' + variable is inserted at the beginning of the current line. If a + numeric argument is supplied, this command acts as a toggle: if + the characters at the beginning of the line do not match the value + of `comment-begin', the value is inserted, otherwise the + characters in `comment-begin' are deleted from the beginning of + the line. In either case, the line is accepted as if a newline + had been typed. The default value of `comment-begin' causes this + command to make the current line a shell comment. If a numeric + argument causes the comment character to be removed, the line will + be executed by the shell. + +`dump-functions ()' + Print all of the functions and their key bindings to the Readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +`dump-variables ()' + Print all of the settable variables and their values to the + Readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +`dump-macros ()' + Print all of the Readline key sequences bound to macros and the + strings they output. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +`glob-complete-word (M-g)' + The word before point is treated as a pattern for pathname + expansion, with an asterisk implicitly appended. This pattern is + used to generate a list of matching file names for possible + completions. + +`glob-expand-word (C-x *)' + The word before point is treated as a pattern for pathname + expansion, and the list of matching file names is inserted, + replacing the word. If a numeric argument is supplied, a `*' is + appended before pathname expansion. + +`glob-list-expansions (C-x g)' + The list of expansions that would have been generated by + `glob-expand-word' is displayed, and the line is redrawn. If a + numeric argument is supplied, a `*' is appended before pathname + expansion. + +`display-shell-version (C-x C-v)' + Display version information about the current instance of Bash. + +`shell-expand-line (M-C-e)' + Expand the line as the shell does. This performs alias and + history expansion as well as all of the shell word expansions + (*note Shell Expansions::). + +`history-expand-line (M-^)' + Perform history expansion on the current line. + +`magic-space ()' + Perform history expansion on the current line and insert a space + (*note History Interaction::). + +`alias-expand-line ()' + Perform alias expansion on the current line (*note Aliases::). + +`history-and-alias-expand-line ()' + Perform history and alias expansion on the current line. + +`insert-last-argument (M-. or M-_)' + A synonym for `yank-last-arg'. + +`operate-and-get-next (C-o)' + Accept the current line for execution and fetch the next line + relative to the current line from the history for editing. Any + argument is ignored. + +`edit-and-execute-command (C-xC-e)' + Invoke an editor on the current command line, and execute the + result as shell commands. Bash attempts to invoke `$VISUAL', + `$EDITOR', and `emacs' as the editor, in that order. + + + +File: bashref.info, Node: Readline vi Mode, Next: Programmable Completion, Prev: Bindable Readline Commands, Up: Command Line Editing + +8.5 Readline vi Mode +==================== + +While the Readline library does not have a full set of `vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline `vi' mode behaves as specified in the POSIX 1003.2 +standard. + + In order to switch interactively between `emacs' and `vi' editing +modes, use the `set -o emacs' and `set -o vi' commands (*note The Set +Builtin::). The Readline default is `emacs' mode. + + When you enter a line in `vi' mode, you are already placed in +`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches +you into `command' mode, where you can edit the text of the line with +the standard `vi' movement keys, move to previous history lines with +`k' and subsequent lines with `j', and so forth. + + +File: bashref.info, Node: Programmable Completion, Next: Programmable Completion Builtins, Prev: Readline vi Mode, Up: Command Line Editing + +8.6 Programmable Completion +=========================== + +When word completion is attempted for an argument to a command for +which a completion specification (a COMPSPEC) has been defined using +the `complete' builtin (*note Programmable Completion Builtins::), the +programmable completion facilities are invoked. + + First, the command name is identified. If a compspec has been +defined for that command, the compspec is used to generate the list of +possible completions for the word. If the command word is the empty +string (completion attempted at the beginning of an empty line), any +compspec defined with the `-E' option to `complete' is used. If the +command word is a full pathname, a compspec for the full pathname is +searched for first. If no compspec is found for the full pathname, an +attempt is made to find a compspec for the portion following the final +slash. If those searches do not result in a compspec, any compspec +defined with the `-D' option to `complete' is used as the default. + + Once a compspec has been found, it is used to generate the list of +matching words. If a compspec is not found, the default Bash completion +described above (*note Commands For Completion::) is performed. + + First, the actions specified by the compspec are used. Only matches +which are prefixed by the word being completed are returned. When the +`-f' or `-d' option is used for filename or directory name completion, +the shell variable `FIGNORE' is used to filter the matches. *Note Bash +Variables::, for a description of `FIGNORE'. + + Any completions specified by a filename expansion pattern to the +`-G' option are generated next. The words generated by the pattern +need not match the word being completed. The `GLOBIGNORE' shell +variable is not used to filter the matches, but the `FIGNORE' shell +variable is used. + + Next, the string specified as the argument to the `-W' option is +considered. The string is first split using the characters in the `IFS' +special variable as delimiters. Shell quoting is honored. Each word +is then expanded using brace expansion, tilde expansion, parameter and +variable expansion, command substitution, and arithmetic expansion, as +described above (*note Shell Expansions::). The results are split +using the rules described above (*note Word Splitting::). The results +of the expansion are prefix-matched against the word being completed, +and the matching words become the possible completions. + + After these matches have been generated, any shell function or +command specified with the `-F' and `-C' options is invoked. When the +command or function is invoked, the `COMP_LINE', `COMP_POINT', +`COMP_KEY', and `COMP_TYPE' variables are assigned values as described +above (*note Bash Variables::). If a shell function is being invoked, +the `COMP_WORDS' and `COMP_CWORD' variables are also set. When the +function or command is invoked, the first argument is the name of the +command whose arguments are being completed, the second argument is the +word being completed, and the third argument is the word preceding the +word being completed on the current command line. No filtering of the +generated completions against the word being completed is performed; +the function or command has complete freedom in generating the matches. + + Any function specified with `-F' is invoked first. The function may +use any of the shell facilities, including the `compgen' and `compopt' +builtins described below (*note Programmable Completion Builtins::), to +generate the matches. It must put the possible completions in the +`COMPREPLY' array variable. + + Next, any command specified with the `-C' option is invoked in an +environment equivalent to command substitution. It should print a list +of completions, one per line, to the standard output. Backslash may be +used to escape a newline, if necessary. + + After all of the possible completions are generated, any filter +specified with the `-X' option is applied to the list. The filter is a +pattern as used for pathname expansion; a `&' in the pattern is +replaced with the text of the word being completed. A literal `&' may +be escaped with a backslash; the backslash is removed before attempting +a match. Any completion that matches the pattern will be removed from +the list. A leading `!' negates the pattern; in this case any +completion not matching the pattern will be removed. + + Finally, any prefix and suffix specified with the `-P' and `-S' +options are added to each member of the completion list, and the result +is returned to the Readline completion code as the list of possible +completions. + + If the previously-applied actions do not generate any matches, and +the `-o dirnames' option was supplied to `complete' when the compspec +was defined, directory name completion is attempted. + + If the `-o plusdirs' option was supplied to `complete' when the +compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. + + By default, if a compspec is found, whatever it generates is +returned to the completion code as the full set of possible completions. +The default Bash completions are not attempted, and the Readline default +of filename completion is disabled. If the `-o bashdefault' option was +supplied to `complete' when the compspec was defined, the default Bash +completions are attempted if the compspec generates no matches. If the +`-o default' option was supplied to `complete' when the compspec was +defined, Readline's default completion will be performed if the +compspec (and, if attempted, the default Bash completions) generate no +matches. + + When a compspec indicates that directory name completion is desired, +the programmable completion functions force Readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the MARK-DIRECTORIES Readline variable, regardless of the +setting of the MARK-SYMLINKED-DIRECTORIES Readline variable. + + There is some support for dynamically modifying completions. This is +most useful when used in combination with a default completion specified +with `-D'. It's possible for shell functions executed as completion +handlers to indicate that completion should be retried by returning an +exit status of 124. If a shell function returns 124, and changes the +compspec associated with the command on which completion is being +attempted (supplied as the first argument when the function is +executed), programmable completion restarts from the beginning, with an +attempt to find a compspec for that command. This allows a set of +completions to be built dynamically as completion is attempted, rather +than being loaded all at once. + + For instance, assuming that there is a library of compspecs, each +kept in a file corresponding to the name of the command, the following +default completion function would load completions dynamically: + + _completion_loader() + { + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 + } + complete -D -F _completion_loader + + +File: bashref.info, Node: Programmable Completion Builtins, Prev: Programmable Completion, Up: Command Line Editing + +8.7 Programmable Completion Builtins +==================================== + +Two builtin commands are available to manipulate the programmable +completion facilities. + +`compgen' + `compgen [OPTION] [WORD]' + + Generate possible completion matches for WORD according to the + OPTIONs, which may be any option accepted by the `complete' + builtin with the exception of `-p' and `-r', and write the matches + to the standard output. When using the `-F' or `-C' options, the + various shell variables set by the programmable completion + facilities, while available, will not have useful values. + + The matches will be generated in the same way as if the + programmable completion code had generated them directly from a + completion specification with the same flags. If WORD is + specified, only those completions matching WORD will be displayed. + + The return value is true unless an invalid option is supplied, or + no matches were generated. + +`complete' + `complete [-abcdefgjksuv] [-o COMP-OPTION] [-DE] [-A ACTION] [-G GLOBPAT] [-W WORDLIST] + [-F FUNCTION] [-C COMMAND] [-X FILTERPAT] + [-P PREFIX] [-S SUFFIX] NAME [NAME ...]' + `complete -pr [-DE] [NAME ...]' + + Specify how arguments to each NAME should be completed. If the + `-p' option is supplied, or if no options are supplied, existing + completion specifications are printed in a way that allows them to + be reused as input. The `-r' option removes a completion + specification for each NAME, or, if no NAMEs are supplied, all + completion specifications. The `-D' option indicates that the + remaining options and actions should apply to the "default" + command completion; that is, completion attempted on a command for + which no completion has previously been defined. The `-E' option + indicates that the remaining options and actions should apply to + "empty" command completion; that is, completion attempted on a + blank line. + + The process of applying these completion specifications when word + completion is attempted is described above (*note Programmable + Completion::). The `-D' option takes precedence over `-E'. + + Other options, if specified, have the following meanings. The + arguments to the `-G', `-W', and `-X' options (and, if necessary, + the `-P' and `-S' options) should be quoted to protect them from + expansion before the `complete' builtin is invoked. + + `-o COMP-OPTION' + The COMP-OPTION controls several aspects of the compspec's + behavior beyond the simple generation of completions. + COMP-OPTION may be one of: + + `bashdefault' + Perform the rest of the default Bash completions if the + compspec generates no matches. + + `default' + Use Readline's default filename completion if the + compspec generates no matches. + + `dirnames' + Perform directory name completion if the compspec + generates no matches. + + `filenames' + Tell Readline that the compspec generates filenames, so + it can perform any filename-specific processing (like + adding a slash to directory names quoting special + characters, or suppressing trailing spaces). This + option is intended to be used with shell functions + specified with `-F'. + + `nospace' + Tell Readline not to append a space (the default) to + words completed at the end of the line. + + `plusdirs' + After any matches defined by the compspec are generated, + directory name completion is attempted and any matches + are added to the results of the other actions. + + + `-A ACTION' + The ACTION may be one of the following to generate a list of + possible completions: + + `alias' + Alias names. May also be specified as `-a'. + + `arrayvar' + Array variable names. + + `binding' + Readline key binding names (*note Bindable Readline + Commands::). + + `builtin' + Names of shell builtin commands. May also be specified + as `-b'. + + `command' + Command names. May also be specified as `-c'. + + `directory' + Directory names. May also be specified as `-d'. + + `disabled' + Names of disabled shell builtins. + + `enabled' + Names of enabled shell builtins. + + `export' + Names of exported shell variables. May also be + specified as `-e'. + + `file' + File names. May also be specified as `-f'. + + `function' + Names of shell functions. + + `group' + Group names. May also be specified as `-g'. + + `helptopic' + Help topics as accepted by the `help' builtin (*note + Bash Builtins::). + + `hostname' + Hostnames, as taken from the file specified by the + `HOSTFILE' shell variable (*note Bash Variables::). + + `job' + Job names, if job control is active. May also be + specified as `-j'. + + `keyword' + Shell reserved words. May also be specified as `-k'. + + `running' + Names of running jobs, if job control is active. + + `service' + Service names. May also be specified as `-s'. + + `setopt' + Valid arguments for the `-o' option to the `set' builtin + (*note The Set Builtin::). + + `shopt' + Shell option names as accepted by the `shopt' builtin + (*note Bash Builtins::). + + `signal' + Signal names. + + `stopped' + Names of stopped jobs, if job control is active. + + `user' + User names. May also be specified as `-u'. + + `variable' + Names of all shell variables. May also be specified as + `-v'. + + `-G GLOBPAT' + The filename expansion pattern GLOBPAT is expanded to generate + the possible completions. + + `-W WORDLIST' + The WORDLIST is split using the characters in the `IFS' + special variable as delimiters, and each resultant word is + expanded. The possible completions are the members of the + resultant list which match the word being completed. + + `-C COMMAND' + COMMAND is executed in a subshell environment, and its output + is used as the possible completions. + + `-F FUNCTION' + The shell function FUNCTION is executed in the current shell + environment. When it finishes, the possible completions are + retrieved from the value of the `COMPREPLY' array variable. + + `-X FILTERPAT' + FILTERPAT is a pattern as used for filename expansion. It is + applied to the list of possible completions generated by the + preceding options and arguments, and each completion matching + FILTERPAT is removed from the list. A leading `!' in + FILTERPAT negates the pattern; in this case, any completion + not matching FILTERPAT is removed. + + `-P PREFIX' + PREFIX is added at the beginning of each possible completion + after all other options have been applied. + + `-S SUFFIX' + SUFFIX is appended to each possible completion after all + other options have been applied. + + The return value is true unless an invalid option is supplied, an + option other than `-p' or `-r' is supplied without a NAME + argument, an attempt is made to remove a completion specification + for a NAME for which no specification exists, or an error occurs + adding a completion specification. + +`compopt' + `compopt' [-o OPTION] [-DE] [+o OPTION] [NAME] + Modify completion options for each NAME according to the OPTIONs, + or for the currently-execution completion if no NAMEs are supplied. + If no OPTIONs are given, display the completion options for each + NAME or the current completion. The possible values of OPTION are + those valid for the `complete' builtin described above. The `-D' + option indicates that the remaining options should apply to the + "default" command completion; that is, completion attempted on a + command for which no completion has previously been defined. The + `-E' option indicates that the remaining options should apply to + "empty" command completion; that is, completion attempted on a + blank line. + + The `-D' option takes precedence over `-E'. + + The return value is true unless an invalid option is supplied, an + attempt is made to modify the options for a NAME for which no + completion specification exists, or an output error occurs. + + + +File: bashref.info, Node: Using History Interactively, Next: Installing Bash, Prev: Command Line Editing, Up: Top + +9 Using History Interactively +***************************** + +This chapter describes how to use the GNU History Library +interactively, from a user's standpoint. It should be considered a +user's guide. For information on using the GNU History Library in +other programs, see the GNU Readline Library Manual. + +* Menu: + +* Bash History Facilities:: How Bash lets you manipulate your command + history. +* Bash History Builtins:: The Bash builtin commands that manipulate + the command history. +* History Interaction:: What it feels like using History as a user. + + +File: bashref.info, Node: Bash History Facilities, Next: Bash History Builtins, Up: Using History Interactively + +9.1 Bash History Facilities +=========================== + +When the `-o history' option to the `set' builtin is enabled (*note The +Set Builtin::), the shell provides access to the "command history", the +list of commands previously typed. The value of the `HISTSIZE' shell +variable is used as the number of commands to save in a history list. +The text of the last `$HISTSIZE' commands (default 500) is saved. The +shell stores each command in the history list prior to parameter and +variable expansion but after history expansion is performed, subject to +the values of the shell variables `HISTIGNORE' and `HISTCONTROL'. + + When the shell starts up, the history is initialized from the file +named by the `HISTFILE' variable (default `~/.bash_history'). The file +named by the value of `HISTFILE' is truncated, if necessary, to contain +no more than the number of lines specified by the value of the +`HISTFILESIZE' variable. When an interactive shell exits, the last +`$HISTSIZE' lines are copied from the history list to the file named by +`$HISTFILE'. If the `histappend' shell option is set (*note Bash +Builtins::), the lines are appended to the history file, otherwise the +history file is overwritten. If `HISTFILE' is unset, or if the history +file is unwritable, the history is not saved. After saving the +history, the history file is truncated to contain no more than +`$HISTFILESIZE' lines. If `HISTFILESIZE' is not set, no truncation is +performed. + + If the `HISTTIMEFORMAT' is set, the time stamp information +associated with each history entry is written to the history file, +marked with the history comment character. When the history file is +read, lines beginning with the history comment character followed +immediately by a digit are interpreted as timestamps for the previous +history line. + + The builtin command `fc' may be used to list or edit and re-execute +a portion of the history list. The `history' builtin may be used to +display or modify the history list and manipulate the history file. +When using command-line editing, search commands are available in each +editing mode that provide access to the history list (*note Commands +For History::). + + The shell allows control over which commands are saved on the history +list. The `HISTCONTROL' and `HISTIGNORE' variables may be set to cause +the shell to save only a subset of the commands entered. The `cmdhist' +shell option, if enabled, causes the shell to attempt to save each line +of a multi-line command in the same history entry, adding semicolons +where necessary to preserve syntactic correctness. The `lithist' shell +option causes the shell to save the command with embedded newlines +instead of semicolons. The `shopt' builtin is used to set these +options. *Note Bash Builtins::, for a description of `shopt'. + + +File: bashref.info, Node: Bash History Builtins, Next: History Interaction, Prev: Bash History Facilities, Up: Using History Interactively + +9.2 Bash History Builtins +========================= + +Bash provides two builtin commands which manipulate the history list +and history file. + +`fc' + `fc [-e ENAME] [-lnr] [FIRST] [LAST]' + `fc -s [PAT=REP] [COMMAND]' + + Fix Command. In the first form, a range of commands from FIRST to + LAST is selected from the history list. Both FIRST and LAST may + be specified as a string (to locate the most recent command + beginning with that string) or as a number (an index into the + history list, where a negative number is used as an offset from the + current command number). If LAST is not specified it is set to + FIRST. If FIRST is not specified it is set to the previous + command for editing and -16 for listing. If the `-l' flag is + given, the commands are listed on standard output. The `-n' flag + suppresses the command numbers when listing. The `-r' flag + reverses the order of the listing. Otherwise, the editor given by + ENAME is invoked on a file containing those commands. If ENAME is + not given, the value of the following variable expansion is used: + `${FCEDIT:-${EDITOR:-vi}}'. This says to use the value of the + `FCEDIT' variable if set, or the value of the `EDITOR' variable if + that is set, or `vi' if neither is set. When editing is complete, + the edited commands are echoed and executed. + + In the second form, COMMAND is re-executed after each instance of + PAT in the selected command is replaced by REP. + + A useful alias to use with the `fc' command is `r='fc -s'', so + that typing `r cc' runs the last command beginning with `cc' and + typing `r' re-executes the last command (*note Aliases::). + +`history' + history [N] + history -c + history -d OFFSET + history [-anrw] [FILENAME] + history -ps ARG + + With no options, display the history list with line numbers. + Lines prefixed with a `*' have been modified. An argument of N + lists only the last N lines. If the shell variable + `HISTTIMEFORMAT' is set and not null, it is used as a format + string for STRFTIME to display the time stamp associated with each + displayed history entry. No intervening blank is printed between + the formatted time stamp and the history line. + + Options, if supplied, have the following meanings: + + `-c' + Clear the history list. This may be combined with the other + options to replace the history list completely. + + `-d OFFSET' + Delete the history entry at position OFFSET. OFFSET should + be specified as it appears when the history is displayed. + + `-a' + Append the new history lines (history lines entered since the + beginning of the current Bash session) to the history file. + + `-n' + Append the history lines not already read from the history + file to the current history list. These are lines appended + to the history file since the beginning of the current Bash + session. + + `-r' + Read the current history file and append its contents to the + history list. + + `-w' + Write out the current history to the history file. + + `-p' + Perform history substitution on the ARGs and display the + result on the standard output, without storing the results in + the history list. + + `-s' + The ARGs are added to the end of the history list as a single + entry. + + + When any of the `-w', `-r', `-a', or `-n' options is used, if + FILENAME is given, then it is used as the history file. If not, + then the value of the `HISTFILE' variable is used. + + + +File: bashref.info, Node: History Interaction, Prev: Bash History Builtins, Up: Using History Interactively + +9.3 History Expansion +===================== + +The History library provides a history expansion feature that is similar +to the history expansion provided by `csh'. This section describes the +syntax used to manipulate the history information. + + History expansions introduce words from the history list into the +input stream, making it easy to repeat commands, insert the arguments +to a previous command into the current input line, or fix errors in +previous commands quickly. + + History expansion takes place in two parts. The first is to +determine which line from the history list should be used during +substitution. The second is to select portions of that line for +inclusion into the current one. The line selected from the history is +called the "event", and the portions of that line that are acted upon +are called "words". Various "modifiers" are available to manipulate +the selected words. The line is broken into words in the same fashion +that Bash does, so that several words surrounded by quotes are +considered one word. History expansions are introduced by the +appearance of the history expansion character, which is `!' by default. +Only `\' and `'' may be used to escape the history expansion character. + + Several shell options settable with the `shopt' builtin (*note Bash +Builtins::) may be used to tailor the behavior of history expansion. +If the `histverify' shell option is enabled, and Readline is being +used, history substitutions are not immediately passed to the shell +parser. Instead, the expanded line is reloaded into the Readline +editing buffer for further modification. If Readline is being used, +and the `histreedit' shell option is enabled, a failed history +expansion will be reloaded into the Readline editing buffer for +correction. The `-p' option to the `history' builtin command may be +used to see what a history expansion will do before using it. The `-s' +option to the `history' builtin may be used to add commands to the end +of the history list without actually executing them, so that they are +available for subsequent recall. This is most useful in conjunction +with Readline. + + The shell allows control of the various characters used by the +history expansion mechanism with the `histchars' variable, as explained +above (*note Bash Variables::). The shell uses the history comment +character to mark history timestamps when writing the history file. + +* Menu: + +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. + + +File: bashref.info, Node: Event Designators, Next: Word Designators, Up: History Interaction + +9.3.1 Event Designators +----------------------- + +An event designator is a reference to a command line entry in the +history list. + +`!' + Start a history substitution, except when followed by a space, tab, + the end of the line, `=' or `(' (when the `extglob' shell option + is enabled using the `shopt' builtin). + +`!N' + Refer to command line N. + +`!-N' + Refer to the command N lines back. + +`!!' + Refer to the previous command. This is a synonym for `!-1'. + +`!STRING' + Refer to the most recent command starting with STRING. + +`!?STRING[?]' + Refer to the most recent command containing STRING. The trailing + `?' may be omitted if the STRING is followed immediately by a + newline. + +`^STRING1^STRING2^' + Quick Substitution. Repeat the last command, replacing STRING1 + with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. + +`!#' + The entire command line typed so far. + + + +File: bashref.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction + +9.3.2 Word Designators +---------------------- + +Word designators are used to select desired words from the event. A +`:' separates the event specification from the word designator. It may +be omitted if the word designator begins with a `^', `$', `*', `-', or +`%'. Words are numbered from the beginning of the line, with the first +word being denoted by 0 (zero). Words are inserted into the current +line separated by single spaces. + + For example, + +`!!' + designates the preceding command. When you type this, the + preceding command is repeated in toto. + +`!!:$' + designates the last argument of the preceding command. This may be + shortened to `!$'. + +`!fi:2' + designates the second argument of the most recent command starting + with the letters `fi'. + + Here are the word designators: + +`0 (zero)' + The `0'th word. For many applications, this is the command word. + +`N' + The Nth word. + +`^' + The first argument; that is, word 1. + +`$' + The last argument. + +`%' + The word matched by the most recent `?STRING?' search. + +`X-Y' + A range of words; `-Y' abbreviates `0-Y'. + +`*' + All of the words, except the `0'th. This is a synonym for `1-$'. + It is not an error to use `*' if there is just one word in the + event; the empty string is returned in that case. + +`X*' + Abbreviates `X-$' + +`X-' + Abbreviates `X-$' like `X*', but omits the last word. + + + If a word designator is supplied without an event specification, the +previous command is used as the event. + + +File: bashref.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction + +9.3.3 Modifiers +--------------- + +After the optional word designator, you can add a sequence of one or +more of the following modifiers, each preceded by a `:'. + +`h' + Remove a trailing pathname component, leaving only the head. + +`t' + Remove all leading pathname components, leaving the tail. + +`r' + Remove a trailing suffix of the form `.SUFFIX', leaving the + basename. + +`e' + Remove all but the trailing suffix. + +`p' + Print the new command but do not execute it. + +`q' + Quote the substituted words, escaping further substitutions. + +`x' + Quote the substituted words as with `q', but break into words at + spaces, tabs, and newlines. + +`s/OLD/NEW/' + Substitute NEW for the first occurrence of OLD in the event line. + Any delimiter may be used in place of `/'. The delimiter may be + quoted in OLD and NEW with a single backslash. If `&' appears in + NEW, it is replaced by OLD. A single backslash will quote the + `&'. The final delimiter is optional if it is the last character + on the input line. + +`&' + Repeat the previous substitution. + +`g' +`a' + Cause changes to be applied over the entire event line. Used in + conjunction with `s', as in `gs/OLD/NEW/', or with `&'. + +`G' + Apply the following `s' modifier once to each word in the event. + + + +File: bashref.info, Node: Installing Bash, Next: Reporting Bugs, Prev: Using History Interactively, Up: Top + +10 Installing Bash +****************** + +This chapter provides basic instructions for installing Bash on the +various supported platforms. The distribution supports the GNU +operating systems, nearly every version of Unix, and several non-Unix +systems such as BeOS and Interix. Other independent ports exist for +MS-DOS, OS/2, and Windows platforms. + +* Menu: + +* Basic Installation:: Installation instructions. +* Compilers and Options:: How to set special options for various + systems. +* Compiling For Multiple Architectures:: How to compile Bash for more + than one kind of system from + the same source tree. +* Installation Names:: How to set the various paths used by the installation. +* Specifying the System Type:: How to configure Bash for a particular system. +* Sharing Defaults:: How to share default configuration values among GNU + programs. +* Operation Controls:: Options recognized by the configuration program. +* Optional Features:: How to enable and disable optional features when + building Bash. + + +File: bashref.info, Node: Basic Installation, Next: Compilers and Options, Up: Installing Bash + +10.1 Basic Installation +======================= + +These are installation instructions for Bash. + + The simplest way to compile Bash is: + + 1. `cd' to the directory containing the source code and type + `./configure' to configure Bash for your system. If you're using + `csh' on an old version of System V, you might need to type `sh + ./configure' instead to prevent `csh' from trying to execute + `configure' itself. + + Running `configure' takes some time. While running, it prints + messages telling which features it is checking for. + + 2. Type `make' to compile Bash and build the `bashbug' bug reporting + script. + + 3. Optionally, type `make tests' to run the Bash test suite. + + 4. Type `make install' to install `bash' and `bashbug'. This will + also install the manual pages and Info file. + + + The `configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a `Makefile' in each directory of the package +(the top directory, the `builtins', `doc', and `support' directories, +each directory under `lib', and several others). It also creates a +`config.h' file containing system-dependent definitions. Finally, it +creates a shell script named `config.status' that you can run in the +future to recreate the current configuration, a file `config.cache' +that saves the results of its tests to speed up reconfiguring, and a +file `config.log' containing compiler output (useful mainly for +debugging `configure'). If at some point `config.cache' contains +results you don't want to keep, you may remove or edit it. + + To find out more about the options and arguments that the +`configure' script understands, type + + bash-2.04$ ./configure --help + +at the Bash prompt in your Bash source directory. + + If you need to do unusual things to compile Bash, please try to +figure out how `configure' could check whether or not to do them, and +mail diffs or instructions to <bash-maintainers@gnu.org> so they can be +considered for the next release. + + The file `configure.in' is used to create `configure' by a program +called Autoconf. You only need `configure.in' if you want to change it +or regenerate `configure' using a newer version of Autoconf. If you do +this, make sure you are using Autoconf version 2.50 or newer. + + You can remove the program binaries and object files from the source +code directory by typing `make clean'. To also remove the files that +`configure' created (so you can compile Bash for a different kind of +computer), type `make distclean'. + + +File: bashref.info, Node: Compilers and Options, Next: Compiling For Multiple Architectures, Prev: Basic Installation, Up: Installing Bash + +10.2 Compilers and Options +========================== + +Some systems require unusual options for compilation or linking that +the `configure' script does not know about. You can give `configure' +initial values for variables by setting them in the environment. Using +a Bourne-compatible shell, you can do that on the command line like +this: + + CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure + + On systems that have the `env' program, you can do it like this: + + env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure + + The configuration process uses GCC to build Bash if it is available. + + +File: bashref.info, Node: Compiling For Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Installing Bash + +10.3 Compiling For Multiple Architectures +========================================= + +You can compile Bash for more than one kind of computer at the same +time, by placing the object files for each architecture in their own +directory. To do this, you must use a version of `make' that supports +the `VPATH' variable, such as GNU `make'. `cd' to the directory where +you want the object files and executables to go and run the `configure' +script from the source directory. You may need to supply the +`--srcdir=PATH' argument to tell `configure' where the source files +are. `configure' automatically checks for the source code in the +directory that `configure' is in and in `..'. + + If you have to use a `make' that does not supports the `VPATH' +variable, you can compile Bash for one architecture at a time in the +source code directory. After you have installed Bash for one +architecture, use `make distclean' before reconfiguring for another +architecture. + + Alternatively, if your system supports symbolic links, you can use +the `support/mkclone' script to create a build tree which has symbolic +links back to each file in the source directory. Here's an example +that creates a build directory in the current directory from a source +directory `/usr/gnu/src/bash-2.0': + + bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . + +The `mkclone' script requires Bash, so you must have already built Bash +for at least one architecture before you can create build directories +for other architectures. + + +File: bashref.info, Node: Installation Names, Next: Specifying the System Type, Prev: Compiling For Multiple Architectures, Up: Installing Bash + +10.4 Installation Names +======================= + +By default, `make install' will install into `/usr/local/bin', +`/usr/local/man', etc. You can specify an installation prefix other +than `/usr/local' by giving `configure' the option `--prefix=PATH', or +by specifying a value for the `DESTDIR' `make' variable when running +`make install'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give `configure' the option `--exec-prefix=PATH', `make install' will +use PATH as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + + +File: bashref.info, Node: Specifying the System Type, Next: Sharing Defaults, Prev: Installation Names, Up: Installing Bash + +10.5 Specifying the System Type +=============================== + +There may be some features `configure' can not figure out +automatically, but need to determine by the type of host Bash will run +on. Usually `configure' can figure that out, but if it prints a +message saying it can not guess the host type, give it the +`--host=TYPE' option. `TYPE' can either be a short name for the system +type, such as `sun4', or a canonical name with three fields: +`CPU-COMPANY-SYSTEM' (e.g., `i386-unknown-freebsd4.2'). + + See the file `support/config.sub' for the possible values of each +field. + + +File: bashref.info, Node: Sharing Defaults, Next: Operation Controls, Prev: Specifying the System Type, Up: Installing Bash + +10.6 Sharing Defaults +===================== + +If you want to set default values for `configure' scripts to share, you +can create a site shell script called `config.site' that gives default +values for variables like `CC', `cache_file', and `prefix'. `configure' +looks for `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Or, you can set the +`CONFIG_SITE' environment variable to the location of the site script. +A warning: the Bash `configure' looks for a site script, but not all +`configure' scripts do. + + +File: bashref.info, Node: Operation Controls, Next: Optional Features, Prev: Sharing Defaults, Up: Installing Bash + +10.7 Operation Controls +======================= + +`configure' recognizes the following options to control how it operates. + +`--cache-file=FILE' + Use and save the results of the tests in FILE instead of + `./config.cache'. Set FILE to `/dev/null' to disable caching, for + debugging `configure'. + +`--help' + Print a summary of the options to `configure', and exit. + +`--quiet' +`--silent' +`-q' + Do not print messages saying which checks are being made. + +`--srcdir=DIR' + Look for the Bash source code in directory DIR. Usually + `configure' can determine that directory automatically. + +`--version' + Print the version of Autoconf used to generate the `configure' + script, and exit. + + `configure' also accepts some other, not widely used, boilerplate +options. `configure --help' prints the complete list. + + +File: bashref.info, Node: Optional Features, Prev: Operation Controls, Up: Installing Bash + +10.8 Optional Features +====================== + +The Bash `configure' has a number of `--enable-FEATURE' options, where +FEATURE indicates an optional part of Bash. There are also several +`--with-PACKAGE' options, where PACKAGE is something like `bash-malloc' +or `purify'. To turn off the default use of a package, use +`--without-PACKAGE'. To configure Bash without a feature that is +enabled by default, use `--disable-FEATURE'. + + Here is a complete list of the `--enable-' and `--with-' options +that the Bash `configure' recognizes. + +`--with-afs' + Define if you are using the Andrew File System from Transarc. + +`--with-bash-malloc' + Use the Bash version of `malloc' in the directory `lib/malloc'. + This is not the same `malloc' that appears in GNU libc, but an + older version originally derived from the 4.2 BSD `malloc'. This + `malloc' is very fast, but wastes some space on each allocation. + This option is enabled by default. The `NOTES' file contains a + list of systems for which this should be turned off, and + `configure' disables this option automatically for a number of + systems. + +`--with-curses' + Use the curses library instead of the termcap library. This should + be supplied if your system has an inadequate or incomplete termcap + database. + +`--with-gnu-malloc' + A synonym for `--with-bash-malloc'. + +`--with-installed-readline[=PREFIX]' + Define this to make Bash link with a locally-installed version of + Readline rather than the version in `lib/readline'. This works + only with Readline 5.0 and later versions. If PREFIX is `yes' or + not supplied, `configure' uses the values of the make variables + `includedir' and `libdir', which are subdirectories of `prefix' by + default, to find the installed version of Readline if it is not in + the standard system include and library directories. If PREFIX is + `no', Bash links with the version in `lib/readline'. If PREFIX is + set to any other value, `configure' treats it as a directory + pathname and looks for the installed version of Readline in + subdirectories of that directory (include files in + PREFIX/`include' and the library in PREFIX/`lib'). + +`--with-purify' + Define this to use the Purify memory allocation checker from + Rational Software. + +`--enable-minimal-config' + This produces a shell with minimal features, close to the + historical Bourne shell. + + There are several `--enable-' options that alter how Bash is +compiled and linked, rather than changing run-time features. + +`--enable-largefile' + Enable support for large files + (http://www.sas.com/standards/large_file/x_open.20Mar96.html) if + the operating system requires special compiler options to build + programs which can access large files. This is enabled by + default, if the operating system provides large file support. + +`--enable-profiling' + This builds a Bash binary that produces profiling information to be + processed by `gprof' each time it is executed. + +`--enable-static-link' + This causes Bash to be linked statically, if `gcc' is being used. + This could be used to build a version to use as root's shell. + + The `minimal-config' option can be used to disable all of the +following options, but it is processed first, so individual options may +be enabled using `enable-FEATURE'. + + All of the following options except for `disabled-builtins' and +`xpg-echo-default' are enabled by default, unless the operating system +does not provide the necessary support. + +`--enable-alias' + Allow alias expansion and include the `alias' and `unalias' + builtins (*note Aliases::). + +`--enable-arith-for-command' + Include support for the alternate form of the `for' command that + behaves like the C language `for' statement (*note Looping + Constructs::). + +`--enable-array-variables' + Include support for one-dimensional array shell variables (*note + Arrays::). + +`--enable-bang-history' + Include support for `csh'-like history substitution (*note History + Interaction::). + +`--enable-brace-expansion' + Include `csh'-like brace expansion ( `b{a,b}c' ==> `bac bbc' ). + See *note Brace Expansion::, for a complete description. + +`--enable-casemod-attributes' + Include support for case-modifying attributes in the `declare' + builtin and assignment statements. Variables with the UPPERCASE + attribute, for example, will have their values converted to + uppercase upon assignment. + +`--enable-casemod-expansion' + Include support for case-modifying word expansions. + +`--enable-command-timing' + Include support for recognizing `time' as a reserved word and for + displaying timing statistics for the pipeline following `time' + (*note Pipelines::). This allows pipelines as well as shell + builtins and functions to be timed. + +`--enable-cond-command' + Include support for the `[[' conditional command. (*note + Conditional Constructs::). + +`--enable-cond-regexp' + Include support for matching POSIX regular expressions using the + `=~' binary operator in the `[[' conditional command. (*note + Conditional Constructs::). + +`--enable-coprocesses' + Include support for coprocesses and the `coproc' reserved word + (*note Pipelines::). + +`--enable-debugger' + Include support for the bash debugger (distributed separately). + +`--enable-directory-stack' + Include support for a `csh'-like directory stack and the `pushd', + `popd', and `dirs' builtins (*note The Directory Stack::). + +`--enable-disabled-builtins' + Allow builtin commands to be invoked via `builtin xxx' even after + `xxx' has been disabled using `enable -n xxx'. See *note Bash + Builtins::, for details of the `builtin' and `enable' builtin + commands. + +`--enable-dparen-arithmetic' + Include support for the `((...))' command (*note Conditional + Constructs::). + +`--enable-extended-glob' + Include support for the extended pattern matching features + described above under *note Pattern Matching::. + +`--enable-extended-glob-default' + Set the default value of the EXTGLOB shell option described above + under *note The Shopt Builtin:: to be enabled. + +`--enable-help-builtin' + Include the `help' builtin, which displays help on shell builtins + and variables (*note Bash Builtins::). + +`--enable-history' + Include command history and the `fc' and `history' builtin + commands (*note Bash History Facilities::). + +`--enable-job-control' + This enables the job control features (*note Job Control::), if + the operating system supports them. + +`--enable-multibyte' + This enables support for multibyte characters if the operating + system provides the necessary support. + +`--enable-net-redirections' + This enables the special handling of filenames of the form + `/dev/tcp/HOST/PORT' and `/dev/udp/HOST/PORT' when used in + redirections (*note Redirections::). + +`--enable-process-substitution' + This enables process substitution (*note Process Substitution::) if + the operating system provides the necessary support. + +`--enable-progcomp' + Enable the programmable completion facilities (*note Programmable + Completion::). If Readline is not enabled, this option has no + effect. + +`--enable-prompt-string-decoding' + Turn on the interpretation of a number of backslash-escaped + characters in the `$PS1', `$PS2', `$PS3', and `$PS4' prompt + strings. See *note Printing a Prompt::, for a complete list of + prompt string escape sequences. + +`--enable-readline' + Include support for command-line editing and history with the Bash + version of the Readline library (*note Command Line Editing::). + +`--enable-restricted' + Include support for a "restricted shell". If this is enabled, + Bash, when called as `rbash', enters a restricted mode. See *note + The Restricted Shell::, for a description of restricted mode. + +`--enable-select' + Include the `select' builtin, which allows the generation of simple + menus (*note Conditional Constructs::). + +`--enable-separate-helpfiles' + Use external files for the documentation displayed by the `help' + builtin instead of storing the text internally. + +`--enable-single-help-strings' + Store the text displayed by the `help' builtin as a single string + for each help topic. This aids in translating the text to + different languages. You may need to disable this if your + compiler cannot handle very long string literals. + +`--enable-strict-posix-default' + Make Bash POSIX-conformant by default (*note Bash POSIX Mode::). + +`--enable-usg-echo-default' + A synonym for `--enable-xpg-echo-default'. + +`--enable-xpg-echo-default' + Make the `echo' builtin expand backslash-escaped characters by + default, without requiring the `-e' option. This sets the default + value of the `xpg_echo' shell option to `on', which makes the Bash + `echo' behave more like the version specified in the Single Unix + Specification, version 3. *Note Bash Builtins::, for a + description of the escape sequences that `echo' recognizes. + + + The file `config-top.h' contains C Preprocessor `#define' statements +for options which are not settable from `configure'. Some of these are +not meant to be changed; beware of the consequences if you do. Read +the comments associated with each definition for more information about +its effect. + + +File: bashref.info, Node: Reporting Bugs, Next: Major Differences From The Bourne Shell, Prev: Installing Bash, Up: Top + +Appendix A Reporting Bugs +************************* + +Please report all bugs you find in Bash. But first, you should make +sure that it really is a bug, and that it appears in the latest version +of Bash. The latest version of Bash is always available for FTP from +`ftp://ftp.gnu.org/pub/gnu/bash/'. + + Once you have determined that a bug actually exists, use the +`bashbug' command to submit a bug report. If you have a fix, you are +encouraged to mail that as well! Suggestions and `philosophical' bug +reports may be mailed to <bug-bash@gnu.org> or posted to the Usenet +newsgroup `gnu.bash.bug'. + + All bug reports should include: + * The version number of Bash. + + * The hardware and operating system. + + * The compiler used to compile Bash. + + * A description of the bug behaviour. + + * A short script or `recipe' which exercises the bug and may be used + to reproduce it. + +`bashbug' inserts the first three items automatically into the template +it provides for filing a bug report. + + Please send all reports concerning this manual to +<chet.ramey@case.edu>. + + +File: bashref.info, Node: Major Differences From The Bourne Shell, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top + +Appendix B Major Differences From The Bourne Shell +************************************************** + +Bash implements essentially the same grammar, parameter and variable +expansion, redirection, and quoting as the Bourne Shell. Bash uses the +POSIX standard as the specification of how these features are to be +implemented. There are some differences between the traditional Bourne +shell and Bash; this section quickly details the differences of +significance. A number of these differences are explained in greater +depth in previous sections. This section uses the version of `sh' +included in SVR4.2 (the last version of the historical Bourne shell) as +the baseline reference. + + * Bash is POSIX-conformant, even where the POSIX specification + differs from traditional `sh' behavior (*note Bash POSIX Mode::). + + * Bash has multi-character invocation options (*note Invoking + Bash::). + + * Bash has command-line editing (*note Command Line Editing::) and + the `bind' builtin. + + * Bash provides a programmable word completion mechanism (*note + Programmable Completion::), and builtin commands `complete', + `compgen', and `compopt', to manipulate it. + + * Bash has command history (*note Bash History Facilities::) and the + `history' and `fc' builtins to manipulate it. The Bash history + list maintains timestamp information and uses the value of the + `HISTTIMEFORMAT' variable to display it. + + * Bash implements `csh'-like history expansion (*note History + Interaction::). + + * Bash has one-dimensional array variables (*note Arrays::), and the + appropriate variable expansions and assignment syntax to use them. + Several of the Bash builtins take options to act on arrays. Bash + provides a number of built-in array variables. + + * The `$'...'' quoting syntax, which expands ANSI-C + backslash-escaped characters in the text between the single quotes, + is supported (*note ANSI-C Quoting::). + + * Bash supports the `$"..."' quoting syntax to do locale-specific + translation of the characters between the double quotes. The + `-D', `--dump-strings', and `--dump-po-strings' invocation options + list the translatable strings found in a script (*note Locale + Translation::). + + * Bash implements the `!' keyword to negate the return value of a + pipeline (*note Pipelines::). Very useful when an `if' statement + needs to act only if a test fails. The Bash `-o pipefail' option + to `set' will cause a pipeline to return a failure status if any + command fails. + + * Bash has the `time' reserved word and command timing (*note + Pipelines::). The display of the timing statistics may be + controlled with the `TIMEFORMAT' variable. + + * Bash implements the `for (( EXPR1 ; EXPR2 ; EXPR3 ))' arithmetic + for command, similar to the C language (*note Looping + Constructs::). + + * Bash includes the `select' compound command, which allows the + generation of simple menus (*note Conditional Constructs::). + + * Bash includes the `[[' compound command, which makes conditional + testing part of the shell grammar (*note Conditional + Constructs::), including optional regular expression matching. + + * Bash provides optional case-insensitive matching for the `case' and + `[[' constructs. + + * Bash includes brace expansion (*note Brace Expansion::) and tilde + expansion (*note Tilde Expansion::). + + * Bash implements command aliases and the `alias' and `unalias' + builtins (*note Aliases::). + + * Bash provides shell arithmetic, the `((' compound command (*note + Conditional Constructs::), and arithmetic expansion (*note Shell + Arithmetic::). + + * Variables present in the shell's initial environment are + automatically exported to child processes. The Bourne shell does + not normally do this unless the variables are explicitly marked + using the `export' command. + + * Bash supports the `+=' assignment operator, which appends to the + value of the variable named on the left hand side. + + * Bash includes the POSIX pattern removal `%', `#', `%%' and `##' + expansions to remove leading or trailing substrings from variable + values (*note Shell Parameter Expansion::). + + * The expansion `${#xx}', which returns the length of `${xx}', is + supported (*note Shell Parameter Expansion::). + + * The expansion `${var:'OFFSET`[:'LENGTH`]}', which expands to the + substring of `var''s value of length LENGTH, beginning at OFFSET, + is present (*note Shell Parameter Expansion::). + + * The expansion `${var/[/]'PATTERN`[/'REPLACEMENT`]}', which matches + PATTERN and replaces it with REPLACEMENT in the value of `var', is + available (*note Shell Parameter Expansion::). + + * The expansion `${!PREFIX}*' expansion, which expands to the names + of all shell variables whose names begin with PREFIX, is available + (*note Shell Parameter Expansion::). + + * Bash has INDIRECT variable expansion using `${!word}' (*note Shell + Parameter Expansion::). + + * Bash can expand positional parameters beyond `$9' using `${NUM}'. + + * The POSIX `$()' form of command substitution is implemented (*note + Command Substitution::), and preferred to the Bourne shell's ```' + (which is also implemented for backwards compatibility). + + * Bash has process substitution (*note Process Substitution::). + + * Bash automatically assigns variables that provide information + about the current user (`UID', `EUID', and `GROUPS'), the current + host (`HOSTTYPE', `OSTYPE', `MACHTYPE', and `HOSTNAME'), and the + instance of Bash that is running (`BASH', `BASH_VERSION', and + `BASH_VERSINFO'). *Note Bash Variables::, for details. + + * The `IFS' variable is used to split only the results of expansion, + not all words (*note Word Splitting::). This closes a + longstanding shell security hole. + + * Bash implements the full set of POSIX filename expansion operators, + including CHARACTER CLASSES, EQUIVALENCE CLASSES, and COLLATING + SYMBOLS (*note Filename Expansion::). + + * Bash implements extended pattern matching features when the + `extglob' shell option is enabled (*note Pattern Matching::). + + * It is possible to have a variable and a function with the same + name; `sh' does not separate the two name spaces. + + * Bash functions are permitted to have local variables using the + `local' builtin, and thus useful recursive functions may be written + (*note Bash Builtins::). + + * Variable assignments preceding commands affect only that command, + even builtins and functions (*note Environment::). In `sh', all + variable assignments preceding commands are global unless the + command is executed from the file system. + + * Bash performs filename expansion on filenames specified as operands + to input and output redirection operators (*note Redirections::). + + * Bash contains the `<>' redirection operator, allowing a file to be + opened for both reading and writing, and the `&>' redirection + operator, for directing standard output and standard error to the + same file (*note Redirections::). + + * Bash includes the `<<<' redirection operator, allowing a string to + be used as the standard input to a command. + + * Bash implements the `[n]<&WORD' and `[n]>&WORD' redirection + operators, which move one file descriptor to another. + + * Bash treats a number of filenames specially when they are used in + redirection operators (*note Redirections::). + + * Bash can open network connections to arbitrary machines and + services with the redirection operators (*note Redirections::). + + * The `noclobber' option is available to avoid overwriting existing + files with output redirection (*note The Set Builtin::). The `>|' + redirection operator may be used to override `noclobber'. + + * The Bash `cd' and `pwd' builtins (*note Bourne Shell Builtins::) + each take `-L' and `-P' options to switch between logical and + physical modes. + + * Bash allows a function to override a builtin with the same name, + and provides access to that builtin's functionality within the + function via the `builtin' and `command' builtins (*note Bash + Builtins::). + + * The `command' builtin allows selective disabling of functions when + command lookup is performed (*note Bash Builtins::). + + * Individual builtins may be enabled or disabled using the `enable' + builtin (*note Bash Builtins::). + + * The Bash `exec' builtin takes additional options that allow users + to control the contents of the environment passed to the executed + command, and what the zeroth argument to the command is to be + (*note Bourne Shell Builtins::). + + * Shell functions may be exported to children via the environment + using `export -f' (*note Shell Functions::). + + * The Bash `export', `readonly', and `declare' builtins can take a + `-f' option to act on shell functions, a `-p' option to display + variables with various attributes set in a format that can be used + as shell input, a `-n' option to remove various variable + attributes, and `name=value' arguments to set variable attributes + and values simultaneously. + + * The Bash `hash' builtin allows a name to be associated with an + arbitrary filename, even when that filename cannot be found by + searching the `$PATH', using `hash -p' (*note Bourne Shell + Builtins::). + + * Bash includes a `help' builtin for quick reference to shell + facilities (*note Bash Builtins::). + + * The `printf' builtin is available to display formatted output + (*note Bash Builtins::). + + * The Bash `read' builtin (*note Bash Builtins::) will read a line + ending in `\' with the `-r' option, and will use the `REPLY' + variable as a default if no non-option arguments are supplied. + The Bash `read' builtin also accepts a prompt string with the `-p' + option and will use Readline to obtain the line when given the + `-e' option. The `read' builtin also has additional options to + control input: the `-s' option will turn off echoing of input + characters as they are read, the `-t' option will allow `read' to + time out if input does not arrive within a specified number of + seconds, the `-n' option will allow reading only a specified + number of characters rather than a full line, and the `-d' option + will read until a particular character rather than newline. + + * The `return' builtin may be used to abort execution of scripts + executed with the `.' or `source' builtins (*note Bourne Shell + Builtins::). + + * Bash includes the `shopt' builtin, for finer control of shell + optional capabilities (*note The Shopt Builtin::), and allows + these options to be set and unset at shell invocation (*note + Invoking Bash::). + + * Bash has much more optional behavior controllable with the `set' + builtin (*note The Set Builtin::). + + * The `-x' (`xtrace') option displays commands other than simple + commands when performing an execution trace (*note The Set + Builtin::). + + * The `test' builtin (*note Bourne Shell Builtins::) is slightly + different, as it implements the POSIX algorithm, which specifies + the behavior based on the number of arguments. + + * Bash includes the `caller' builtin, which displays the context of + any active subroutine call (a shell function or a script executed + with the `.' or `source' builtins). This supports the bash + debugger. + + * The `trap' builtin (*note Bourne Shell Builtins::) allows a + `DEBUG' pseudo-signal specification, similar to `EXIT'. Commands + specified with a `DEBUG' trap are executed before every simple + command, `for' command, `case' command, `select' command, every + arithmetic `for' command, and before the first command executes in + a shell function. The `DEBUG' trap is not inherited by shell + functions unless the function has been given the `trace' attribute + or the `functrace' option has been enabled using the `shopt' + builtin. The `extdebug' shell option has additional effects on the + `DEBUG' trap. + + The `trap' builtin (*note Bourne Shell Builtins::) allows an `ERR' + pseudo-signal specification, similar to `EXIT' and `DEBUG'. + Commands specified with an `ERR' trap are executed after a simple + command fails, with a few exceptions. The `ERR' trap is not + inherited by shell functions unless the `-o errtrace' option to + the `set' builtin is enabled. + + The `trap' builtin (*note Bourne Shell Builtins::) allows a + `RETURN' pseudo-signal specification, similar to `EXIT' and + `DEBUG'. Commands specified with an `RETURN' trap are executed + before execution resumes after a shell function or a shell script + executed with `.' or `source' returns. The `RETURN' trap is not + inherited by shell functions unless the function has been given + the `trace' attribute or the `functrace' option has been enabled + using the `shopt' builtin. + + * The Bash `type' builtin is more extensive and gives more + information about the names it finds (*note Bash Builtins::). + + * The Bash `umask' builtin permits a `-p' option to cause the output + to be displayed in the form of a `umask' command that may be + reused as input (*note Bourne Shell Builtins::). + + * Bash implements a `csh'-like directory stack, and provides the + `pushd', `popd', and `dirs' builtins to manipulate it (*note The + Directory Stack::). Bash also makes the directory stack visible + as the value of the `DIRSTACK' shell variable. + + * Bash interprets special backslash-escaped characters in the prompt + strings when interactive (*note Printing a Prompt::). + + * The Bash restricted mode is more useful (*note The Restricted + Shell::); the SVR4.2 shell restricted mode is too limited. + + * The `disown' builtin can remove a job from the internal shell job + table (*note Job Control Builtins::) or suppress the sending of + `SIGHUP' to a job when the shell exits as the result of a `SIGHUP'. + + * Bash includes a number of features to support a separate debugger + for shell scripts. + + * The SVR4.2 shell has two privilege-related builtins (`mldmode' and + `priv') not present in Bash. + + * Bash does not have the `stop' or `newgrp' builtins. + + * Bash does not use the `SHACCT' variable or perform shell + accounting. + + * The SVR4.2 `sh' uses a `TIMEOUT' variable like Bash uses `TMOUT'. + + +More features unique to Bash may be found in *note Bash Features::. + +B.1 Implementation Differences From The SVR4.2 Shell +==================================================== + +Since Bash is a completely new implementation, it does not suffer from +many of the limitations of the SVR4.2 shell. For instance: + + * Bash does not fork a subshell when redirecting into or out of a + shell control structure such as an `if' or `while' statement. + + * Bash does not allow unbalanced quotes. The SVR4.2 shell will + silently insert a needed closing quote at `EOF' under certain + circumstances. This can be the cause of some hard-to-find errors. + + * The SVR4.2 shell uses a baroque memory management scheme based on + trapping `SIGSEGV'. If the shell is started from a process with + `SIGSEGV' blocked (e.g., by using the `system()' C library + function call), it misbehaves badly. + + * In a questionable attempt at security, the SVR4.2 shell, when + invoked without the `-p' option, will alter its real and effective + UID and GID if they are less than some magic threshold value, + commonly 100. This can lead to unexpected results. + + * The SVR4.2 shell does not allow users to trap `SIGSEGV', + `SIGALRM', or `SIGCHLD'. + + * The SVR4.2 shell does not allow the `IFS', `MAILCHECK', `PATH', + `PS1', or `PS2' variables to be unset. + + * The SVR4.2 shell treats `^' as the undocumented equivalent of `|'. + + * Bash allows multiple option arguments when it is invoked (`-x -v'); + the SVR4.2 shell allows only one option argument (`-xv'). In + fact, some versions of the shell dump core if the second argument + begins with a `-'. + + * The SVR4.2 shell exits a script if any builtin fails; Bash exits a + script only if one of the POSIX special builtins fails, and only + for certain failures, as enumerated in the POSIX standard. + + * The SVR4.2 shell behaves differently when invoked as `jsh' (it + turns on job control). + + +File: bashref.info, Node: GNU Free Documentation License, Next: Indexes, Prev: Major Differences From The Bourne Shell, Up: Top + +Appendix C GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, receipt of a copy of some or all of + the same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. If the Document specifies that a proxy + can decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: bashref.info, Node: Indexes, Prev: GNU Free Documentation License, Up: Top + +Appendix D Indexes +****************** + +* Menu: + +* Builtin Index:: Index of Bash builtin commands. +* Reserved Word Index:: Index of Bash reserved words. +* Variable Index:: Quick reference helps you find the + variable you want. +* Function Index:: Index of bindable Readline functions. +* Concept Index:: General index for concepts described in + this manual. + + +File: bashref.info, Node: Builtin Index, Next: Reserved Word Index, Up: Indexes + +D.1 Index of Shell Builtin Commands +=================================== + + +* Menu: + +* .: Bourne Shell Builtins. + (line 16) +* :: Bourne Shell Builtins. + (line 11) +* [: Bourne Shell Builtins. + (line 213) +* alias: Bash Builtins. (line 11) +* bg: Job Control Builtins. + (line 7) +* bind: Bash Builtins. (line 21) +* break: Bourne Shell Builtins. + (line 29) +* builtin: Bash Builtins. (line 98) +* caller: Bash Builtins. (line 106) +* cd: Bourne Shell Builtins. + (line 36) +* command: Bash Builtins. (line 123) +* compgen: Programmable Completion Builtins. + (line 10) +* complete: Programmable Completion Builtins. + (line 28) +* compopt: Programmable Completion Builtins. + (line 217) +* continue: Bourne Shell Builtins. + (line 55) +* declare: Bash Builtins. (line 142) +* dirs: Directory Stack Builtins. + (line 7) +* disown: Job Control Builtins. + (line 83) +* echo: Bash Builtins. (line 221) +* enable: Bash Builtins. (line 273) +* eval: Bourne Shell Builtins. + (line 63) +* exec: Bourne Shell Builtins. + (line 70) +* exit: Bourne Shell Builtins. + (line 82) +* export: Bourne Shell Builtins. + (line 88) +* fc: Bash History Builtins. + (line 10) +* fg: Job Control Builtins. + (line 16) +* getopts: Bourne Shell Builtins. + (line 103) +* hash: Bourne Shell Builtins. + (line 145) +* help: Bash Builtins. (line 301) +* history: Bash History Builtins. + (line 39) +* jobs: Job Control Builtins. + (line 25) +* kill: Job Control Builtins. + (line 57) +* let: Bash Builtins. (line 321) +* local: Bash Builtins. (line 328) +* logout: Bash Builtins. (line 338) +* mapfile: Bash Builtins. (line 342) +* popd: Directory Stack Builtins. + (line 37) +* printf: Bash Builtins. (line 388) +* pushd: Directory Stack Builtins. + (line 58) +* pwd: Bourne Shell Builtins. + (line 163) +* read: Bash Builtins. (line 413) +* readarray: Bash Builtins. (line 493) +* readonly: Bourne Shell Builtins. + (line 172) +* return: Bourne Shell Builtins. + (line 188) +* set: The Set Builtin. (line 11) +* shift: Bourne Shell Builtins. + (line 201) +* shopt: The Shopt Builtin. (line 9) +* source: Bash Builtins. (line 501) +* suspend: Job Control Builtins. + (line 94) +* test: Bourne Shell Builtins. + (line 213) +* times: Bourne Shell Builtins. + (line 281) +* trap: Bourne Shell Builtins. + (line 286) +* type: Bash Builtins. (line 505) +* typeset: Bash Builtins. (line 536) +* ulimit: Bash Builtins. (line 542) +* umask: Bourne Shell Builtins. + (line 332) +* unalias: Bash Builtins. (line 630) +* unset: Bourne Shell Builtins. + (line 349) +* wait: Job Control Builtins. + (line 73) + + +File: bashref.info, Node: Reserved Word Index, Next: Variable Index, Prev: Builtin Index, Up: Indexes + +D.2 Index of Shell Reserved Words +================================= + + +* Menu: + +* !: Pipelines. (line 9) +* [[: Conditional Constructs. + (line 117) +* ]]: Conditional Constructs. + (line 117) +* case: Conditional Constructs. + (line 28) +* do: Looping Constructs. (line 12) +* done: Looping Constructs. (line 12) +* elif: Conditional Constructs. + (line 7) +* else: Conditional Constructs. + (line 7) +* esac: Conditional Constructs. + (line 28) +* fi: Conditional Constructs. + (line 7) +* for: Looping Constructs. (line 29) +* function: Shell Functions. (line 13) +* if: Conditional Constructs. + (line 7) +* in: Conditional Constructs. + (line 28) +* select: Conditional Constructs. + (line 76) +* then: Conditional Constructs. + (line 7) +* time: Pipelines. (line 9) +* until: Looping Constructs. (line 12) +* while: Looping Constructs. (line 20) +* {: Command Grouping. (line 21) +* }: Command Grouping. (line 21) + + +File: bashref.info, Node: Variable Index, Next: Function Index, Prev: Reserved Word Index, Up: Indexes + +D.3 Parameter and Variable Index +================================ + + +* Menu: + +* !: Special Parameters. (line 46) +* #: Special Parameters. (line 30) +* $: Special Parameters. (line 42) +* *: Special Parameters. (line 9) +* -: Special Parameters. (line 37) +* 0: Special Parameters. (line 50) +* ?: Special Parameters. (line 33) +* @: Special Parameters. (line 19) +* _: Special Parameters. (line 59) +* auto_resume: Job Control Variables. + (line 6) +* BASH: Bash Variables. (line 13) +* BASH_ALIASES: Bash Variables. (line 30) +* BASH_ARGC: Bash Variables. (line 37) +* BASH_ARGV: Bash Variables. (line 47) +* BASH_CMDS: Bash Variables. (line 57) +* BASH_COMMAND: Bash Variables. (line 64) +* BASH_ENV: Bash Variables. (line 69) +* BASH_EXECUTION_STRING: Bash Variables. (line 75) +* BASH_LINENO: Bash Variables. (line 78) +* BASH_REMATCH: Bash Variables. (line 87) +* BASH_SOURCE: Bash Variables. (line 95) +* BASH_SUBSHELL: Bash Variables. (line 99) +* BASH_VERSINFO: Bash Variables. (line 103) +* BASH_VERSION: Bash Variables. (line 127) +* BASH_XTRACEFD: Bash Variables. (line 130) +* BASHOPTS: Bash Variables. (line 16) +* BASHPID: Bash Variables. (line 25) +* bell-style: Readline Init File Syntax. + (line 38) +* bind-tty-special-chars: Readline Init File Syntax. + (line 45) +* CDPATH: Bourne Shell Variables. + (line 9) +* COLUMNS: Bash Variables. (line 141) +* comment-begin: Readline Init File Syntax. + (line 50) +* COMP_CWORD: Bash Variables. (line 146) +* COMP_KEY: Bash Variables. (line 175) +* COMP_LINE: Bash Variables. (line 152) +* COMP_POINT: Bash Variables. (line 157) +* COMP_TYPE: Bash Variables. (line 165) +* COMP_WORDBREAKS: Bash Variables. (line 179) +* COMP_WORDS: Bash Variables. (line 185) +* completion-prefix-display-length: Readline Init File Syntax. + (line 60) +* completion-query-items: Readline Init File Syntax. + (line 67) +* COMPREPLY: Bash Variables. (line 193) +* convert-meta: Readline Init File Syntax. + (line 77) +* DIRSTACK: Bash Variables. (line 198) +* disable-completion: Readline Init File Syntax. + (line 83) +* editing-mode: Readline Init File Syntax. + (line 88) +* EMACS: Bash Variables. (line 208) +* enable-keypad: Readline Init File Syntax. + (line 99) +* EUID: Bash Variables. (line 213) +* expand-tilde: Readline Init File Syntax. + (line 110) +* FCEDIT: Bash Variables. (line 217) +* FIGNORE: Bash Variables. (line 221) +* FUNCNAME: Bash Variables. (line 227) +* GLOBIGNORE: Bash Variables. (line 236) +* GROUPS: Bash Variables. (line 242) +* histchars: Bash Variables. (line 248) +* HISTCMD: Bash Variables. (line 263) +* HISTCONTROL: Bash Variables. (line 268) +* HISTFILE: Bash Variables. (line 284) +* HISTFILESIZE: Bash Variables. (line 288) +* HISTIGNORE: Bash Variables. (line 296) +* history-preserve-point: Readline Init File Syntax. + (line 114) +* history-size: Readline Init File Syntax. + (line 120) +* HISTSIZE: Bash Variables. (line 315) +* HISTTIMEFORMAT: Bash Variables. (line 319) +* HOME: Bourne Shell Variables. + (line 13) +* horizontal-scroll-mode: Readline Init File Syntax. + (line 125) +* HOSTFILE: Bash Variables. (line 328) +* HOSTNAME: Bash Variables. (line 339) +* HOSTTYPE: Bash Variables. (line 342) +* IFS: Bourne Shell Variables. + (line 18) +* IGNOREEOF: Bash Variables. (line 345) +* input-meta: Readline Init File Syntax. + (line 132) +* INPUTRC: Bash Variables. (line 355) +* isearch-terminators: Readline Init File Syntax. + (line 139) +* keymap: Readline Init File Syntax. + (line 146) +* LANG: Bash Variables. (line 359) +* LC_ALL: Bash Variables. (line 363) +* LC_COLLATE: Bash Variables. (line 367) +* LC_CTYPE: Bash Variables. (line 374) +* LC_MESSAGES <1>: Locale Translation. (line 11) +* LC_MESSAGES: Bash Variables. (line 379) +* LC_NUMERIC: Bash Variables. (line 383) +* LINENO: Bash Variables. (line 387) +* LINES: Bash Variables. (line 391) +* MACHTYPE: Bash Variables. (line 396) +* MAIL: Bourne Shell Variables. + (line 22) +* MAILCHECK: Bash Variables. (line 400) +* MAILPATH: Bourne Shell Variables. + (line 27) +* mark-modified-lines: Readline Init File Syntax. + (line 159) +* mark-symlinked-directories: Readline Init File Syntax. + (line 164) +* match-hidden-files: Readline Init File Syntax. + (line 169) +* meta-flag: Readline Init File Syntax. + (line 132) +* OLDPWD: Bash Variables. (line 408) +* OPTARG: Bourne Shell Variables. + (line 34) +* OPTERR: Bash Variables. (line 411) +* OPTIND: Bourne Shell Variables. + (line 38) +* OSTYPE: Bash Variables. (line 415) +* output-meta: Readline Init File Syntax. + (line 176) +* page-completions: Readline Init File Syntax. + (line 181) +* PATH: Bourne Shell Variables. + (line 42) +* PIPESTATUS: Bash Variables. (line 418) +* POSIXLY_CORRECT: Bash Variables. (line 423) +* PPID: Bash Variables. (line 432) +* PROMPT_COMMAND: Bash Variables. (line 436) +* PROMPT_DIRTRIM: Bash Variables. (line 440) +* PS1: Bourne Shell Variables. + (line 48) +* PS2: Bourne Shell Variables. + (line 53) +* PS3: Bash Variables. (line 446) +* PS4: Bash Variables. (line 451) +* PWD: Bash Variables. (line 457) +* RANDOM: Bash Variables. (line 460) +* REPLY: Bash Variables. (line 465) +* revert-all-at-newline: Readline Init File Syntax. + (line 191) +* SECONDS: Bash Variables. (line 468) +* SHELL: Bash Variables. (line 474) +* SHELLOPTS: Bash Variables. (line 479) +* SHLVL: Bash Variables. (line 488) +* show-all-if-ambiguous: Readline Init File Syntax. + (line 197) +* show-all-if-unmodified: Readline Init File Syntax. + (line 203) +* skip-completed-text: Readline Init File Syntax. + (line 212) +* TEXTDOMAIN: Locale Translation. (line 11) +* TEXTDOMAINDIR: Locale Translation. (line 11) +* TIMEFORMAT: Bash Variables. (line 493) +* TMOUT: Bash Variables. (line 531) +* TMPDIR: Bash Variables. (line 543) +* UID: Bash Variables. (line 547) +* visible-stats: Readline Init File Syntax. + (line 225) + + +File: bashref.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Indexes + +D.4 Function Index +================== + + +* Menu: + +* abort (C-g): Miscellaneous Commands. + (line 10) +* accept-line (Newline or Return): Commands For History. (line 6) +* backward-char (C-b): Commands For Moving. (line 15) +* backward-delete-char (Rubout): Commands For Text. (line 11) +* backward-kill-line (C-x Rubout): Commands For Killing. (line 9) +* backward-kill-word (M-<DEL>): Commands For Killing. (line 24) +* backward-word (M-b): Commands For Moving. (line 22) +* beginning-of-history (M-<): Commands For History. (line 20) +* beginning-of-line (C-a): Commands For Moving. (line 6) +* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) +* capitalize-word (M-c): Commands For Text. (line 46) +* character-search (C-]): Miscellaneous Commands. + (line 41) +* character-search-backward (M-C-]): Miscellaneous Commands. + (line 46) +* clear-screen (C-l): Commands For Moving. (line 34) +* complete (<TAB>): Commands For Completion. + (line 6) +* copy-backward-word (): Commands For Killing. (line 58) +* copy-forward-word (): Commands For Killing. (line 63) +* copy-region-as-kill (): Commands For Killing. (line 54) +* delete-char (C-d): Commands For Text. (line 6) +* delete-char-or-list (): Commands For Completion. + (line 39) +* delete-horizontal-space (): Commands For Killing. (line 46) +* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) +* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. + (line 14) +* downcase-word (M-l): Commands For Text. (line 42) +* dump-functions (): Miscellaneous Commands. + (line 73) +* dump-macros (): Miscellaneous Commands. + (line 85) +* dump-variables (): Miscellaneous Commands. + (line 79) +* end-kbd-macro (C-x )): Keyboard Macros. (line 9) +* end-of-history (M->): Commands For History. (line 23) +* end-of-line (C-e): Commands For Moving. (line 9) +* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. + (line 36) +* forward-backward-delete-char (): Commands For Text. (line 15) +* forward-char (C-f): Commands For Moving. (line 12) +* forward-search-history (C-s): Commands For History. (line 31) +* forward-word (M-f): Commands For Moving. (line 18) +* history-search-backward (): Commands For History. (line 51) +* history-search-forward (): Commands For History. (line 46) +* insert-comment (M-#): Miscellaneous Commands. + (line 60) +* insert-completions (M-*): Commands For Completion. + (line 18) +* kill-line (C-k): Commands For Killing. (line 6) +* kill-region (): Commands For Killing. (line 50) +* kill-whole-line (): Commands For Killing. (line 15) +* kill-word (M-d): Commands For Killing. (line 19) +* menu-complete (): Commands For Completion. + (line 22) +* menu-complete-backward (): Commands For Completion. + (line 34) +* next-history (C-n): Commands For History. (line 17) +* non-incremental-forward-search-history (M-n): Commands For History. + (line 41) +* non-incremental-reverse-search-history (M-p): Commands For History. + (line 36) +* overwrite-mode (): Commands For Text. (line 50) +* possible-completions (M-?): Commands For Completion. + (line 15) +* prefix-meta (<ESC>): Miscellaneous Commands. + (line 18) +* previous-history (C-p): Commands For History. (line 13) +* quoted-insert (C-q or C-v): Commands For Text. (line 20) +* re-read-init-file (C-x C-r): Miscellaneous Commands. + (line 6) +* redraw-current-line (): Commands For Moving. (line 38) +* reverse-search-history (C-r): Commands For History. (line 27) +* revert-line (M-r): Miscellaneous Commands. + (line 25) +* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 24) +* set-mark (C-@): Miscellaneous Commands. + (line 32) +* skip-csi-sequence (): Miscellaneous Commands. + (line 51) +* start-kbd-macro (C-x (): Keyboard Macros. (line 6) +* transpose-chars (C-t): Commands For Text. (line 27) +* transpose-words (M-t): Commands For Text. (line 33) +* undo (C-_ or C-x C-u): Miscellaneous Commands. + (line 22) +* universal-argument (): Numeric Arguments. (line 10) +* unix-filename-rubout (): Commands For Killing. (line 41) +* unix-line-discard (C-u): Commands For Killing. (line 12) +* unix-word-rubout (C-w): Commands For Killing. (line 37) +* upcase-word (M-u): Commands For Text. (line 38) +* yank (C-y): Commands For Killing. (line 68) +* yank-last-arg (M-. or M-_): Commands For History. (line 65) +* yank-nth-arg (M-C-y): Commands For History. (line 56) +* yank-pop (M-y): Commands For Killing. (line 71) + + +File: bashref.info, Node: Concept Index, Prev: Function Index, Up: Indexes + +D.5 Concept Index +================= + + +* Menu: + +* alias expansion: Aliases. (line 6) +* arithmetic evaluation: Shell Arithmetic. (line 6) +* arithmetic expansion: Arithmetic Expansion. + (line 6) +* arithmetic, shell: Shell Arithmetic. (line 6) +* arrays: Arrays. (line 6) +* background: Job Control Basics. (line 6) +* Bash configuration: Basic Installation. (line 6) +* Bash installation: Basic Installation. (line 6) +* Bourne shell: Basic Shell Features. + (line 6) +* brace expansion: Brace Expansion. (line 6) +* builtin: Definitions. (line 17) +* command editing: Readline Bare Essentials. + (line 6) +* command execution: Command Search and Execution. + (line 6) +* command expansion: Simple Command Expansion. + (line 6) +* command history: Bash History Facilities. + (line 6) +* command search: Command Search and Execution. + (line 6) +* command substitution: Command Substitution. + (line 6) +* command timing: Pipelines. (line 9) +* commands, compound: Compound Commands. (line 6) +* commands, conditional: Conditional Constructs. + (line 6) +* commands, grouping: Command Grouping. (line 6) +* commands, lists: Lists. (line 6) +* commands, looping: Looping Constructs. (line 6) +* commands, pipelines: Pipelines. (line 6) +* commands, shell: Shell Commands. (line 6) +* commands, simple: Simple Commands. (line 6) +* comments, shell: Comments. (line 6) +* completion builtins: Programmable Completion Builtins. + (line 6) +* configuration: Basic Installation. (line 6) +* control operator: Definitions. (line 21) +* coprocess: Coprocesses. (line 6) +* directory stack: The Directory Stack. (line 6) +* editing command lines: Readline Bare Essentials. + (line 6) +* environment: Environment. (line 6) +* evaluation, arithmetic: Shell Arithmetic. (line 6) +* event designators: Event Designators. (line 6) +* execution environment: Command Execution Environment. + (line 6) +* exit status <1>: Exit Status. (line 6) +* exit status: Definitions. (line 26) +* expansion: Shell Expansions. (line 6) +* expansion, arithmetic: Arithmetic Expansion. + (line 6) +* expansion, brace: Brace Expansion. (line 6) +* expansion, filename: Filename Expansion. (line 9) +* expansion, parameter: Shell Parameter Expansion. + (line 6) +* expansion, pathname: Filename Expansion. (line 9) +* expansion, tilde: Tilde Expansion. (line 6) +* expressions, arithmetic: Shell Arithmetic. (line 6) +* expressions, conditional: Bash Conditional Expressions. + (line 6) +* field: Definitions. (line 30) +* filename: Definitions. (line 35) +* filename expansion: Filename Expansion. (line 9) +* foreground: Job Control Basics. (line 6) +* functions, shell: Shell Functions. (line 6) +* history builtins: Bash History Builtins. + (line 6) +* history events: Event Designators. (line 7) +* history expansion: History Interaction. (line 6) +* history list: Bash History Facilities. + (line 6) +* History, how to use: Programmable Completion Builtins. + (line 237) +* identifier: Definitions. (line 51) +* initialization file, readline: Readline Init File. (line 6) +* installation: Basic Installation. (line 6) +* interaction, readline: Readline Interaction. + (line 6) +* interactive shell <1>: Interactive Shells. (line 6) +* interactive shell: Invoking Bash. (line 127) +* internationalization: Locale Translation. (line 6) +* job: Definitions. (line 38) +* job control <1>: Job Control Basics. (line 6) +* job control: Definitions. (line 42) +* kill ring: Readline Killing Commands. + (line 19) +* killing text: Readline Killing Commands. + (line 6) +* localization: Locale Translation. (line 6) +* login shell: Invoking Bash. (line 124) +* matching, pattern: Pattern Matching. (line 6) +* metacharacter: Definitions. (line 46) +* name: Definitions. (line 51) +* native languages: Locale Translation. (line 6) +* notation, readline: Readline Bare Essentials. + (line 6) +* operator, shell: Definitions. (line 57) +* parameter expansion: Shell Parameter Expansion. + (line 6) +* parameters: Shell Parameters. (line 6) +* parameters, positional: Positional Parameters. + (line 6) +* parameters, special: Special Parameters. (line 6) +* pathname expansion: Filename Expansion. (line 9) +* pattern matching: Pattern Matching. (line 6) +* pipeline: Pipelines. (line 6) +* POSIX: Definitions. (line 9) +* POSIX Mode: Bash POSIX Mode. (line 6) +* process group: Definitions. (line 62) +* process group ID: Definitions. (line 66) +* process substitution: Process Substitution. + (line 6) +* programmable completion: Programmable Completion. + (line 6) +* prompting: Printing a Prompt. (line 6) +* quoting: Quoting. (line 6) +* quoting, ANSI: ANSI-C Quoting. (line 6) +* Readline, how to use: Job Control Variables. + (line 24) +* redirection: Redirections. (line 6) +* reserved word: Definitions. (line 70) +* restricted shell: The Restricted Shell. + (line 6) +* return status: Definitions. (line 75) +* shell arithmetic: Shell Arithmetic. (line 6) +* shell function: Shell Functions. (line 6) +* shell script: Shell Scripts. (line 6) +* shell variable: Shell Parameters. (line 6) +* shell, interactive: Interactive Shells. (line 6) +* signal: Definitions. (line 78) +* signal handling: Signals. (line 6) +* special builtin <1>: Special Builtins. (line 6) +* special builtin: Definitions. (line 82) +* startup files: Bash Startup Files. (line 6) +* suspending jobs: Job Control Basics. (line 6) +* tilde expansion: Tilde Expansion. (line 6) +* token: Definitions. (line 86) +* translation, native languages: Locale Translation. (line 6) +* variable, shell: Shell Parameters. (line 6) +* variables, readline: Readline Init File Syntax. + (line 37) +* word: Definitions. (line 90) +* word splitting: Word Splitting. (line 6) +* yanking text: Readline Killing Commands. + (line 6) + + + +Tag Table: +Node: Top1346 +Node: Introduction3185 +Node: What is Bash?3413 +Node: What is a shell?4526 +Node: Definitions7066 +Node: Basic Shell Features9984 +Node: Shell Syntax11203 +Node: Shell Operation12233 +Node: Quoting13527 +Node: Escape Character14830 +Node: Single Quotes15315 +Node: Double Quotes15663 +Node: ANSI-C Quoting16788 +Node: Locale Translation17773 +Node: Comments18669 +Node: Shell Commands19287 +Node: Simple Commands20111 +Node: Pipelines20742 +Node: Lists22998 +Node: Compound Commands24727 +Node: Looping Constructs25531 +Node: Conditional Constructs27986 +Node: Command Grouping36099 +Node: Coprocesses37578 +Node: Shell Functions39222 +Node: Shell Parameters43776 +Node: Positional Parameters46192 +Node: Special Parameters47092 +Node: Shell Expansions50056 +Node: Brace Expansion51981 +Node: Tilde Expansion54736 +Node: Shell Parameter Expansion57087 +Node: Command Substitution65988 +Node: Arithmetic Expansion67321 +Node: Process Substitution68171 +Node: Word Splitting69221 +Node: Filename Expansion70844 +Node: Pattern Matching72983 +Node: Quote Removal76622 +Node: Redirections76917 +Node: Executing Commands85442 +Node: Simple Command Expansion86112 +Node: Command Search and Execution88042 +Node: Command Execution Environment90379 +Node: Environment93365 +Node: Exit Status95025 +Node: Signals96646 +Node: Shell Scripts98614 +Node: Shell Builtin Commands101132 +Node: Bourne Shell Builtins103160 +Node: Bash Builtins120536 +Node: Modifying Shell Behavior145364 +Node: The Set Builtin145709 +Node: The Shopt Builtin155233 +Node: Special Builtins166095 +Node: Shell Variables167074 +Node: Bourne Shell Variables167514 +Node: Bash Variables169495 +Node: Bash Features192981 +Node: Invoking Bash193864 +Node: Bash Startup Files199673 +Node: Interactive Shells204685 +Node: What is an Interactive Shell?205095 +Node: Is this Shell Interactive?205744 +Node: Interactive Shell Behavior206559 +Node: Bash Conditional Expressions209839 +Node: Shell Arithmetic213488 +Node: Aliases216234 +Node: Arrays218806 +Node: The Directory Stack222764 +Node: Directory Stack Builtins223478 +Node: Printing a Prompt226370 +Node: The Restricted Shell229122 +Node: Bash POSIX Mode230954 +Node: Job Control239011 +Node: Job Control Basics239471 +Node: Job Control Builtins244188 +Node: Job Control Variables248552 +Node: Command Line Editing249710 +Node: Introduction and Notation251277 +Node: Readline Interaction252899 +Node: Readline Bare Essentials254090 +Node: Readline Movement Commands255879 +Node: Readline Killing Commands256844 +Node: Readline Arguments258764 +Node: Searching259808 +Node: Readline Init File261994 +Node: Readline Init File Syntax263141 +Node: Conditional Init Constructs277628 +Node: Sample Init File280161 +Node: Bindable Readline Commands283278 +Node: Commands For Moving284485 +Node: Commands For History285629 +Node: Commands For Text288784 +Node: Commands For Killing291457 +Node: Numeric Arguments293908 +Node: Commands For Completion295047 +Node: Keyboard Macros299007 +Node: Miscellaneous Commands299578 +Node: Readline vi Mode305384 +Node: Programmable Completion306298 +Node: Programmable Completion Builtins313504 +Node: Using History Interactively322640 +Node: Bash History Facilities323324 +Node: Bash History Builtins326238 +Node: History Interaction330095 +Node: Event Designators332800 +Node: Word Designators333815 +Node: Modifiers335454 +Node: Installing Bash336858 +Node: Basic Installation337995 +Node: Compilers and Options340687 +Node: Compiling For Multiple Architectures341428 +Node: Installation Names343092 +Node: Specifying the System Type343910 +Node: Sharing Defaults344626 +Node: Operation Controls345299 +Node: Optional Features346257 +Node: Reporting Bugs355816 +Node: Major Differences From The Bourne Shell357017 +Node: GNU Free Documentation License373704 +Node: Indexes398900 +Node: Builtin Index399354 +Node: Reserved Word Index406181 +Node: Variable Index408629 +Node: Function Index420722 +Node: Concept Index427731 + +End Tag Table |