| 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 |
| =================================== |
| |
| [index] |
| * 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 |
| ================================= |
| |
| [index] |
| * 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 |
| ================================ |
| |
| [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 |
| ================== |
| |
| [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 |
| ================= |
| |
| [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 |