| \input texinfo.tex @c -*- texinfo -*- |
| @c %**start of header |
| @setfilename bashref.info |
| @settitle Bash Reference Manual |
| @c %**end of header |
| |
| @setchapternewpage odd |
| |
| @include version.texi |
| |
| @copying |
| This text is a brief description of the features that are present in |
| the Bash shell (version @value{VERSION}, @value{UPDATED}). |
| |
| This is Edition @value{EDITION}, last updated @value{UPDATED}, |
| of @cite{The GNU Bash Reference Manual}, |
| for @code{Bash}, Version @value{VERSION}. |
| |
| Copyright @copyright{} 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. |
| |
| @quotation |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.2 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.'' |
| |
| @end quotation |
| @end copying |
| |
| @defcodeindex bt |
| @defcodeindex rw |
| @set BashFeatures |
| |
| @dircategory Basics |
| @direntry |
| * Bash: (bash). The GNU Bourne-Again SHell. |
| @end direntry |
| |
| @finalout |
| |
| @titlepage |
| @title Bash Reference Manual |
| @subtitle Reference Documentation for Bash |
| @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}. |
| @subtitle @value{UPDATED-MONTH} |
| @author Chet Ramey, Case Western Reserve University |
| @author Brian Fox, Free Software Foundation |
| |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| |
| @sp 1 |
| Published by the Free Software Foundation @* |
| 59 Temple Place, Suite 330, @* |
| Boston, MA 02111-1307 @* |
| USA @* |
| |
| @end titlepage |
| |
| @contents |
| |
| @ifnottex |
| @node Top, Introduction, (dir), (dir) |
| @top Bash Features |
| |
| This text is a brief description of the features that are present in |
| the Bash shell (version @value{VERSION}, @value{UPDATED}). |
| |
| This is Edition @value{EDITION}, last updated @value{UPDATED}, |
| of @cite{The GNU Bash Reference Manual}, |
| for @code{Bash}, Version @value{VERSION}. |
| |
| 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 (@file{sh}), the Korn Shell |
| (@file{ksh}), and the C-shell (@file{csh} and its successor, |
| @file{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. |
| @end menu |
| @end ifnottex |
| |
| @node Introduction |
| @chapter Introduction |
| @menu |
| * What is Bash?:: A short description of Bash. |
| * What is a shell?:: A brief introduction to shells. |
| @end menu |
| |
| @node What is Bash? |
| @section What is Bash? |
| |
| Bash is the shell, or command language interpreter, |
| for the @sc{gnu} operating system. |
| The name is an acronym for the @samp{Bourne-Again SHell}, |
| a pun on Stephen Bourne, the author of the direct ancestor of |
| the current Unix shell @code{sh}, |
| which appeared in the Seventh Edition Bell Labs Research version |
| of Unix. |
| |
| Bash is largely compatible with @code{sh} and incorporates useful |
| features from the Korn shell @code{ksh} and the C shell @code{csh}. |
| It is intended to be a conformant implementation of the @sc{ieee} |
| @sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix} |
| specification (@sc{ieee} Standard 1003.1). |
| It offers functional improvements over @code{sh} for both interactive and |
| programming use. |
| |
| While the @sc{gnu} operating system provides other shells, including |
| a version of @code{csh}, Bash is the default shell. |
| Like other @sc{gnu} software, Bash is quite portable. It currently runs |
| on nearly every version of Unix and a few other operating systems @minus{} |
| independently-supported ports exist for @sc{ms-dos}, @sc{os/2}, |
| and Windows platforms. |
| |
| @node What is a shell? |
| @section 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 @sc{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 @file{/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 @sc{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 @dfn{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 (@dfn{builtins}) implementing functionality impossible |
| or inconvenient to obtain via separate utilities. |
| For example, @code{cd}, @code{break}, @code{continue}, and |
| @code{exec}) cannot be implemented outside of the shell because |
| they directly manipulate the shell itself. |
| The @code{history}, @code{getopts}, @code{kill}, or @code{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. |
| |
| @node Definitions |
| @chapter Definitions |
| These definitions are used throughout the remainder of this manual. |
| |
| @table @code |
| |
| @item POSIX |
| @cindex POSIX |
| A family of open system standards based on Unix. Bash |
| is primarily concerned with the Shell and Utilities portion of the |
| @sc{posix} 1003.1 standard. |
| |
| @item blank |
| A space or tab character. |
| |
| @item builtin |
| @cindex builtin |
| A command that is implemented internally by the shell itself, rather |
| than by an executable program somewhere in the file system. |
| |
| @item control operator |
| @cindex control operator |
| A @code{token} that performs a control function. It is a @code{newline} |
| or one of the following: |
| @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, |
| @samp{|}, @samp{|&}, @samp{(}, or @samp{)}. |
| |
| @item exit status |
| @cindex exit status |
| The value returned by a command to its caller. The value is restricted |
| to eight bits, so the maximum value is 255. |
| |
| @item field |
| @cindex 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. |
| |
| @item filename |
| @cindex filename |
| A string of characters used to identify a file. |
| |
| @item job |
| @cindex job |
| A set of processes comprising a pipeline, and any processes descended |
| from it, that are all in the same process group. |
| |
| @item job control |
| @cindex job control |
| A mechanism by which users can selectively stop (suspend) and restart |
| (resume) execution of processes. |
| |
| @item metacharacter |
| @cindex metacharacter |
| A character that, when unquoted, separates words. A metacharacter is |
| a @code{blank} or one of the following characters: |
| @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or |
| @samp{>}. |
| |
| @item name |
| @cindex name |
| @cindex identifier |
| A @code{word} consisting solely of letters, numbers, and underscores, |
| and beginning with a letter or underscore. @code{Name}s are used as |
| shell variable and function names. |
| Also referred to as an @code{identifier}. |
| |
| @item operator |
| @cindex operator, shell |
| A @code{control operator} or a @code{redirection operator}. |
| @xref{Redirections}, for a list of redirection operators. |
| Operators contain at least one unquoted @code{metacharacter}. |
| |
| @item process group |
| @cindex process group |
| A collection of related processes each having the same process |
| group @sc{id}. |
| |
| @item process group ID |
| @cindex process group ID |
| A unique identifier that represents a @code{process group} |
| during its lifetime. |
| |
| @item reserved word |
| @cindex reserved word |
| A @code{word} that has a special meaning to the shell. Most reserved |
| words introduce shell flow control constructs, such as @code{for} and |
| @code{while}. |
| |
| @item return status |
| @cindex return status |
| A synonym for @code{exit status}. |
| |
| @item signal |
| @cindex signal |
| A mechanism by which a process may be notified by the kernel |
| of an event occurring in the system. |
| |
| @item special builtin |
| @cindex special builtin |
| A shell builtin command that has been classified as special by the |
| @sc{posix} standard. |
| |
| @item token |
| @cindex token |
| A sequence of characters considered a single unit by the shell. |
| It is either a @code{word} or an @code{operator}. |
| |
| @item word |
| @cindex word |
| A sequence of characters treated as a unit by the shell. |
| Words may not include unquoted @code{metacharacters}. |
| @end table |
| |
| @node Basic Shell Features |
| @chapter Basic Shell Features |
| @cindex Bourne shell |
| |
| Bash is an acronym for @samp{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 @sc{posix} |
| specification for the `standard' Unix shell. |
| |
| This chapter briefly summarizes the shell's `building blocks': |
| commands, control structures, shell functions, shell @i{parameters}, |
| shell expansions, |
| @i{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. |
| @end menu |
| |
| @node Shell Syntax |
| @section 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. |
| @end menu |
| |
| 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 (@samp{#}), 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. |
| |
| @node Shell Operation |
| @subsection 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: |
| |
| @enumerate |
| @item |
| Reads its input from a file (@pxref{Shell Scripts}), from a string |
| supplied as an argument to the @option{-c} invocation option |
| (@pxref{Invoking Bash}), or from the user's terminal. |
| |
| @item |
| Breaks the input into words and operators, obeying the quoting rules |
| described in @ref{Quoting}. These tokens are separated by |
| @code{metacharacters}. Alias expansion is performed by this step |
| (@pxref{Aliases}). |
| |
| @item |
| Parses the tokens into simple and compound commands |
| (@pxref{Shell Commands}). |
| |
| @item |
| Performs the various shell expansions (@pxref{Shell Expansions}), breaking |
| the expanded tokens into lists of filenames (@pxref{Filename Expansion}) |
| and commands and arguments. |
| |
| @item |
| Performs any necessary redirections (@pxref{Redirections}) and removes |
| the redirection operators and their operands from the argument list. |
| |
| @item |
| Executes the command (@pxref{Executing Commands}). |
| |
| @item |
| Optionally waits for the command to complete and collects its exit |
| status (@pxref{Exit Status}). |
| |
| @end enumerate |
| |
| @node Quoting |
| @subsection Quoting |
| @cindex 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. |
| @end menu |
| |
| 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 (@pxref{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 |
| (@pxref{History Interaction}), the |
| @var{history expansion} character, usually @samp{!}, must be quoted |
| to prevent history expansion. @xref{Bash History Facilities}, for |
| more details concerning history expansion. |
| |
| There are three quoting mechanisms: the |
| @var{escape character}, single quotes, and double quotes. |
| |
| @node Escape Character |
| @subsubsection Escape Character |
| A non-quoted backslash @samp{\} is the Bash escape character. |
| It preserves the literal value of the next character that follows, |
| with the exception of @code{newline}. If a @code{\newline} pair |
| appears, and the backslash itself is not quoted, the @code{\newline} |
| is treated as a line continuation (that is, it is removed from |
| the input stream and effectively ignored). |
| |
| @node Single Quotes |
| @subsubsection Single Quotes |
| |
| Enclosing characters in single quotes (@samp{'}) 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. |
| |
| @node Double Quotes |
| @subsubsection Double Quotes |
| |
| Enclosing characters in double quotes (@samp{"}) preserves the literal value |
| of all characters within the quotes, with the exception of |
| @samp{$}, @samp{`}, @samp{\}, |
| and, when history expansion is enabled, @samp{!}. |
| The characters @samp{$} and @samp{`} |
| retain their special meaning within double quotes (@pxref{Shell Expansions}). |
| The backslash retains its special meaning only when followed by one of |
| the following characters: |
| @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{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 @samp{!} |
| appearing in double quotes is escaped using a backslash. |
| The backslash preceding the @samp{!} is not removed. |
| |
| The special parameters @samp{*} and @samp{@@} have special meaning |
| when in double quotes (@pxref{Shell Parameter Expansion}). |
| |
| @node ANSI-C Quoting |
| @subsubsection ANSI-C Quoting |
| @cindex quoting, ANSI |
| |
| Words of the form @code{$'@var{string}'} are treated specially. The |
| word expands to @var{string}, with backslash-escaped characters replaced |
| as specified by the ANSI C standard. Backslash escape sequences, if |
| present, are decoded as follows: |
| |
| @table @code |
| @item \a |
| alert (bell) |
| @item \b |
| backspace |
| @item \e |
| an escape character (not ANSI C) |
| @item \f |
| form feed |
| @item \n |
| newline |
| @item \r |
| carriage return |
| @item \t |
| horizontal tab |
| @item \v |
| vertical tab |
| @item \\ |
| backslash |
| @item \' |
| single quote |
| @item \@var{nnn} |
| the eight-bit character whose value is the octal value @var{nnn} |
| (one to three digits) |
| @item \x@var{HH} |
| the eight-bit character whose value is the hexadecimal value @var{HH} |
| (one or two hex digits) |
| @item \c@var{x} |
| a control-@var{x} character |
| @end table |
| |
| @noindent |
| The expanded result is single-quoted, as if the dollar sign had not |
| been present. |
| |
| @node Locale Translation |
| @subsubsection Locale-Specific Translation |
| @cindex localization |
| @cindex internationalization |
| @cindex native languages |
| @cindex translation, native languages |
| |
| A double-quoted string preceded by a dollar sign (@samp{$}) will cause |
| the string to be translated according to the current locale. |
| If the current locale is @code{C} or @code{POSIX}, the dollar sign |
| is ignored. |
| If the string is translated and replaced, the replacement is |
| double-quoted. |
| |
| @vindex LC_MESSAGES |
| @vindex TEXTDOMAIN |
| @vindex TEXTDOMAINDIR |
| Some systems use the message catalog selected by the @env{LC_MESSAGES} |
| shell variable. Others create the name of the message catalog from the |
| value of the @env{TEXTDOMAIN} shell variable, possibly adding a |
| suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you |
| may need to set the @env{TEXTDOMAINDIR} variable to the location of |
| the message catalog files. Still others use both variables in this |
| fashion: |
| @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo. |
| |
| @node Comments |
| @subsection Comments |
| @cindex comments, shell |
| |
| In a non-interactive shell, or an interactive shell in which the |
| @code{interactive_comments} option to the @code{shopt} |
| builtin is enabled (@pxref{The Shopt Builtin}), |
| a word beginning with @samp{#} |
| causes that word and all remaining characters on that line to |
| be ignored. An interactive shell without the @code{interactive_comments} |
| option enabled does not allow comments. The @code{interactive_comments} |
| option is on by default in interactive shells. |
| @xref{Interactive Shells}, for a description of what makes |
| a shell interactive. |
| |
| @node Shell Commands |
| @section Shell Commands |
| @cindex commands, shell |
| |
| A simple shell command such as @code{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. |
| @end menu |
| |
| @node Simple Commands |
| @subsection Simple Commands |
| @cindex commands, simple |
| |
| A simple command is the kind of command encountered most often. |
| It's just a sequence of words separated by @code{blank}s, terminated |
| by one of the shell's control operators (@pxref{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 (@pxref{Exit Status}) of a simple command is |
| its exit status as provided |
| by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if |
| the command was terminated by signal @var{n}. |
| |
| @node Pipelines |
| @subsection Pipelines |
| @cindex pipeline |
| @cindex commands, pipelines |
| |
| A @code{pipeline} is a sequence of simple commands separated by one of |
| the control operators @samp{|} or @samp{|&}. |
| |
| @rwindex time |
| @rwindex ! |
| @cindex command timing |
| The format for a pipeline is |
| @example |
| [@code{time} [@code{-p}]] [@code{!}] @var{command1} [ [@code{|} or @code{|&}] @var{command2} @dots{}] |
| @end example |
| |
| @noindent |
| 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 @samp{|&} is used, the standard error of @var{command1} is connected to |
| @var{command2}'s standard input through the pipe; it is shorthand for |
| @code{2>&1 |}. This implicit redirection of the standard error is |
| performed after any redirections specified by the command. |
| |
| The reserved word @code{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 @option{-p} option changes the output format to that specified |
| by @sc{posix}. |
| The @env{TIMEFORMAT} variable may be set to a format string that |
| specifies how the timing information should be displayed. |
| @xref{Bash Variables}, for a description of the available formats. |
| The use of @code{time} as a reserved word permits the timing of |
| shell builtins, shell functions, and pipelines. An external |
| @code{time} command cannot time these easily. |
| |
| If the pipeline is not executed asynchronously (@pxref{Lists}), the |
| shell waits for all commands in the pipeline to complete. |
| |
| Each command in a pipeline is executed in its own subshell |
| (@pxref{Command Execution Environment}). The exit |
| status of a pipeline is the exit status of the last command in the |
| pipeline, unless the @code{pipefail} option is enabled |
| (@pxref{The Set Builtin}). |
| If @code{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 @samp{!} 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. |
| |
| @node Lists |
| @subsection Lists of Commands |
| @cindex commands, lists |
| |
| A @code{list} is a sequence of one or more pipelines separated by one |
| of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, |
| and optionally terminated by one of @samp{;}, @samp{&}, or a |
| @code{newline}. |
| |
| Of these list operators, @samp{&&} and @samp{||} |
| have equal precedence, followed by @samp{;} and @samp{&}, |
| which have equal precedence. |
| |
| A sequence of one or more newlines may appear in a @code{list} |
| to delimit commands, equivalent to a semicolon. |
| |
| If a command is terminated by the control operator @samp{&}, |
| the shell executes the command asynchronously in a subshell. |
| This is known as executing the command in the @var{background}. |
| The shell does not wait for the command to finish, and the return |
| status is 0 (true). |
| When job control is not active (@pxref{Job Control}), |
| the standard input for asynchronous commands, in the absence of any |
| explicit redirections, is redirected from @code{/dev/null}. |
| |
| Commands separated by a @samp{;} 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. |
| |
| @sc{and} and @sc{or} lists are sequences of one or more pipelines |
| separated by the control operators @samp{&&} and @samp{||}, |
| respectively. @sc{and} and @sc{or} lists are executed with left |
| associativity. |
| |
| An @sc{and} list has the form |
| @example |
| @var{command1} && @var{command2} |
| @end example |
| |
| @noindent |
| @var{command2} is executed if, and only if, @var{command1} |
| returns an exit status of zero. |
| |
| An @sc{or} list has the form |
| @example |
| @var{command1} || @var{command2} |
| @end example |
| |
| @noindent |
| @var{command2} is executed if, and only if, @var{command1} |
| returns a non-zero exit status. |
| |
| The return status of |
| @sc{and} and @sc{or} lists is the exit status of the last command |
| executed in the list. |
| |
| @node Compound Commands |
| @subsection Compound Commands |
| @cindex commands, compound |
| |
| @menu |
| * Looping Constructs:: Shell commands for iterative action. |
| * Conditional Constructs:: Shell commands for conditional execution. |
| * Command Grouping:: Ways to group commands. |
| @end menu |
| |
| 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 (@pxref{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. |
| |
| @node Looping Constructs |
| @subsubsection Looping Constructs |
| @cindex commands, looping |
| |
| Bash supports the following looping constructs. |
| |
| Note that wherever a @samp{;} appears in the description of a |
| command's syntax, it may be replaced with one or more newlines. |
| |
| @table @code |
| @item until |
| @rwindex until |
| @rwindex do |
| @rwindex done |
| The syntax of the @code{until} command is: |
| @example |
| until @var{test-commands}; do @var{consequent-commands}; done |
| @end example |
| Execute @var{consequent-commands} as long as |
| @var{test-commands} has an exit status which is not zero. |
| The return status is the exit status of the last command executed |
| in @var{consequent-commands}, or zero if none was executed. |
| |
| @item while |
| @rwindex while |
| The syntax of the @code{while} command is: |
| @example |
| while @var{test-commands}; do @var{consequent-commands}; done |
| @end example |
| |
| Execute @var{consequent-commands} as long as |
| @var{test-commands} has an exit status of zero. |
| The return status is the exit status of the last command executed |
| in @var{consequent-commands}, or zero if none was executed. |
| |
| @item for |
| @rwindex for |
| The syntax of the @code{for} command is: |
| |
| @example |
| for @var{name} [in @var{words} @dots{}]; do @var{commands}; done |
| @end example |
| Expand @var{words}, and execute @var{commands} once for each member |
| in the resultant list, with @var{name} bound to the current member. |
| If @samp{in @var{words}} is not present, the @code{for} command |
| executes the @var{commands} once for each positional parameter that is |
| set, as if @samp{in "$@@"} had been specified |
| (@pxref{Special Parameters}). |
| The return status is the exit status of the last command that executes. |
| If there are no items in the expansion of @var{words}, no commands are |
| executed, and the return status is zero. |
| |
| An alternate form of the @code{for} command is also supported: |
| |
| @example |
| for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done |
| @end example |
| First, the arithmetic expression @var{expr1} is evaluated according |
| to the rules described below (@pxref{Shell Arithmetic}). |
| The arithmetic expression @var{expr2} is then evaluated repeatedly |
| until it evaluates to zero. |
| Each time @var{expr2} evaluates to a non-zero value, @var{commands} are |
| executed and the arithmetic expression @var{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 @var{list} |
| that is executed, or false if any of the expressions is invalid. |
| |
| @end table |
| |
| The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) |
| may be used to control loop execution. |
| |
| @node Conditional Constructs |
| @subsubsection Conditional Constructs |
| @cindex commands, conditional |
| |
| @table @code |
| @item if |
| @rwindex if |
| @rwindex then |
| @rwindex else |
| @rwindex elif |
| @rwindex fi |
| The syntax of the @code{if} command is: |
| |
| @example |
| if @var{test-commands}; then |
| @var{consequent-commands}; |
| [elif @var{more-test-commands}; then |
| @var{more-consequents};] |
| [else @var{alternate-consequents};] |
| fi |
| @end example |
| |
| The @var{test-commands} list is executed, and if its return status is zero, |
| the @var{consequent-commands} list is executed. |
| If @var{test-commands} returns a non-zero status, each @code{elif} list |
| is executed in turn, and if its exit status is zero, |
| the corresponding @var{more-consequents} is executed and the |
| command completes. |
| If @samp{else @var{alternate-consequents}} is present, and |
| the final command in the final @code{if} or @code{elif} clause |
| has a non-zero exit status, then @var{alternate-consequents} is executed. |
| The return status is the exit status of the last command executed, or |
| zero if no condition tested true. |
| |
| @item case |
| @rwindex case |
| @rwindex in |
| @rwindex esac |
| The syntax of the @code{case} command is: |
| |
| @example |
| @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac} |
| @end example |
| |
| @code{case} will selectively execute the @var{command-list} corresponding to |
| the first @var{pattern} that matches @var{word}. |
| If the shell option @code{nocasematch} |
| (see the description of @code{shopt} in @ref{The Shopt Builtin}) |
| is enabled, the match is performed without regard to the case |
| of alphabetic characters. |
| The @samp{|} is used to separate multiple patterns, and the @samp{)} |
| operator terminates a pattern list. |
| A list of patterns and an associated command-list is known |
| as a @var{clause}. |
| |
| Each clause must be terminated with @samp{;;}, @samp{,&}, or @samp{;;&}. |
| The @var{word} undergoes tilde expansion, parameter expansion, command |
| substitution, arithmetic expansion, and quote removal before matching is |
| attempted. Each @var{pattern} undergoes tilde expansion, parameter |
| expansion, command substitution, and arithmetic expansion. |
| |
| There may be an arbitrary number of @code{case} clauses, each terminated |
| by a @samp{;;}, @samp{;&}, or @samp{;;&}. |
| The first pattern that matches determines the |
| command-list that is executed. |
| |
| Here is an example using @code{case} in a script that could be used to |
| describe one interesting feature of an animal: |
| |
| @example |
| 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." |
| @end example |
| |
| @noindent |
| |
| If the @samp{;;} operator is used, no subsequent matches are attempted after |
| the first pattern match. |
| Using @samp{;&} in place of @samp{;;} causes execution to continue with |
| the @var{command-list} associated with the next clause, if any. |
| Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns |
| in the next clause, if any, and execute any associated @var{command-list} |
| on a successful match. |
| |
| The return status is zero if no @var{pattern} is matched. Otherwise, the |
| return status is the exit status of the @var{command-list} executed. |
| |
| @item select |
| @rwindex select |
| |
| The @code{select} construct allows the easy generation of menus. |
| It has almost the same syntax as the @code{for} command: |
| |
| @example |
| select @var{name} [in @var{words} @dots{}]; do @var{commands}; done |
| @end example |
| |
| The list of words following @code{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 |
| @samp{in @var{words}} is omitted, the positional parameters are printed, |
| as if @samp{in "$@@"} had been specified. |
| The @env{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 @var{name} is set to that word. |
| If the line is empty, the words and prompt are displayed again. |
| If @code{EOF} is read, the @code{select} command completes. |
| Any other value read causes @var{name} to be set to null. |
| The line read is saved in the variable @env{REPLY}. |
| |
| The @var{commands} are executed after each selection until a |
| @code{break} command is executed, at which |
| point the @code{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. |
| |
| @example |
| select fname in *; |
| do |
| echo you picked $fname \($REPLY\) |
| break; |
| done |
| @end example |
| |
| @item ((@dots{})) |
| @example |
| (( @var{expression} )) |
| @end example |
| |
| The arithmetic @var{expression} is evaluated according to the rules |
| described below (@pxref{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 |
| @example |
| let "@var{expression}" |
| @end example |
| @noindent |
| @xref{Bash Builtins}, for a full description of the @code{let} builtin. |
| |
| @item [[@dots{}]] |
| @rwindex [[ |
| @rwindex ]] |
| @example |
| [[ @var{expression} ]] |
| @end example |
| |
| Return a status of 0 or 1 depending on the evaluation of |
| the conditional expression @var{expression}. |
| Expressions are composed of the primaries described below in |
| @ref{Bash Conditional Expressions}. |
| Word splitting and filename expansion are not performed on the words |
| between the @samp{[[} and @samp{]]}; tilde expansion, parameter and |
| variable expansion, arithmetic expansion, command substitution, process |
| substitution, and quote removal are performed. |
| Conditional operators such as @samp{-f} must be unquoted to be recognized |
| as primaries. |
| |
| When the @samp{==} and @samp{!=} operators are used, the string to the |
| right of the operator is considered a pattern and matched according |
| to the rules described below in @ref{Pattern Matching}. |
| If the shell option @code{nocasematch} |
| (see the description of @code{shopt} in @ref{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 (@samp{==}) or does not |
| match (@samp{!=})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, @samp{=~}, is available, with the same |
| precedence as @samp{==} and @samp{!=}. |
| When it is used, the string to the right of the operator is considered |
| an extended regular expression and matched accordingly (as in @i{regex}3)). |
| 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 @code{nocasematch} |
| (see the description of @code{shopt} in @ref{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 @code{BASH_REMATCH}. |
| The element of @code{BASH_REMATCH} with index 0 is the portion of the string |
| matching the entire regular expression. |
| The element of @code{BASH_REMATCH} with index @var{n} is the portion of the |
| string matching the @var{n}th parenthesized subexpression. |
| |
| Expressions may be combined using the following operators, listed |
| in decreasing order of precedence: |
| |
| @table @code |
| @item ( @var{expression} ) |
| Returns the value of @var{expression}. |
| This may be used to override the normal precedence of operators. |
| |
| @item ! @var{expression} |
| True if @var{expression} is false. |
| |
| @item @var{expression1} && @var{expression2} |
| True if both @var{expression1} and @var{expression2} are true. |
| |
| @item @var{expression1} || @var{expression2} |
| True if either @var{expression1} or @var{expression2} is true. |
| @end table |
| @noindent |
| The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the |
| value of @var{expression1} is sufficient to determine the return |
| value of the entire conditional expression. |
| |
| @end table |
| |
| @node Command Grouping |
| @subsubsection Grouping Commands |
| @cindex commands, grouping |
| |
| 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. |
| |
| @table @code |
| @item () |
| @example |
| ( @var{list} ) |
| @end example |
| |
| Placing a list of commands between parentheses causes a subshell |
| environment to be created (@pxref{Command Execution Environment}), and each |
| of the commands in @var{list} to be executed in that subshell. Since the |
| @var{list} is executed in a subshell, variable assignments do not remain in |
| effect after the subshell completes. |
| |
| @item @{@} |
| @rwindex @{ |
| @rwindex @} |
| @example |
| @{ @var{list}; @} |
| @end example |
| |
| 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 @var{list} is required. |
| @end table |
| |
| In addition to the creation of a subshell, there is a subtle difference |
| between these two constructs due to historical reasons. The braces |
| are @code{reserved words}, so they must be separated from the @var{list} |
| by @code{blank}s or other shell metacharacters. |
| The parentheses are @code{operators}, and are |
| recognized as separate tokens by the shell even if they are not separated |
| from the @var{list} by whitespace. |
| |
| The exit status of both of these constructs is the exit status of |
| @var{list}. |
| |
| @node Coprocesses |
| @subsection Coprocesses |
| @cindex coprocess |
| |
| A @code{coprocess} is a shell command preceded by the @code{coproc} |
| reserved word. |
| A coprocess is executed asynchronously in a subshell, as if the command |
| had been terminated with the @samp{&} control operator, with a two-way pipe |
| established between the executing shell and the coprocess. |
| |
| The format for a coprocess is: |
| @example |
| @code{coproc} [@var{NAME}] @var{command} [@var{redirections}] |
| @end example |
| |
| @noindent |
| This creates a coprocess named @var{NAME}. |
| If @var{NAME} is not supplied, the default name is @var{COPROC}. |
| @var{NAME} must not be supplied if @var{command} is a simple |
| command (@pxref{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 |
| (@pxref{Arrays}) |
| named @var{NAME} in the context of the executing shell. |
| The standard output of @var{command} |
| is connected via a pipe to a file descriptor in the executing shell, |
| and that file descriptor is assigned to @var{NAME}[0]. |
| The standard input of @var{command} |
| is connected via a pipe to a file descriptor in the executing shell, |
| and that file descriptor is assigned to @var{NAME}[1]. |
| This pipe is established before any redirections specified by the |
| command (@pxref{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 @var{NAME}_PID. |
| The @code{wait} |
| builtin command may be used to wait for the coprocess to terminate. |
| |
| The return status of a coprocess is the exit status of @var{command}. |
| |
| @node Shell Functions |
| @section Shell Functions |
| @cindex shell function |
| @cindex functions, shell |
| |
| 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: |
| @rwindex function |
| @example |
| [ @code{function} ] @var{name} () @var{compound-command} [ @var{redirections} ] |
| @end example |
| |
| This defines a shell function named @var{name}. The reserved |
| word @code{function} is optional. |
| If the @code{function} reserved |
| word is supplied, the parentheses are optional. |
| The @var{body} of the function is the compound command |
| @var{compound-command} (@pxref{Compound Commands}). |
| That command is usually a @var{list} enclosed between @{ and @}, but |
| may be any compound command listed above. |
| @var{compound-command} is executed whenever @var{name} is specified as the |
| name of a command. |
| Any redirections (@pxref{Redirections}) associated with the shell function |
| are performed when the function is executed. |
| |
| A function definition may be deleted using the @option{-f} option to the |
| @code{unset} builtin (@pxref{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 |
| @code{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 @var{list} must be terminated by a semicolon, |
| a @samp{&}, or a newline. |
| |
| When a function is executed, the arguments to the |
| function become the positional parameters |
| during its execution (@pxref{Positional Parameters}). |
| The special parameter @samp{#} that expands to the number of |
| positional parameters is updated to reflect the change. |
| Special parameter @code{0} is unchanged. |
| The first element of the @env{FUNCNAME} variable is set to the |
| name of the function while the function is executing. |
| All other aspects of the shell execution |
| environment are identical between a function and its caller |
| with the exception that the @env{DEBUG} and @env{RETURN} traps |
| are not inherited unless the function has been given the |
| @code{trace} attribute using the @code{declare} builtin or |
| the @code{-o functrace} option has been enabled with |
| the @code{set} builtin, |
| (in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps). |
| @xref{Bourne Shell Builtins}, for the description of the |
| @code{trap} builtin. |
| |
| If the builtin command @code{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 @code{RETURN} trap is executed |
| before execution resumes. |
| When a function completes, the values of the |
| positional parameters and the special parameter @samp{#} |
| are restored to the values they had prior to the function's |
| execution. If a numeric argument is given to @code{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 @code{return}. |
| |
| Variables local to the function may be declared with the |
| @code{local} builtin. These variables are visible only to |
| the function and the commands it invokes. |
| |
| Function names and definitions may be listed with the |
| @option{-f} option to the @code{declare} or @code{typeset} |
| builtin commands (@pxref{Bash Builtins}). |
| The @option{-F} option to @code{declare} or @code{typeset} |
| will list the function names only |
| (and optionally the source file and line number, if the @code{extdebug} |
| shell option is enabled). |
| Functions may be exported so that subshells |
| automatically have them defined with the |
| @option{-f} option to the @code{export} builtin |
| (@pxref{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. |
| |
| @node Shell Parameters |
| @section Shell Parameters |
| @cindex parameters |
| @cindex variable, shell |
| @cindex shell variable |
| |
| @menu |
| * Positional Parameters:: The shell's command-line arguments. |
| * Special Parameters:: Parameters denoted by special characters. |
| @end menu |
| |
| A @var{parameter} is an entity that stores values. |
| It can be a @code{name}, a number, or one of the special characters |
| listed below. |
| A @var{variable} is a parameter denoted by a @code{name}. |
| A variable has a @var{value} and zero or more @var{attributes}. |
| Attributes are assigned using the @code{declare} builtin command |
| (see the description of the @code{declare} builtin in @ref{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 @code{unset} builtin command. |
| |
| A variable may be assigned to by a statement of the form |
| @example |
| @var{name}=[@var{value}] |
| @end example |
| @noindent |
| If @var{value} |
| is not given, the variable is assigned the null string. All |
| @var{value}s undergo tilde expansion, parameter and variable expansion, |
| command substitution, arithmetic expansion, and quote |
| removal (detailed below). If the variable has its @code{integer} |
| attribute set, then @var{value} |
| is evaluated as an arithmetic expression even if the @code{$((@dots{}))} |
| expansion is not used (@pxref{Arithmetic Expansion}). |
| Word splitting is not performed, with the exception |
| of @code{"$@@"} as explained below. |
| Filename expansion is not performed. |
| Assignment statements may also appear as arguments to the |
| @code{alias}, |
| @code{declare}, @code{typeset}, @code{export}, @code{readonly}, |
| and @code{local} builtin commands. |
| |
| In the context where an assignment statement is assigning a value |
| to a shell variable or array index (@pxref{Arrays}), the @samp{+=} |
| operator can be used to |
| append to or add to the variable's previous value. |
| When @samp{+=} is applied to a variable for which the integer attribute |
| has been set, @var{value} is evaluated as an arithmetic expression and |
| added to the variable's current value, which is also evaluated. |
| When @samp{+=} is applied to an array variable using compound assignment |
| (@pxref{Arrays}), the |
| variable's value is not unset (as it is when using @samp{=}), 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, @var{value} is expanded and |
| appended to the variable's value. |
| |
| @node Positional Parameters |
| @subsection Positional Parameters |
| @cindex parameters, positional |
| |
| A @var{positional parameter} is a parameter denoted by one or more |
| digits, other than the single digit @code{0}. Positional parameters are |
| assigned from the shell's arguments when it is invoked, |
| and may be reassigned using the @code{set} builtin command. |
| Positional parameter @code{N} may be referenced as @code{$@{N@}}, or |
| as @code{$N} when @code{N} consists of a single digit. |
| Positional parameters may not be assigned to with assignment statements. |
| The @code{set} and @code{shift} builtins are used to set and |
| unset them (@pxref{Shell Builtin Commands}). |
| The positional parameters are |
| temporarily replaced when a shell function is executed |
| (@pxref{Shell Functions}). |
| |
| When a positional parameter consisting of more than a single |
| digit is expanded, it must be enclosed in braces. |
| |
| @node Special Parameters |
| @subsection Special Parameters |
| @cindex parameters, special |
| |
| The shell treats several parameters specially. These parameters may |
| only be referenced; assignment to them is not allowed. |
| |
| @vtable @code |
| |
| @item * |
| 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 @env{IFS} |
| special variable. That is, @code{"$*"} is equivalent |
| to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c} |
| is the first character of the value of the @code{IFS} |
| variable. |
| If @env{IFS} is unset, the parameters are separated by spaces. |
| If @env{IFS} is null, the parameters are joined without intervening |
| separators. |
| |
| |
| @item @@ |
| Expands to the positional parameters, starting from one. When the |
| expansion occurs within double quotes, each parameter expands to a |
| separate word. That is, @code{"$@@"} is equivalent to |
| @code{"$1" "$2" @dots{}}. |
| 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, @code{"$@@"} and |
| @code{$@@} |
| expand to nothing (i.e., they are removed). |
| |
| @item # |
| Expands to the number of positional parameters in decimal. |
| |
| @item ? |
| Expands to the exit status of the most recently executed foreground |
| pipeline. |
| |
| @item - |
| (A hyphen.) Expands to the current option flags as specified upon |
| invocation, by the @code{set} |
| builtin command, or those set by the shell itself |
| (such as the @option{-i} option). |
| |
| @item $ |
| Expands to the process @sc{id} of the shell. In a @code{()} subshell, it |
| expands to the process @sc{id} of the invoking shell, not the subshell. |
| |
| @item ! |
| Expands to the process @sc{id} of the most recently executed background |
| (asynchronous) command. |
| |
| @item 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 |
| (@pxref{Shell Scripts}), @code{$0} is set to the name of that file. |
| If Bash is started with the @option{-c} option (@pxref{Invoking Bash}), |
| then @code{$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. |
| |
| @item _ |
| (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. |
| @end vtable |
| |
| @node Shell Expansions |
| @section Shell Expansions |
| @cindex expansion |
| |
| Expansion is performed on the command line after it has been split into |
| @code{token}s. There are seven kinds of expansion performed: |
| @itemize @bullet |
| @item brace expansion |
| @item tilde expansion |
| @item parameter and variable expansion |
| @item command substitution |
| @item arithmetic expansion |
| @item word splitting |
| @item filename expansion |
| @end itemize |
| |
| @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. |
| @end menu |
| |
| 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: @var{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 |
| @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"} |
| (@pxref{Arrays}). |
| |
| After all expansions, @code{quote removal} (@pxref{Quote Removal}) |
| is performed. |
| |
| @node Brace Expansion |
| @subsection Brace Expansion |
| @cindex brace expansion |
| @cindex expansion, brace |
| |
| Brace expansion is a mechanism by which arbitrary strings may be generated. |
| This mechanism is similar to |
| @var{filename expansion} (@pxref{Filename Expansion}), |
| but the file names generated need not exist. |
| Patterns to be brace expanded take the form of an optional @var{preamble}, |
| followed by either a series of comma-separated strings or a seqeunce expression |
| between a pair of braces, |
| followed by an optional @var{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, |
| @example |
| bash$ echo a@{d,c,b@}e |
| ade ace abe |
| @end example |
| |
| A sequence expression takes the form @code{@{@var{x}..@var{y}[@var{incr}]@}}, |
| where @var{x} and @var{y} are either integers or single characters, |
| and @var{incr}, an optional increment, is an integer. |
| When integers are supplied, the expression expands to each number between |
| @var{x} and @var{y}, inclusive. |
| Supplied integers may be prefixed with @samp{0} to force each term to have the |
| same width. When either @var{x} or @var{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 @var{x} and @var{y}, inclusive. Note that |
| both @var{x} and @var{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 @samp{$@{} |
| 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 @samp{,} may be quoted with a backslash to prevent its |
| being considered part of a brace expression. |
| To avoid conflicts with parameter expansion, the string @samp{$@{} |
| 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: |
| @example |
| mkdir /usr/local/src/bash/@{old,new,dist,bugs@} |
| @end example |
| or |
| @example |
| chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} |
| @end example |
| |
| @node Tilde Expansion |
| @subsection Tilde Expansion |
| @cindex tilde expansion |
| @cindex expansion, tilde |
| |
| If a word begins with an unquoted tilde character (@samp{~}), all of the |
| characters up to the first unquoted slash (or all characters, |
| if there is no unquoted slash) are considered a @var{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 @var{login name}. |
| If this login name is the null string, the tilde is replaced with the |
| value of the @env{HOME} shell variable. |
| If @env{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 @samp{~+}, the value of |
| the shell variable @env{PWD} replaces the tilde-prefix. |
| If the tilde-prefix is @samp{~-}, the value of the shell variable |
| @env{OLDPWD}, if it is set, is substituted. |
| |
| If the characters following the tilde in the tilde-prefix consist of a |
| number @var{N}, optionally prefixed by a @samp{+} or a @samp{-}, |
| the tilde-prefix is replaced with the |
| corresponding element from the directory stack, as it would be displayed |
| by the @code{dirs} builtin invoked with the characters following tilde |
| in the tilde-prefix as an argument (@pxref{The Directory Stack}). |
| If the tilde-prefix, sans the tilde, consists of a number without a |
| leading @samp{+} or @samp{-}, @samp{+} 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 @samp{:} or the first @samp{=}. |
| In these cases, tilde expansion is also performed. |
| Consequently, one may use file names with tildes in assignments to |
| @env{PATH}, @env{MAILPATH}, and @env{CDPATH}, |
| and the shell assigns the expanded value. |
| |
| The following table shows how Bash treats unquoted tilde-prefixes: |
| |
| @table @code |
| @item ~ |
| The value of @code{$HOME} |
| @item ~/foo |
| @file{$HOME/foo} |
| |
| @item ~fred/foo |
| The subdirectory @code{foo} of the home directory of the user |
| @code{fred} |
| |
| @item ~+/foo |
| @file{$PWD/foo} |
| |
| @item ~-/foo |
| @file{$@{OLDPWD-'~-'@}/foo} |
| |
| @item ~@var{N} |
| The string that would be displayed by @samp{dirs +@var{N}} |
| |
| @item ~+@var{N} |
| The string that would be displayed by @samp{dirs +@var{N}} |
| |
| @item ~-@var{N} |
| The string that would be displayed by @samp{dirs -@var{N}} |
| |
| @end table |
| |
| @node Shell Parameter Expansion |
| @subsection Shell Parameter Expansion |
| @cindex parameter expansion |
| @cindex expansion, parameter |
| |
| The @samp{$} 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 @samp{@}} |
| 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 $@{@var{parameter}@}. |
| The value of @var{parameter} is substituted. The braces are required |
| when @var{parameter} |
| is a positional parameter with more than one digit, |
| or when @var{parameter} |
| is followed by a character that is not to be |
| interpreted as part of its name. |
| |
| If the first character of @var{parameter} is an exclamation point, |
| a level of variable indirection is introduced. |
| Bash uses the value of the variable formed from the rest of |
| @var{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 @var{parameter} itself. |
| This is known as @code{indirect expansion}. |
| The exceptions to this are the expansions of $@{!@var{prefix*}@} |
| and $@{!@var{name}[@@]@} |
| described below. |
| The exclamation point must immediately follow the left brace in order to |
| introduce indirection. |
| |
| In each of the cases below, @var{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 @var{parameter}'s existence and that its value |
| is not null; if the colon is omitted, the operator tests only for existence. |
| |
| @table @code |
| |
| @item $@{@var{parameter}:@minus{}@var{word}@} |
| If @var{parameter} is unset or null, the expansion of |
| @var{word} is substituted. Otherwise, the value of |
| @var{parameter} is substituted. |
| |
| @item $@{@var{parameter}:=@var{word}@} |
| If @var{parameter} |
| is unset or null, the expansion of @var{word} |
| is assigned to @var{parameter}. |
| The value of @var{parameter} is then substituted. |
| Positional parameters and special parameters may not be assigned to |
| in this way. |
| |
| @item $@{@var{parameter}:?@var{word}@} |
| If @var{parameter} |
| is null or unset, the expansion of @var{word} (or a message |
| to that effect if @var{word} |
| is not present) is written to the standard error and the shell, if it |
| is not interactive, exits. Otherwise, the value of @var{parameter} is |
| substituted. |
| |
| @item $@{@var{parameter}:+@var{word}@} |
| If @var{parameter} |
| is null or unset, nothing is substituted, otherwise the expansion of |
| @var{word} is substituted. |
| |
| @item $@{@var{parameter}:@var{offset}@} |
| @itemx $@{@var{parameter}:@var{offset}:@var{length}@} |
| Expands to up to @var{length} characters of @var{parameter} |
| starting at the character specified by @var{offset}. |
| If @var{length} is omitted, expands to the substring of |
| @var{parameter} starting at the character specified by @var{offset}. |
| @var{length} and @var{offset} are arithmetic expressions |
| (@pxref{Shell Arithmetic}). |
| This is referred to as Substring Expansion. |
| |
| @var{length} must evaluate to a number greater than or equal to zero. |
| If @var{offset} evaluates to a number less than zero, the value |
| is used as an offset from the end of the value of @var{parameter}. |
| If @var{parameter} is @samp{@@}, the result is @var{length} positional |
| parameters beginning at @var{offset}. |
| If @var{parameter} is an indexed array name subscripted |
| by @samp{@@} or @samp{*}, the result is the @var{length} |
| members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}. |
| A negative @var{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 @samp{:-} expansion. |
| Substring indexing is zero-based unless the positional parameters |
| are used, in which case the indexing starts at 1 by default. |
| If @var{offset} is 0, and the positional parameters are used, @code{$@@} is |
| prefixed to the list. |
| |
| @item $@{!@var{prefix}*@} |
| @itemx $@{!@var{prefix}@@@} |
| Expands to the names of variables whose names begin with @var{prefix}, |
| separated by the first character of the @env{IFS} special variable. |
| When @samp{@@} is used and the expansion appears within double quotes, each |
| variable name expands to a separate word. |
| |
| @item $@{!@var{name}[@@]@} |
| @itemx $@{!@var{name}[*]@} |
| If @var{name} is an array variable, expands to the list of array indices |
| (keys) assigned in @var{name}. |
| If @var{name} is not an array, expands to 0 if @var{name} is set and null |
| otherwise. |
| When @samp{@@} is used and the expansion appears within double quotes, each |
| key expands to a separate word. |
| |
| @item $@{#@var{parameter}@} |
| The length in characters of the expanded value of @var{parameter} is |
| substituted. |
| If @var{parameter} is @samp{*} or @samp{@@}, the value substituted |
| is the number of positional parameters. |
| If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, |
| the value substituted is the number of elements in the array. |
| |
| @item $@{@var{parameter}#@var{word}@} |
| @itemx $@{@var{parameter}##@var{word}@} |
| The @var{word} |
| is expanded to produce a pattern just as in filename |
| expansion (@pxref{Filename Expansion}). If the pattern matches |
| the beginning of the expanded value of @var{parameter}, |
| then the result of the expansion is the expanded value of @var{parameter} |
| with the shortest matching pattern (the @samp{#} case) or the |
| longest matching pattern (the @samp{##} case) deleted. |
| If @var{parameter} is @samp{@@} or @samp{*}, |
| the pattern removal operation is applied to each positional |
| parameter in turn, and the expansion is the resultant list. |
| If @var{parameter} is an array variable subscripted with |
| @samp{@@} or @samp{*}, |
| the pattern removal operation is applied to each member of the |
| array in turn, and the expansion is the resultant list. |
| |
| @item $@{@var{parameter}%@var{word}@} |
| @itemx $@{@var{parameter}%%@var{word}@} |
| The @var{word} is expanded to produce a pattern just as in |
| filename expansion. |
| If the pattern matches a trailing portion of the expanded value of |
| @var{parameter}, then the result of the expansion is the value of |
| @var{parameter} with the shortest matching pattern (the @samp{%} case) |
| or the longest matching pattern (the @samp{%%} case) deleted. |
| If @var{parameter} is @samp{@@} or @samp{*}, |
| the pattern removal operation is applied to each positional |
| parameter in turn, and the expansion is the resultant list. |
| If @var{parameter} |
| is an array variable subscripted with @samp{@@} or @samp{*}, |
| the pattern removal operation is applied to each member of the |
| array in turn, and the expansion is the resultant list. |
| |
| @item $@{@var{parameter}/@var{pattern}/@var{string}@} |
| |
| The @var{pattern} is expanded to produce a pattern just as in |
| filename expansion. |
| @var{Parameter} is expanded and the longest match of @var{pattern} |
| against its value is replaced with @var{string}. |
| If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are |
| replaced with @var{string}. Normally only the first match is replaced. |
| If @var{pattern} begins with @samp{#}, it must match at the beginning |
| of the expanded value of @var{parameter}. |
| If @var{pattern} begins with @samp{%}, it must match at the end |
| of the expanded value of @var{parameter}. |
| If @var{string} is null, matches of @var{pattern} are deleted |
| and the @code{/} following @var{pattern} may be omitted. |
| If @var{parameter} is @samp{@@} or @samp{*}, |
| the substitution operation is applied to each positional |
| parameter in turn, and the expansion is the resultant list. |
| If @var{parameter} |
| is an array variable subscripted with @samp{@@} or @samp{*}, |
| the substitution operation is applied to each member of the |
| array in turn, and the expansion is the resultant list. |
| |
| @item $@{@var{parameter}^@var{pattern}@} |
| @itemx $@{@var{parameter}^^@var{pattern}@} |
| @itemx $@{@var{parameter},@var{pattern}@} |
| @itemx $@{@var{parameter},,@var{pattern}@} |
| This expansion modifies the case of alphabetic characters in @var{parameter}. |
| The @var{pattern} is expanded to produce a pattern just as in |
| pathname expansion. |
| The @samp{^} operator converts lowercase letters matching @var{pattern} |
| to uppercase; the @samp{,} operator converts matching uppercase letters |
| to lowercase. |
| The @samp{^^} and @samp{,,} expansions convert each matched character in the |
| expanded value; the @samp{^} and @samp{,} expansions match and convert only |
| the first character in the expanded value. |
| If @var{pattern} is omitted, it is treated like a @samp{?}, which matches |
| every character. |
| If @var{parameter} is @samp{@@} or @samp{*}, |
| the case modification operation is applied to each positional |
| parameter in turn, and the expansion is the resultant list. |
| If @var{parameter} |
| is an array variable subscripted with @samp{@@} or @samp{*}, |
| the case modification operation is applied to each member of the |
| array in turn, and the expansion is the resultant list. |
| |
| @end table |
| |
| @node Command Substitution |
| @subsection Command Substitution |
| @cindex 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: |
| @example |
| $(@var{command}) |
| @end example |
| @noindent |
| or |
| @example |
| `@var{command}` |
| @end example |
| |
| @noindent |
| Bash performs the expansion by executing @var{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 @code{$(cat @var{file})} can be |
| replaced by the equivalent but faster @code{$(< @var{file})}. |
| |
| When the old-style backquote form of substitution is used, |
| backslash retains its literal meaning except when followed by |
| @samp{$}, @samp{`}, or @samp{\}. |
| The first backquote not preceded by a backslash terminates the |
| command substitution. |
| When using the @code{$(@var{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. |
| |
| @node Arithmetic Expansion |
| @subsection Arithmetic Expansion |
| @cindex expansion, arithmetic |
| @cindex arithmetic expansion |
| |
| Arithmetic expansion allows the evaluation of an arithmetic expression |
| and the substitution of the result. The format for arithmetic expansion is: |
| |
| @example |
| $(( @var{expression} )) |
| @end example |
| |
| 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 |
| (@pxref{Shell Arithmetic}). |
| If the expression is invalid, Bash prints a message indicating |
| failure to the standard error and no substitution occurs. |
| |
| @node Process Substitution |
| @subsection Process Substitution |
| @cindex process substitution |
| |
| Process substitution is supported on systems that support named |
| pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files. |
| It takes the form of |
| @example |
| <(@var{list}) |
| @end example |
| @noindent |
| or |
| @example |
| >(@var{list}) |
| @end example |
| @noindent |
| The process @var{list} is run with its input or output connected to a |
| @sc{fifo} or some file in @file{/dev/fd}. The name of this file is |
| passed as an argument to the current command as the result of the |
| expansion. If the @code{>(@var{list})} form is used, writing to |
| the file will provide input for @var{list}. If the |
| @code{<(@var{list})} form is used, the file passed as an |
| argument should be read to obtain the output of @var{list}. |
| Note that no space may appear between the @code{<} or @code{>} |
| 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. |
| |
| @node Word Splitting |
| @subsection Word Splitting |
| @cindex 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 @env{$IFS} as a delimiter, and splits |
| the results of the other expansions into words on these characters. |
| If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, |
| the default, then sequences of |
| @code{ <space>}, @code{<tab>}, and @code{<newline>} |
| at the beginning and end of the results of the previous |
| expansions are ignored, and any sequence of @env{IFS} |
| characters not at the beginning or end serves to delimit words. |
| If @env{IFS} has a value other than the default, then sequences of |
| the whitespace characters @code{space} and @code{tab} |
| are ignored at the beginning and end of the |
| word, as long as the whitespace character is in the |
| value of @env{IFS} (an @env{IFS} whitespace character). |
| Any character in @env{IFS} that is not @env{IFS} |
| whitespace, along with any adjacent @env{IFS} |
| whitespace characters, delimits a field. A sequence of @env{IFS} |
| whitespace characters is also treated as a delimiter. |
| If the value of @env{IFS} is null, no word splitting occurs. |
| |
| Explicit null arguments (@code{""} or @code{''}) 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. |
| |
| @node Filename Expansion |
| @subsection Filename Expansion |
| @menu |
| * Pattern Matching:: How the shell matches patterns. |
| @end menu |
| @cindex expansion, filename |
| @cindex expansion, pathname |
| @cindex filename expansion |
| @cindex pathname expansion |
| |
| After word splitting, unless the @option{-f} option has been set |
| (@pxref{The Set Builtin}), Bash scans each word for the characters |
| @samp{*}, @samp{?}, and @samp{[}. |
| If one of these characters appears, then the word is |
| regarded as a @var{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 @code{nullglob} is disabled, the word is left |
| unchanged. |
| If the @code{nullglob} option is set, and no matches are found, the word |
| is removed. |
| If the @code{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 @code{nocaseglob} is enabled, the match is performed |
| without regard to the case of alphabetic characters. |
| |
| When a pattern is used for filename generation, the character @samp{.} |
| at the start of a filename or immediately following a slash |
| must be matched explicitly, unless the shell option @code{dotglob} is set. |
| When matching a file name, the slash character must always be |
| matched explicitly. |
| In other cases, the @samp{.} character is not treated specially. |
| |
| See the description of @code{shopt} in @ref{The Shopt Builtin}, |
| for a description of the @code{nocaseglob}, @code{nullglob}, |
| @code{failglob}, and @code{dotglob} options. |
| |
| The @env{GLOBIGNORE} |
| shell variable may be used to restrict the set of filenames matching a |
| pattern. If @env{GLOBIGNORE} |
| is set, each matching filename that also matches one of the patterns in |
| @env{GLOBIGNORE} is removed from the list of matches. The filenames |
| @file{.} and @file{..} |
| are always ignored when @env{GLOBIGNORE} |
| is set and not null. |
| However, setting @env{GLOBIGNORE} to a non-null value has the effect of |
| enabling the @code{dotglob} |
| shell option, so all other filenames beginning with a |
| @samp{.} will match. |
| To get the old behavior of ignoring filenames beginning with a |
| @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}. |
| The @code{dotglob} option is disabled when @env{GLOBIGNORE} |
| is unset. |
| |
| @node Pattern Matching |
| @subsubsection Pattern Matching |
| @cindex pattern matching |
| @cindex matching, pattern |
| |
| Any character that appears in a pattern, other than the special pattern |
| characters described below, matches itself. |
| The @sc{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: |
| @table @code |
| @item * |
| Matches any string, including the null string. |
| When the @code{globstar} shell option is enabled, and @samp{*} is used in |
| a filename expansion context, two adjacent @samp{*}s used as a single |
| pattern will match all files and zero or more directories and |
| subdirectories. |
| If followed by a @samp{/}, two adjacent @samp{*}s will match only |
| directories and subdirectories. |
| @item ? |
| Matches any single character. |
| @item [@dots{}] |
| Matches any one of the enclosed characters. A pair of characters |
| separated by a hyphen denotes a @var{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 |
| @samp{[} is a @samp{!} or a @samp{^} |
| then any character not enclosed is matched. A @samp{@minus{}} |
| may be matched by including it as the first or last character |
| in the set. A @samp{]} 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 @env{LC_COLLATE} shell variable, |
| if set. |
| |
| For example, in the default C locale, @samp{[a-dx-z]} is equivalent to |
| @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in |
| these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; |
| it might be equivalent to @samp{[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 @env{LC_COLLATE} or |
| @env{LC_ALL} environment variable to the value @samp{C}. |
| |
| Within @samp{[} and @samp{]}, @var{character classes} can be specified |
| using the syntax |
| @code{[:}@var{class}@code{:]}, where @var{class} is one of the |
| following classes defined in the @sc{posix} standard: |
| @example |
| alnum alpha ascii blank cntrl digit graph lower |
| print punct space upper word xdigit |
| @end example |
| @noindent |
| A character class matches any character belonging to that class. |
| The @code{word} character class matches letters, digits, and the character |
| @samp{_}. |
| |
| Within @samp{[} and @samp{]}, an @var{equivalence class} can be |
| specified using the syntax @code{[=}@var{c}@code{=]}, which |
| matches all characters with the same collation weight (as defined |
| by the current locale) as the character @var{c}. |
| |
| Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]} |
| matches the collating symbol @var{symbol}. |
| @end table |
| |
| If the @code{extglob} shell option is enabled using the @code{shopt} |
| builtin, several extended pattern matching operators are recognized. |
| In the following description, a @var{pattern-list} is a list of one |
| or more patterns separated by a @samp{|}. |
| Composite patterns may be formed using one or more of the following |
| sub-patterns: |
| |
| @table @code |
| @item ?(@var{pattern-list}) |
| Matches zero or one occurrence of the given patterns. |
| |
| @item *(@var{pattern-list}) |
| Matches zero or more occurrences of the given patterns. |
| |
| @item +(@var{pattern-list}) |
| Matches one or more occurrences of the given patterns. |
| |
| @item @@(@var{pattern-list}) |
| Matches one of the given patterns. |
| |
| @item !(@var{pattern-list}) |
| Matches anything except one of the given patterns. |
| @end table |
| |
| @node Quote Removal |
| @subsection Quote Removal |
| |
| After the preceding expansions, all unquoted occurrences of the |
| characters @samp{\}, @samp{'}, and @samp{"} that did not |
| result from one of the above expansions are removed. |
| |
| @node Redirections |
| @section Redirections |
| @cindex redirection |
| |
| Before a command is executed, its input and output |
| may be @var{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. |
| |
| In the following descriptions, if the file descriptor number is |
| omitted, and the first character of the redirection operator is |
| @samp{<}, the redirection refers to the standard input (file |
| descriptor 0). If the first character of the redirection operator |
| is @samp{>}, 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 |
| @example |
| ls > @var{dirlist} 2>&1 |
| @end example |
| @noindent |
| directs both standard output (file descriptor 1) and standard error |
| (file descriptor 2) to the file @var{dirlist}, while the command |
| @example |
| ls 2>&1 > @var{dirlist} |
| @end example |
| @noindent |
| directs only the standard output to file @var{dirlist}, |
| because the standard error was made a copy of the standard output |
| before the standard output was redirected to @var{dirlist}. |
| |
| Bash handles several filenames specially when they are used in |
| redirections, as described in the following table: |
| |
| @table @code |
| @item /dev/fd/@var{fd} |
| If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated. |
| |
| @item /dev/stdin |
| File descriptor 0 is duplicated. |
| |
| @item /dev/stdout |
| File descriptor 1 is duplicated. |
| |
| @item /dev/stderr |
| File descriptor 2 is duplicated. |
| |
| @item /dev/tcp/@var{host}/@var{port} |
| If @var{host} is a valid hostname or Internet address, and @var{port} |
| is an integer port number or service name, Bash attempts to open a TCP |
| connection to the corresponding socket. |
| |
| @item /dev/udp/@var{host}/@var{port} |
| If @var{host} is a valid hostname or Internet address, and @var{port} |
| is an integer port number or service name, Bash attempts to open a UDP |
| connection to the corresponding socket. |
| |
| @end table |
| |
| 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. |
| |
| @subsection Redirecting Input |
| Redirection of input causes the file whose name results from |
| the expansion of @var{word} |
| to be opened for reading on file descriptor @code{n}, |
| or the standard input (file descriptor 0) if @code{n} |
| is not specified. |
| |
| The general format for redirecting input is: |
| @example |
| [@var{n}]<@var{word} |
| @end example |
| |
| @subsection Redirecting Output |
| Redirection of output causes the file whose name results from |
| the expansion of @var{word} |
| to be opened for writing on file descriptor @var{n}, |
| or the standard output (file descriptor 1) if @var{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: |
| @example |
| [@var{n}]>[|]@var{word} |
| @end example |
| |
| If the redirection operator is @samp{>}, and the @code{noclobber} |
| option to the @code{set} builtin has been enabled, the redirection |
| will fail if the file whose name results from the expansion of |
| @var{word} exists and is a regular file. |
| If the redirection operator is @samp{>|}, or the redirection operator is |
| @samp{>} and the @code{noclobber} option is not enabled, the redirection |
| is attempted even if the file named by @var{word} exists. |
| |
| @subsection Appending Redirected Output |
| Redirection of output in this fashion |
| causes the file whose name results from |
| the expansion of @var{word} |
| to be opened for appending on file descriptor @var{n}, |
| or the standard output (file descriptor 1) if @var{n} |
| is not specified. If the file does not exist it is created. |
| |
| The general format for appending output is: |
| @example |
| [@var{n}]>>@var{word} |
| @end example |
| |
| @subsection 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 @var{word}. |
| |
| There are two formats for redirecting standard output and |
| standard error: |
| @example |
| &>@var{word} |
| @end example |
| @noindent |
| and |
| @example |
| >&@var{word} |
| @end example |
| @noindent |
| Of the two forms, the first is preferred. |
| This is semantically equivalent to |
| @example |
| >@var{word} 2>&1 |
| @end example |
| |
| @subsection 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 @var{word}. |
| |
| The format for appending standard output and standard error is: |
| @example |
| &>>@var{word} |
| @end example |
| @noindent |
| This is semantically equivalent to |
| @example |
| >>@var{word} 2>&1 |
| @end example |
| |
| @subsection Here Documents |
| This type of redirection instructs the shell to read input from the |
| current source until a line containing only @var{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: |
| @example |
| <<[@minus{}]@var{word} |
| @var{here-document} |
| @var{delimiter} |
| @end example |
| |
| No parameter expansion, command substitution, arithmetic expansion, |
| or filename expansion is performed on |
| @var{word}. If any characters in @var{word} are quoted, the |
| @var{delimiter} is the result of quote removal on @var{word}, |
| and the lines in the here-document are not expanded. |
| If @var{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 @code{\newline} is ignored, and @samp{\} |
| must be used to quote the characters |
| @samp{\}, @samp{$}, and @samp{`}. |
| |
| If the redirection operator is @samp{<<-}, |
| then all leading tab characters are stripped from input lines and the |
| line containing @var{delimiter}. |
| This allows here-documents within shell scripts to be indented in a |
| natural fashion. |
| |
| @subsection Here Strings |
| A variant of here documents, the format is: |
| @example |
| <<< @var{word} |
| @end example |
| |
| The @var{word} is expanded and supplied to the command on its standard |
| input. |
| |
| @subsection Duplicating File Descriptors |
| The redirection operator |
| @example |
| [@var{n}]<&@var{word} |
| @end example |
| @noindent |
| is used to duplicate input file descriptors. |
| If @var{word} |
| expands to one or more digits, the file descriptor denoted by @var{n} |
| is made to be a copy of that file descriptor. |
| If the digits in @var{word} do not specify a file descriptor open for |
| input, a redirection error occurs. |
| If @var{word} |
| evaluates to @samp{-}, file descriptor @var{n} is closed. If |
| @var{n} is not specified, the standard input (file descriptor 0) is used. |
| |
| The operator |
| @example |
| [@var{n}]>&@var{word} |
| @end example |
| @noindent |
| is used similarly to duplicate output file descriptors. If |
| @var{n} is not specified, the standard output (file descriptor 1) is used. |
| If the digits in @var{word} do not specify a file descriptor open for |
| output, a redirection error occurs. |
| As a special case, if @var{n} is omitted, and @var{word} does not |
| expand to one or more digits, the standard output and standard |
| error are redirected as described previously. |
| |
| @subsection Moving File Descriptors |
| The redirection operator |
| @example |
| [@var{n}]<&@var{digit}- |
| @end example |
| @noindent |
| moves the file descriptor @var{digit} to file descriptor @var{n}, |
| or the standard input (file descriptor 0) if @var{n} is not specified. |
| @var{digit} is closed after being duplicated to @var{n}. |
| |
| Similarly, the redirection operator |
| @example |
| [@var{n}]>&@var{digit}- |
| @end example |
| @noindent |
| moves the file descriptor @var{digit} to file descriptor @var{n}, |
| or the standard output (file descriptor 1) if @var{n} is not specified. |
| |
| @subsection Opening File Descriptors for Reading and Writing |
| The redirection operator |
| @example |
| [@var{n}]<>@var{word} |
| @end example |
| @noindent |
| causes the file whose name is the expansion of @var{word} |
| to be opened for both reading and writing on file descriptor |
| @var{n}, or on file descriptor 0 if @var{n} |
| is not specified. If the file does not exist, it is created. |
| |
| @node Executing Commands |
| @section 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. |
| @end menu |
| |
| @node Simple Command Expansion |
| @subsection Simple Command Expansion |
| @cindex command expansion |
| |
| When a simple command is executed, the shell performs the following |
| expansions, assignments, and redirections, from left to right. |
| |
| @enumerate |
| @item |
| The words that the parser has marked as variable assignments (those |
| preceding the command name) and redirections are saved for later |
| processing. |
| |
| @item |
| The words that are not variable assignments or redirections are |
| expanded (@pxref{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. |
| |
| @item |
| Redirections are performed as described above (@pxref{Redirections}). |
| |
| @item |
| The text after the @samp{=} in each variable assignment undergoes tilde |
| expansion, parameter expansion, command substitution, arithmetic expansion, |
| and quote removal before being assigned to the variable. |
| @end enumerate |
| |
| 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. |
| |
| @node Command Search and Execution |
| @subsection Command Search and Execution |
| @cindex command execution |
| @cindex command search |
| |
| 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. |
| |
| @enumerate |
| @item |
| 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 @ref{Shell Functions}. |
| |
| @item |
| 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. |
| |
| @item |
| If the name is neither a shell function nor a builtin, |
| and contains no slashes, Bash searches each element of |
| @env{$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 @env{PATH} searches |
| (see the description of @code{hash} in @ref{Bourne Shell Builtins}). |
| A full search of the directories in @env{$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 @code{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. |
| |
| @item |
| 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. |
| |
| @item |
| 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 |
| @var{shell script} and the shell executes it as described in |
| @ref{Shell Scripts}. |
| |
| @item |
| If the command was not begun asynchronously, the shell waits for |
| the command to complete and collects its exit status. |
| |
| @end enumerate |
| |
| @node Command Execution Environment |
| @subsection Command Execution Environment |
| @cindex execution environment |
| |
| The shell has an @var{execution environment}, which consists of the |
| following: |
| |
| @itemize @bullet |
| @item |
| open files inherited by the shell at invocation, as modified by |
| redirections supplied to the @code{exec} builtin |
| |
| @item |
| the current working directory as set by @code{cd}, @code{pushd}, or |
| @code{popd}, or inherited by the shell at invocation |
| |
| @item |
| the file creation mode mask as set by @code{umask} or inherited from |
| the shell's parent |
| |
| @item |
| current traps set by @code{trap} |
| |
| @item |
| shell parameters that are set by variable assignment or with @code{set} |
| or inherited from the shell's parent in the environment |
| |
| @item |
| shell functions defined during execution or inherited from the shell's |
| parent in the environment |
| |
| @item |
| options enabled at invocation (either by default or with command-line |
| arguments) or by @code{set} |
| |
| @item |
| options enabled by @code{shopt} (@pxref{The Shopt Builtin}) |
| |
| @item |
| shell aliases defined with @code{alias} (@pxref{Aliases}) |
| |
| @item |
| various process @sc{id}s, including those of background jobs |
| (@pxref{Lists}), the value of @code{$$}, and the value of |
| @env{$PPID} |
| |
| @end itemize |
| |
| 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. |
| |
| @itemize @bullet |
| @item |
| the shell's open files, plus any modifications and additions specified |
| by redirections to the command |
| |
| @item |
| the current working directory |
| |
| @item |
| the file creation mode mask |
| |
| @item |
| shell variables and functions marked for export, along with variables |
| exported for the command, passed in the environment (@pxref{Environment}) |
| |
| @item |
| traps caught by the shell are reset to the values inherited from the |
| shell's parent, and traps ignored by the shell are ignored |
| |
| @end itemize |
| |
| 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 @option{-e} option from the parent shell. When not in @sc{posix} mode, |
| Bash clears the @option{-e} option in such subshells. |
| |
| If a command is followed by a @samp{&} and job control is not active, the |
| default standard input for the command is the empty file @file{/dev/null}. |
| Otherwise, the invoked command inherits the file descriptors of the calling |
| shell as modified by redirections. |
| |
| @node Environment |
| @subsection Environment |
| @cindex environment |
| |
| When a program is invoked it is given an array of strings |
| called the @var{environment}. |
| This is a list of name-value pairs, of the form @code{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 @var{export} |
| to child processes. Executed commands inherit the environment. |
| The @code{export} and @samp{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 @code{unset} and @samp{export -n} |
| commands, plus any additions via the @code{export} and |
| @samp{declare -x} commands. |
| |
| The environment for any simple command |
| or function may be augmented temporarily by prefixing it with |
| parameter assignments, as described in @ref{Shell Parameters}. |
| These assignment statements affect only the environment seen |
| by that command. |
| |
| If the @option{-k} option is set (@pxref{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 @samp{$_} |
| is set to the full path name of the command and passed to that |
| command in its environment. |
| |
| @node Exit Status |
| @subsection Exit Status |
| @cindex exit status |
| |
| The exit status of an executed command is the value returned by the |
| @var{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 @var{N}, |
| Bash uses the value 128+@var{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 |
| (@pxref{Conditional Constructs}) and some of the list |
| constructs (@pxref{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. |
| |
| @node Signals |
| @subsection Signals |
| @cindex signal handling |
| |
| When Bash is interactive, in the absence of any traps, it ignores |
| @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), |
| and @code{SIGINT} |
| is caught and handled (so that the @code{wait} builtin is interruptible). |
| When Bash receives a @code{SIGINT}, it breaks out of any executing loops. |
| In all cases, Bash ignores @code{SIGQUIT}. |
| If job control is in effect (@pxref{Job Control}), Bash |
| ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{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 @code{SIGINT} and @code{SIGQUIT} in addition to these inherited |
| handlers. |
| Commands run as a result of |
| command substitution ignore the keyboard-generated job control signals |
| @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. |
| |
| The shell exits by default upon receipt of a @code{SIGHUP}. |
| Before exiting, an interactive shell resends the @code{SIGHUP} to |
| all jobs, running or stopped. |
| Stopped jobs are sent @code{SIGCONT} to ensure that they receive |
| the @code{SIGHUP}. |
| To prevent the shell from sending the @code{SIGHUP} signal to a |
| particular job, it should be removed |
| from the jobs table with the @code{disown} |
| builtin (@pxref{Job Control Builtins}) or marked |
| to not receive @code{SIGHUP} using @code{disown -h}. |
| |
| If the @code{huponexit} shell option has been set with @code{shopt} |
| (@pxref{The Shopt Builtin}), Bash sends a @code{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 @code{wait} builtin, the reception of a signal for |
| which a trap has been set will cause the @code{wait} builtin to return |
| immediately with an exit status greater than 128, immediately after |
| which the trap is executed. |
| |
| @node Shell Scripts |
| @section Shell Scripts |
| @cindex shell script |
| |
| 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 @option{-c} nor @option{-s} option is supplied |
| (@pxref{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 @env{$PATH} if not found there. |
| |
| When Bash runs |
| a shell script, it sets the special parameter @code{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 @code{chmod} command |
| to turn on the execute bit. When Bash finds such a file while |
| searching the @env{$PATH} for a command, it spawns a subshell to |
| execute it. In other words, executing |
| @example |
| filename @var{arguments} |
| @end example |
| @noindent |
| is equivalent to executing |
| @example |
| bash filename @var{arguments} |
| @end example |
| |
| @noindent |
| if @code{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 @code{hash} in @ref{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 @samp{#!}, the remainder of the line specifies |
| an interpreter for the program. |
| Thus, you can specify Bash, @code{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 @code{#! /bin/bash} (assuming that |
| Bash has been installed in @file{/bin}), since this ensures that |
| Bash will be used to interpret the script, even if it is executed |
| under another shell. |
| |
| @node Shell Builtin Commands |
| @chapter 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. |
| @end menu |
| |
| 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 (@pxref{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 (@pxref{Job Control Builtins}), the directory stack |
| (@pxref{Directory Stack Builtins}), the command history |
| (@pxref{Bash History Builtins}), and the programmable completion |
| facilities (@pxref{Programmable Completion Builtins}). |
| |
| Many of the builtins have been extended by @sc{posix} or Bash. |
| |
| Unless otherwise noted, each builtin command documented as accepting |
| options preceded by @samp{-} accepts @samp{--} |
| to signify the end of the options. |
| For example, the @code{:}, @code{true}, @code{false}, and @code{test} |
| builtins do not accept options. |
| |
| @node Bourne Shell Builtins |
| @section Bourne Shell Builtins |
| |
| The following shell builtin commands are inherited from the Bourne Shell. |
| These commands are implemented as specified by the @sc{posix} standard. |
| |
| @table @code |
| @item : @r{(a colon)} |
| @btindex : |
| @example |
| : [@var{arguments}] |
| @end example |
| Do nothing beyond expanding @var{arguments} and performing redirections. |
| The return status is zero. |
| |
| @item . @r{(a period)} |
| @btindex . |
| @example |
| . @var{filename} [@var{arguments}] |
| @end example |
| Read and execute commands from the @var{filename} argument in the |
| current shell context. If @var{filename} does not contain a slash, |
| the @env{PATH} variable is used to find @var{filename}. |
| When Bash is not in @sc{posix} mode, the current directory is searched |
| if @var{filename} is not found in @env{$PATH}. |
| If any @var{arguments} are supplied, they become the positional |
| parameters when @var{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 @var{filename} is not found, or |
| cannot be read, the return status is non-zero. |
| This builtin is equivalent to @code{source}. |
| |
| @item break |
| @btindex break |
| @example |
| break [@var{n}] |
| @end example |
| Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. |
| If @var{n} is supplied, the @var{n}th enclosing loop is exited. |
| @var{n} must be greater than or equal to 1. |
| The return status is zero unless @var{n} is not greater than or equal to 1. |
| |
| @item cd |
| @btindex cd |
| @example |
| cd [-L|-P] [@var{directory}] |
| @end example |
| Change the current working directory to @var{directory}. |
| If @var{directory} is not given, the value of the @env{HOME} shell |
| variable is used. |
| If the shell variable @env{CDPATH} exists, it is used as a search path. |
| If @var{directory} begins with a slash, @env{CDPATH} is not used. |
| |
| The @option{-P} option means to not follow symbolic links; symbolic |
| links are followed by default or with the @option{-L} option. |
| If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}. |
| |
| If a non-empty directory name from @env{CDPATH} is used, or if |
| @samp{-} 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. |
| |
| @item continue |
| @btindex continue |
| @example |
| continue [@var{n}] |
| @end example |
| Resume the next iteration of an enclosing @code{for}, @code{while}, |
| @code{until}, or @code{select} loop. |
| If @var{n} is supplied, the execution of the @var{n}th enclosing loop |
| is resumed. |
| @var{n} must be greater than or equal to 1. |
| The return status is zero unless @var{n} is not greater than or equal to 1. |
| |
| @item eval |
| @btindex eval |
| @example |
| eval [@var{arguments}] |
| @end example |
| 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 @code{eval}. |
| If there are no arguments or only empty arguments, the return status is |
| zero. |
| |
| @item exec |
| @btindex exec |
| @example |
| exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]] |
| @end example |
| If @var{command} |
| is supplied, it replaces the shell without creating a new process. |
| If the @option{-l} option is supplied, the shell places a dash at the |
| beginning of the zeroth argument passed to @var{command}. |
| This is what the @code{login} program does. |
| The @option{-c} option causes @var{command} to be executed with an empty |
| environment. |
| If @option{-a} is supplied, the shell passes @var{name} as the zeroth |
| argument to @var{command}. |
| If no @var{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. |
| |
| @item exit |
| @btindex exit |
| @example |
| exit [@var{n}] |
| @end example |
| Exit the shell, returning a status of @var{n} to the shell's parent. |
| If @var{n} is omitted, the exit status is that of the last command executed. |
| Any trap on @code{EXIT} is executed before the shell terminates. |
| |
| @item export |
| @btindex export |
| @example |
| export [-fn] [-p] [@var{name}[=@var{value}]] |
| @end example |
| Mark each @var{name} to be passed to child processes |
| in the environment. If the @option{-f} option is supplied, the @var{name}s |
| refer to shell functions; otherwise the names refer to shell variables. |
| The @option{-n} option means to no longer mark each @var{name} for export. |
| If no @var{names} are supplied, or if the @option{-p} option is given, a |
| list of exported names is displayed. |
| The @option{-p} option displays output in a form that may be reused as input. |
| If a variable name is followed by =@var{value}, the value of |
| the variable is set to @var{value}. |
| |
| The return status is zero unless an invalid option is supplied, one of |
| the names is not a valid shell variable name, or @option{-f} is supplied |
| with a name that is not a shell function. |
| |
| @item getopts |
| @btindex getopts |
| @example |
| getopts @var{optstring} @var{name} [@var{args}] |
| @end example |
| @code{getopts} is used by shell scripts to parse positional parameters. |
| @var{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 (@samp{:}) and question mark (@samp{?}) may not be |
| used as option characters. |
| Each time it is invoked, @code{getopts} |
| places the next option in the shell variable @var{name}, initializing |
| @var{name} if it does not exist, |
| and the index of the next argument to be processed into the |
| variable @env{OPTIND}. |
| @env{OPTIND} is initialized to 1 each time the shell or a shell script |
| is invoked. |
| When an option requires an argument, |
| @code{getopts} places that argument into the variable @env{OPTARG}. |
| The shell does not reset @env{OPTIND} automatically; it must be manually |
| reset between multiple calls to @code{getopts} within the same shell |
| invocation if a new set of parameters is to be used. |
| |
| When the end of options is encountered, @code{getopts} exits with a |
| return value greater than zero. |
| @env{OPTIND} is set to the index of the first non-option argument, |
| and @code{name} is set to @samp{?}. |
| |
| @code{getopts} |
| normally parses the positional parameters, but if more arguments are |
| given in @var{args}, @code{getopts} parses those instead. |
| |
| @code{getopts} can report errors in two ways. If the first character of |
| @var{optstring} is a colon, @var{silent} |
| error reporting is used. In normal operation diagnostic messages |
| are printed when invalid options or missing option arguments are |
| encountered. |
| If the variable @env{OPTERR} |
| is set to 0, no error messages will be displayed, even if the first |
| character of @code{optstring} is not a colon. |
| |
| If an invalid option is seen, |
| @code{getopts} places @samp{?} into @var{name} and, if not silent, |
| prints an error message and unsets @env{OPTARG}. |
| If @code{getopts} is silent, the option character found is placed in |
| @env{OPTARG} and no diagnostic message is printed. |
| |
| If a required argument is not found, and @code{getopts} |
| is not silent, a question mark (@samp{?}) is placed in @var{name}, |
| @code{OPTARG} is unset, and a diagnostic message is printed. |
| If @code{getopts} is silent, then a colon (@samp{:}) is placed in |
| @var{name} and @env{OPTARG} is set to the option character found. |
| |
| @item hash |
| @btindex hash |
| @example |
| hash [-r] [-p @var{filename}] [-dt] [@var{name}] |
| @end example |
| Remember the full pathnames of commands specified as @var{name} arguments, |
| so they need not be searched for on subsequent invocations. |
| The commands are found by searching through the directories listed in |
| @env{$PATH}. |
| The @option{-p} option inhibits the path search, and @var{filename} is |
| used as the location of @var{name}. |
| The @option{-r} option causes the shell to forget all remembered locations. |
| The @option{-d} option causes the shell to forget the remembered location |
| of each @var{name}. |
| If the @option{-t} option is supplied, the full pathname to which each |
| @var{name} corresponds is printed. If multiple @var{name} arguments are |
| supplied with @option{-t} the @var{name} is printed before the hashed |
| full pathname. |
| The @option{-l} option causes output to be displayed in a format |
| that may be reused as input. |
| If no arguments are given, or if only @option{-l} is supplied, |
| information about remembered commands is printed. |
| The return status is zero unless a @var{name} is not found or an invalid |
| option is supplied. |
| |
| @item pwd |
| @btindex pwd |
| @example |
| pwd [-LP] |
| @end example |
| Print the absolute pathname of the current working directory. |
| If the @option{-P} option is supplied, the pathname printed will not |
| contain symbolic links. |
| If the @option{-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. |
| |
| @item readonly |
| @btindex readonly |
| @example |
| readonly [-aApf] [@var{name}[=@var{value}]] @dots{} |
| @end example |
| Mark each @var{name} as readonly. |
| The values of these names may not be changed by subsequent assignment. |
| If the @option{-f} option is supplied, each @var{name} refers to a shell |
| function. |
| The @option{-a} option means each @var{name} refers to an indexed |
| array variable; the @option{-A} option means each @var{name} refers |
| to an associative array variable. |
| If no @var{name} arguments are given, or if the @option{-p} |
| option is supplied, a list of all readonly names is printed. |
| The @option{-p} option causes output to be displayed in a format that |
| may be reused as input. |
| If a variable name is followed by =@var{value}, the value of |
| the variable is set to @var{value}. |
| The return status is zero unless an invalid option is supplied, one of |
| the @var{name} arguments is not a valid shell variable or function name, |
| or the @option{-f} option is supplied with a name that is not a shell function. |
| |
| @item return |
| @btindex return |
| @example |
| return [@var{n}] |
| @end example |
| Cause a shell function to exit with the return value @var{n}. |
| If @var{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 @code{.} (or @code{source}) builtin, returning either @var{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 @code{RETURN} trap is executed |
| before execution resumes after the function or script. |
| The return status is non-zero if @code{return} is used outside a function |
| and not during the execution of a script by @code{.} or @code{source}. |
| |
| @item shift |
| @btindex shift |
| @example |
| shift [@var{n}] |
| @end example |
| Shift the positional parameters to the left by @var{n}. |
| The positional parameters from @var{n}+1 @dots{} @code{$#} are |
| renamed to @code{$1} @dots{} @code{$#}-@var{n}. |
| Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1 |
| are unset. |
| @var{n} must be a non-negative number less than or equal to @code{$#}. |
| If @var{n} is zero or greater than @code{$#}, the positional parameters |
| are not changed. |
| If @var{n} is not supplied, it is assumed to be 1. |
| The return status is zero unless @var{n} is greater than @code{$#} or |
| less than zero, non-zero otherwise. |
| |
| @item test |
| @itemx [ |
| @btindex test |
| @btindex [ |
| Evaluate a conditional expression @var{expr}. |
| Each operator and operand must be a separate argument. |
| Expressions are composed of the primaries described below in |
| @ref{Bash Conditional Expressions}. |
| @code{test} does not accept any options, nor does it accept and ignore |
| an argument of @option{--} as signifying the end of options. |
| |
| When the @code{[} form is used, the last argument to the command must |
| be a @code{]}. |
| |
| Expressions may be combined using the following operators, listed in |
| decreasing order of precedence. |
| The evaluation depends on the number of arguments; see below. |
| |
| @table @code |
| @item ! @var{expr} |
| True if @var{expr} is false. |
| |
| @item ( @var{expr} ) |
| Returns the value of @var{expr}. |
| This may be used to override the normal precedence of operators. |
| |
| @item @var{expr1} -a @var{expr2} |
| True if both @var{expr1} and @var{expr2} are true. |
| |
| @item @var{expr1} -o @var{expr2} |
| True if either @var{expr1} or @var{expr2} is true. |
| @end table |
| |
| The @code{test} and @code{[} builtins evaluate conditional |
| expressions using a set of rules based on the number of arguments. |
| |
| @table @asis |
| @item 0 arguments |
| The expression is false. |
| |
| @item 1 argument |
| The expression is true if and only if the argument is not null. |
| |
| @item 2 arguments |
| If the first argument is @samp{!}, the expression is true if and |
| only if the second argument is null. |
| If the first argument is one of the unary conditional operators |
| (@pxref{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. |
| |
| @item 3 arguments |
| If the second argument is one of the binary conditional |
| operators (@pxref{Bash Conditional Expressions}), the |
| result of the expression is the result of the binary test using the |
| first and third arguments as operands. |
| The @samp{-a} and @samp{-o} operators are considered binary operators |
| when there are three arguments. |
| If the first argument is @samp{!}, the value is the negation of |
| the two-argument test using the second and third arguments. |
| If the first argument is exactly @samp{(} and the third argument is |
| exactly @samp{)}, the result is the one-argument test of the second |
| argument. |
| Otherwise, the expression is false. |
| |
| @item 4 arguments |
| If the first argument is @samp{!}, 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. |
| |
| @item 5 or more arguments |
| The expression is parsed and evaluated according to precedence |
| using the rules listed above. |
| @end table |
| |
| @item times |
| @btindex times |
| @example |
| times |
| @end example |
| Print out the user and system times used by the shell and its children. |
| The return status is zero. |
| |
| @item trap |
| @btindex trap |
| @example |
| trap [-lp] [@var{arg}] [@var{sigspec} @dots{}] |
| @end example |
| The commands in @var{arg} are to be read and executed when the |
| shell receives signal @var{sigspec}. If @var{arg} is absent (and |
| there is a single @var{sigspec}) or |
| equal to @samp{-}, each specified signal's disposition is reset |
| to the value it had when the shell was started. |
| If @var{arg} is the null string, then the signal specified by |
| each @var{sigspec} is ignored by the shell and commands it invokes. |
| If @var{arg} is not present and @option{-p} has been supplied, |
| the shell displays the trap commands associated with each @var{sigspec}. |
| If no arguments are supplied, or |
| only @option{-p} is given, @code{trap} prints the list of commands |
| associated with each signal number in a form that may be reused as |
| shell input. |
| The @option{-l} option causes the shell to print a list of signal names |
| and their corresponding numbers. |
| Each @var{sigspec} is either a signal name or a signal number. |
| Signal names are case insensitive and the @code{SIG} prefix is optional. |
| If a @var{sigspec} |
| is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. |
| If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed |
| before every simple command, @code{for} command, @code{case} command, |
| @code{select} command, every arithmetic @code{for} command, and before |
| the first command executes in a shell function. |
| Refer to the description of the @code{extglob} option to the |
| @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its |
| effect on the @code{DEBUG} trap. |
| If a @var{sigspec} is @code{ERR}, the command @var{arg} |
| is executed whenever a simple command has a non-zero exit status, |
| subject to the following conditions. |
| The @code{ERR} trap is not executed if the failed command is part of the |
| command list immediately following an @code{until} or @code{while} keyword, |
| part of the test following the @code{if} or @code{elif} reserved words, |
| part of a command executed in a @code{&&} or @code{||} list, |
| or if the command's return |
| status is being inverted using @code{!}. |
| These are the same conditions obeyed by the @code{errexit} option. |
| If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed |
| each time a shell function or a script executed with the @code{.} or |
| @code{source} builtins finishes executing. |
| |
| 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 child process when it is created. |
| |
| The return status is zero unless a @var{sigspec} does not specify a |
| valid signal. |
| |
| @item umask |
| @btindex umask |
| @example |
| umask [-p] [-S] [@var{mode}] |
| @end example |
| Set the shell process's file creation mask to @var{mode}. If |
| @var{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 @code{chmod} command. If @var{mode} is |
| omitted, the current value of the mask is printed. If the @option{-S} |
| option is supplied without a @var{mode} argument, the mask is printed |
| in a symbolic format. |
| If the @option{-p} option is supplied, and @var{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 @var{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 @code{7}. Thus, a umask of @code{022} |
| results in permissions of @code{755}. |
| |
| @item unset |
| @btindex unset |
| @example |
| unset [-fv] [@var{name}] |
| @end example |
| Each variable or function @var{name} is removed. |
| If no options are supplied, or the @option{-v} option is given, each |
| @var{name} refers to a shell variable. |
| If the @option{-f} option is given, the @var{name}s 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 @var{name} is readonly. |
| @end table |
| |
| @node Bash Builtins |
| @section 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 @sc{posix} standard. |
| |
| @table @code |
| |
| @item alias |
| @btindex alias |
| @example |
| alias [@code{-p}] [@var{name}[=@var{value}] @dots{}] |
| @end example |
| |
| Without arguments or with the @option{-p} option, @code{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 @var{name} |
| whose @var{value} is given. If no @var{value} is given, the name |
| and value of the alias is printed. |
| Aliases are described in @ref{Aliases}. |
| |
| @item bind |
| @btindex bind |
| @example |
| bind [-m @var{keymap}] [-lpsvPSV] |
| bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}] |
| bind [-m @var{keymap}] -f @var{filename} |
| bind [-m @var{keymap}] -x @var{keyseq:shell-command} |
| bind [-m @var{keymap}] @var{keyseq:function-name} |
| bind @var{readline-command} |
| @end example |
| |
| Display current Readline (@pxref{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 (@pxref{Readline Init File}), |
| but each binding or command must be passed as a separate argument; e.g., |
| @samp{"\C-x\C-r":re-read-init-file}. |
| |
| Options, if supplied, have the following meanings: |
| |
| @table @code |
| @item -m @var{keymap} |
| Use @var{keymap} as the keymap to be affected by |
| the subsequent bindings. Acceptable @var{keymap} |
| names are |
| @code{emacs}, |
| @code{emacs-standard}, |
| @code{emacs-meta}, |
| @code{emacs-ctlx}, |
| @code{vi}, |
| @code{vi-move}, |
| @code{vi-command}, and |
| @code{vi-insert}. |
| @code{vi} is equivalent to @code{vi-command}; |
| @code{emacs} is equivalent to @code{emacs-standard}. |
| |
| @item -l |
| List the names of all Readline functions. |
| |
| @item -p |
| Display Readline function names and bindings in such a way that they |
| can be used as input or in a Readline initialization file. |
| |
| @item -P |
| List current Readline function names and bindings. |
| |
| @item -v |
| Display Readline variable names and values in such a way that they |
| can be used as input or in a Readline initialization file. |
| |
| @item -V |
| List current Readline variable names and values. |
| |
| @item -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. |
| |
| @item -S |
| Display Readline key sequences bound to macros and the strings they output. |
| |
| @item -f @var{filename} |
| Read key bindings from @var{filename}. |
| |
| @item -q @var{function} |
| Query about which keys invoke the named @var{function}. |
| |
| @item -u @var{function} |
| Unbind all keys bound to the named @var{function}. |
| |
| @item -r @var{keyseq} |
| Remove any current binding for @var{keyseq}. |
| |
| @item -x @var{keyseq:shell-command} |
| Cause @var{shell-command} to be executed whenever @var{keyseq} is |
| entered. |
| When @var{shell-command} is executed, the shell sets the |
| @code{READLINE_LINE} variable to the contents of the Readline line |
| buffer and the @code{READLINE_POINT} variable to the current location |
| of the insertion point. |
| If the executed command changes the value of @code{READLINE_LINE} or |
| @code{READLINE_POINT}, those new values will be reflected in the |
| editing state. |
| @end table |
| |
| @noindent |
| The return status is zero unless an invalid option is supplied or an |
| error occurs. |
| |
| @item builtin |
| @btindex builtin |
| @example |
| builtin [@var{shell-builtin} [@var{args}]] |
| @end example |
| Run a shell builtin, passing it @var{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 @var{shell-builtin} is not a shell |
| builtin command. |
| |
| @item caller |
| @btindex caller |
| @example |
| caller [@var{expr}] |
| @end example |
| Returns the context of any active subroutine call (a shell function or |
| a script executed with the @code{.} or @code{source} builtins). |
| |
| Without @var{expr}, @code{caller} displays the line number and source |
| filename of the current subroutine call. |
| If a non-negative integer is supplied as @var{expr}, @code{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 @var{expr} does not correspond to a valid position in the |
| call stack. |
| |
| @item command |
| @btindex command |
| @example |
| command [-pVv] @var{command} [@var{arguments} @dots{}] |
| @end example |
| Runs @var{command} with @var{arguments} ignoring any shell function |
| named @var{command}. |
| Only shell builtin commands or commands found by searching the |
| @env{PATH} are executed. |
| If there is a shell function named @code{ls}, running @samp{command ls} |
| within the function will execute the external command @code{ls} |
| instead of calling the function recursively. |
| The @option{-p} option means to use a default value for @env{PATH} |
| that is guaranteed to find all of the standard utilities. |
| The return status in this case is 127 if @var{command} cannot be |
| found or an error occurred, and the exit status of @var{command} |
| otherwise. |
| |
| If either the @option{-V} or @option{-v} option is supplied, a |
| description of @var{command} is printed. The @option{-v} option |
| causes a single word indicating the command or file name used to |
| invoke @var{command} to be displayed; the @option{-V} option produces |
| a more verbose description. In this case, the return status is |
| zero if @var{command} is found, and non-zero if not. |
| |
| @item declare |
| @btindex declare |
| @example |
| declare [-aAfFilrtux] [-p] [@var{name}[=@var{value}] @dots{}] |
| @end example |
| |
| Declare variables and give them attributes. If no @var{name}s |
| are given, then display the values of variables instead. |
| |
| The @option{-p} option will display the attributes and values of each |
| @var{name}. |
| When @option{-p} is used with @var{name} arguments, additional options |
| are ignored. |
| |
| When @option{-p} is supplied without @var{name} arguments, @code{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 @option{-p}, @code{declare} will |
| display the attributes and values of all shell variables. The @option{-f} |
| option will restrict the display to shell functions. |
| |
| The @option{-F} option inhibits the display of function definitions; |
| only the function name and attributes are printed. |
| If the @code{extdebug} shell option is enabled using @code{shopt} |
| (@pxref{The Shopt Builtin}), the source file name and line number where |
| the function is defined are displayed as well. |
| @option{-F} implies @option{-f}. |
| The following options can be used to restrict output to variables with |
| the specified attributes or to give variables attributes: |
| |
| @table @code |
| @item -a |
| Each @var{name} is an indexed array variable (@pxref{Arrays}). |
| |
| @item -A |
| Each @var{name} is an associative array variable (@pxref{Arrays}). |
| |
| @item -f |
| Use function names only. |
| |
| @item -i |
| The variable is to be treated as |
| an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is |
| performed when the variable is assigned a value. |
| |
| @item -l |
| When the variable is assigned a value, all upper-case characters are |
| converted to lower-case. |
| The upper-case attribute is disabled. |
| |
| @item -r |
| Make @var{name}s readonly. These names cannot then be assigned values |
| by subsequent assignment statements or unset. |
| |
| @item -t |
| Give each @var{name} the @code{trace} attribute. |
| Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from |
| the calling shell. |
| The trace attribute has no special meaning for variables. |
| |
| @item -u |
| When the variable is assigned a value, all lower-case characters are |
| converted to upper-case. |
| The lower-case attribute is disabled. |
| |
| @item -x |
| Mark each @var{name} for export to subsequent commands via |
| the environment. |
| @end table |
| |
| Using @samp{+} instead of @samp{-} turns off the attribute instead, |
| with the exceptions that @samp{+a} |
| may not be used to destroy an array variable and @samp{+r} will not |
| remove the readonly attribute. |
| When used in a function, @code{declare} makes each @var{name} local, |
| as with the @code{local} command. If a variable name is followed by |
| =@var{value}, the value of the variable is set to @var{value}. |
| |
| The return status is zero unless an invalid option is encountered, |
| an attempt is made to define a function using @samp{-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 (@pxref{Arrays}), |
| one of the @var{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 @option{-f}. |
| |
| @item echo |
| @btindex echo |
| @example |
| echo [-neE] [@var{arg} @dots{}] |
| @end example |
| Output the @var{arg}s, separated by spaces, terminated with a |
| newline. |
| The return status is always 0. |
| If @option{-n} is specified, the trailing newline is suppressed. |
| If the @option{-e} option is given, interpretation of the following |
| backslash-escaped characters is enabled. |
| The @option{-E} option disables the interpretation of these escape characters, |
| even on systems where they are interpreted by default. |
| The @code{xpg_echo} shell option may be used to |
| dynamically determine whether or not @code{echo} expands these |
| escape characters by default. |
| @code{echo} does not interpret @option{--} to mean the end of options. |
| |
| @code{echo} interprets the following escape sequences: |
| @table @code |
| @item \a |
| alert (bell) |
| @item \b |
| backspace |
| @item \c |
| suppress further output |
| @item \e |
| escape |
| @item \f |
| form feed |
| @item \n |
| new line |
| @item \r |
| carriage return |
| @item \t |
| horizontal tab |
| @item \v |
| vertical tab |
| @item \\ |
| backslash |
| @item \0@var{nnn} |
| the eight-bit character whose value is the octal value @var{nnn} |
| (zero to three octal digits) |
| @item \x@var{HH} |
| the eight-bit character whose value is the hexadecimal value @var{HH} |
| (one or two hex digits) |
| @end table |
| |
| @item enable |
| @btindex enable |
| @example |
| enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}] |
| @end example |
| 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 @option{-n} is used, the @var{name}s become disabled. Otherwise |
| @var{name}s are enabled. For example, to use the @code{test} binary |
| found via @env{$PATH} instead of the shell builtin version, type |
| @samp{enable -n test}. |
| |
| If the @option{-p} option is supplied, or no @var{name} arguments appear, |
| a list of shell builtins is printed. With no other arguments, the list |
| consists of all enabled shell builtins. |
| The @option{-a} option means to list |
| each builtin with an indication of whether or not it is enabled. |
| |
| The @option{-f} option means to load the new builtin command @var{name} |
| from shared object @var{filename}, on systems that support dynamic loading. |
| The @option{-d} option will delete a builtin loaded with @option{-f}. |
| |
| If there are no options, a list of the shell builtins is displayed. |
| The @option{-s} option restricts @code{enable} to the @sc{posix} special |
| builtins. If @option{-s} is used with @option{-f}, the new builtin becomes |
| a special builtin (@pxref{Special Builtins}). |
| |
| The return status is zero unless a @var{name} is not a shell builtin |
| or there is an error loading a new builtin from a shared object. |
| |
| @item help |
| @btindex help |
| @example |
| help [-dms] [@var{pattern}] |
| @end example |
| Display helpful information about builtin commands. |
| If @var{pattern} is specified, @code{help} gives detailed help |
| on all commands matching @var{pattern}, otherwise a list of |
| the builtins is printed. |
| |
| Options, if supplied, have the following meanings: |
| |
| @table @code |
| @item -d |
| Display a short description of each @var{pattern} |
| @item -m |
| Display the description of each @var{pattern} in a manpage-like format |
| @item -s |
| Display only a short usage synopsis for each @var{pattern} |
| @end table |
| |
| The return status is zero unless no command matches @var{pattern}. |
| |
| @item let |
| @btindex let |
| @example |
| let @var{expression} [@var{expression}] |
| @end example |
| The @code{let} builtin allows arithmetic to be performed on shell |
| variables. Each @var{expression} is evaluated according to the |
| rules given below in @ref{Shell Arithmetic}. If the |
| last @var{expression} evaluates to 0, @code{let} returns 1; |
| otherwise 0 is returned. |
| |
| @item local |
| @btindex local |
| @example |
| local [@var{option}] @var{name}[=@var{value}] @dots{} |
| @end example |
| For each argument, a local variable named @var{name} is created, |
| and assigned @var{value}. |
| The @var{option} can be any of the options accepted by @code{declare}. |
| @code{local} can only be used within a function; it makes the variable |
| @var{name} have a visible scope restricted to that function and its |
| children. The return status is zero unless @code{local} is used outside |
| a function, an invalid @var{name} is supplied, or @var{name} is a |
| readonly variable. |
| |
| @item logout |
| @btindex logout |
| @example |
| logout [@var{n}] |
| @end example |
| Exit a login shell, returning a status of @var{n} to the shell's |
| parent. |
| |
| @item mapfile |
| @btindex mapfile |
| @example |
| mapfile [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [ |
| -C @var{callback}] [-c @var{quantum}] [@var{array}] |
| @end example |
| Read lines from the standard input into array variable @var{array}, |
| or from file descriptor @var{fd} |
| if the @option{-u} option is supplied. |
| The variable @code{MAPFILE} is the default @var{array}. |
| Options, if supplied, have the following meanings: |
| @table @code |
| |
| @item -n |
| Copy at most @var{count} lines. If @var{count} is 0, all lines are copied. |
| @item -O |
| Begin assigning to @var{array} at index @var{origin}. |
| The default index is 0. |
| @item -s |
| Discard the first @var{count} lines read. |
| @item -t |
| Remove a trailing line from each line read. |
| @item -u |
| Read lines from file descriptor @var{fd} instead of the standard input. |
| @item -C |
| Evaluate @var{callback} each time @var{quantum}P lines are read. |
| The @option{-c} option specifies @var{quantum}. |
| @item -c |
| Specify the number of lines read between each call to @var{callback}. |
| @end table |
| |
| If @option{-C} is specified without @option{-c}, |
| the default quantum is 5000. |
| When @var{callback} is evaluated, it is supplied the index of the next |
| array element to be assigned as an additional argument. |
| @var{callback} is evaluated after the line is read but before the |
| array element is assigned. |
| |
| If not supplied with an explicit origin, @code{mapfile} will clear @var{array} |
| before assigning to it. |
| |
| @code{mapfile} returns successfully unless an invalid option or option |
| argument is supplied, or @var{array} is invalid or unassignable. |
| |
| @item printf |
| @btindex printf |
| @example |
| printf [-v @var{var}] @var{format} [@var{arguments}] |
| @end example |
| Write the formatted @var{arguments} to the standard output under the |
| control of the @var{format}. |
| The @var{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 |
| @var{argument}. |
| In addition to the standard @code{printf(1)} formats, @samp{%b} causes |
| @code{printf} to expand backslash escape sequences in the corresponding |
| @var{argument}, |
| (except that @samp{\c} terminates output, backslashes in |
| @samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes |
| beginning with @samp{\0} may contain up to four digits), |
| and @samp{%q} causes @code{printf} to output the |
| corresponding @var{argument} in a format that can be reused as shell input. |
| |
| The @option{-v} option causes the output to be assigned to the variable |
| @var{var} rather than being printed to the standard output. |
| |
| The @var{format} is reused as necessary to consume all of the @var{arguments}. |
| If the @var{format} requires more @var{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. |
| |
| @item read |
| @btindex read |
| @example |
| read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] |
| @end example |
| One line is read from the standard input, or from the file descriptor |
| @var{fd} supplied as an argument to the @option{-u} option, and the first word |
| is assigned to the first @var{name}, the second word to the second @var{name}, |
| and so on, with leftover words and their intervening separators assigned |
| to the last @var{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 @env{IFS} variable |
| are used to split the line into words. |
| The backslash character @samp{\} 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 @env{REPLY}. |
| The return code is zero, unless end-of-file is encountered, @code{read} |
| times out (in which case the return code is greater than 128), or an |
| invalid file descriptor is supplied as the argument to @option{-u}. |
| |
| Options, if supplied, have the following meanings: |
| |
| @table @code |
| @item -a @var{aname} |
| The words are assigned to sequential indices of the array variable |
| @var{aname}, starting at 0. |
| All elements are removed from @var{aname} before the assignment. |
| Other @var{name} arguments are ignored. |
| |
| @item -d @var{delim} |
| The first character of @var{delim} is used to terminate the input line, |
| rather than newline. |
| |
| @item -e |
| Readline (@pxref{Command Line Editing}) is used to obtain the line. |
| Readline uses the current (or default, if line editing was not previously |
| active) editing settings. |
| |
| @item -i @var{text} |
| If Readline is being used to read the line, @var{text} is placed into |
| the editing buffer before editing begins. |
| |
| @item -n @var{nchars} |
| @code{read} returns after reading @var{nchars} characters rather than |
| waiting for a complete line of input. |
| |
| @item -p @var{prompt} |
| Display @var{prompt}, without a trailing newline, before attempting |
| to read any input. |
| The prompt is displayed only if input is coming from a terminal. |
| |
| @item -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. |
| |
| @item -s |
| Silent mode. If input is coming from a terminal, characters are |
| not echoed. |
| |
| @item -t @var{timeout} |
| Cause @code{read} to time out and return failure if a complete line of |
| input is not read within @var{timeout} seconds. |
| @var{timeout} may be a decimal number with a fractional portion following |
| the decimal point. |
| This option is only effective if @code{read} is reading input from a |
| terminal, pipe, or other special file; it has no effect when reading |
| from regular files. |
| If @var{timeout} is 0, @code{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. |
| |
| @item -u @var{fd} |
| Read input from file descriptor @var{fd}. |
| |
| @end table |
| |
| @item readarray |
| @btindex readarray |
| @example |
| readarray [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [ |
| -C @var{callback}] [-c @var{quantum}] [@var{array}] |
| @end example |
| Read lines from the standard input into array variable @var{array}, |
| or from file descriptor @var{fd} |
| if the @option{-u} option is supplied. |
| |
| A synonym for @code{mapfile}. |
| |
| @item source |
| @btindex source |
| @example |
| source @var{filename} |
| @end example |
| A synonym for @code{.} (@pxref{Bourne Shell Builtins}). |
| |
| @item type |
| @btindex type |
| @example |
| type [-afptP] [@var{name} @dots{}] |
| @end example |
| For each @var{name}, indicate how it would be interpreted if used as a |
| command name. |
| |
| If the @option{-t} option is used, @code{type} prints a single word |
| which is one of @samp{alias}, @samp{function}, @samp{builtin}, |
| @samp{file} or @samp{keyword}, |
| if @var{name} is an alias, shell function, shell builtin, |
| disk file, or shell reserved word, respectively. |
| If the @var{name} is not found, then nothing is printed, and |
| @code{type} returns a failure status. |
| |
| If the @option{-p} option is used, @code{type} either returns the name |
| of the disk file that would be executed, or nothing if @option{-t} |
| would not return @samp{file}. |
| |
| The @option{-P} option forces a path search for each @var{name}, even if |
| @option{-t} would not return @samp{file}. |
| |
| If a command is hashed, @option{-p} and @option{-P} print the hashed value, |
| not necessarily the file that appears first in @code{$PATH}. |
| |
| If the @option{-a} option is used, @code{type} returns all of the places |
| that contain an executable named @var{file}. |
| This includes aliases and functions, if and only if the @option{-p} option |
| is not also used. |
| |
| If the @option{-f} option is used, @code{type} does not attempt to find |
| shell functions, as with the @code{command} builtin. |
| |
| The return status is zero if all of the @var{names} are found, non-zero |
| if any are not found. |
| |
| @item typeset |
| @btindex typeset |
| @example |
| typeset [-afFrxi] [-p] [@var{name}[=@var{value}] @dots{}] |
| @end example |
| The @code{typeset} command is supplied for compatibility with the Korn |
| shell; however, it has been deprecated in favor of the @code{declare} |
| builtin command. |
| |
| @item ulimit |
| @btindex ulimit |
| @example |
| ulimit [-abcdefilmnpqrstuvxHST] [@var{limit}] |
| @end example |
| @code{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: |
| @table @code |
| @item -S |
| Change and report the soft limit associated with a resource. |
| |
| @item -H |
| Change and report the hard limit associated with a resource. |
| |
| @item -a |
| All current limits are reported. |
| |
| @item -b |
| The maximum socket buffer size. |
| |
| @item -c |
| The maximum size of core files created. |
| |
| @item -d |
| The maximum size of a process's data segment. |
| |
| @item -e |
| The maximum scheduling priority ("nice"). |
| |
| @item -f |
| The maximum size of files written by the shell and its children. |
| |
| @item -i |
| The maximum number of pending signals. |
| |
| @item -l |
| The maximum size that may be locked into memory. |
| |
| @item -m |
| The maximum resident set size (many systems do not honor this limit). |
| |
| @item -n |
| The maximum number of open file descriptors (most systems do not |
| allow this value to be set). |
| |
| @item -p |
| The pipe buffer size. |
| |
| @item -q |
| The maximum number of bytes in POSIX message queues. |
| |
| @item -r |
| The maximum real-time scheduling priority. |
| |
| @item -s |
| The maximum stack size. |
| |
| @item -t |
| The maximum amount of cpu time in seconds. |
| |
| @item -u |
| The maximum number of processes available to a single user. |
| |
| @item -v |
| The maximum amount of virtual memory available to the process. |
| |
| @item -x |
| The maximum number of file locks. |
| |
| @item -T |
| The maximum number of threads. |
| |
| @end table |
| |
| If @var{limit} is given, it is the new value of the specified resource; |
| the special @var{limit} values @code{hard}, @code{soft}, and |
| @code{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 @option{-H} option is supplied. |
| When setting new limits, if neither @option{-H} nor @option{-S} is supplied, |
| both the hard and soft limits are set. |
| If no option is given, then @option{-f} is assumed. Values are in 1024-byte |
| increments, except for @option{-t}, which is in seconds, @option{-p}, |
| which is in units of 512-byte blocks, and @option{-n} and @option{-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. |
| |
| @item unalias |
| @btindex unalias |
| @example |
| unalias [-a] [@var{name} @dots{} ] |
| @end example |
| |
| Remove each @var{name} from the list of aliases. If @option{-a} is |
| supplied, all aliases are removed. |
| Aliases are described in @ref{Aliases}. |
| |
| @end table |
| |
| @node Modifying Shell Behavior |
| @section Modifying Shell Behavior |
| |
| @menu |
| * The Set Builtin:: Change the values of shell attributes and |
| positional parameters. |
| * The Shopt Builtin:: Modify shell optional behavior. |
| @end menu |
| |
| @node The Set Builtin |
| @subsection The Set Builtin |
| |
| This builtin is so complicated that it deserves its own section. @code{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. |
| |
| @table @code |
| @item set |
| @btindex set |
| @example |
| set [--abefhkmnptuvxBCEHPT] [-o @var{option}] [@var{argument} @dots{}] |
| set [+abefhkmnptuvxBCEHPT] [+o @var{option}] [@var{argument} @dots{}] |
| @end example |
| |
| If no options or arguments are supplied, @code{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 @sc{posix} mode, only shell variables are listed. |
| |
| When options are supplied, they set or unset shell attributes. |
| Options, if specified, have the following meanings: |
| |
| @table @code |
| @item -a |
| Mark variables and function which are modified or created for export |
| to the environment of subsequent commands. |
| |
| @item -b |
| Cause the status of terminated background jobs to be reported |
| immediately, rather than before printing the next primary prompt. |
| |
| @item -e |
| Exit immediately if a pipeline (@pxref{Pipelines}), which may consist |
| of a single simple command (@pxref{Simple Commands}), |
| a subshell command enclosed in parentheses (@pxref{Command Grouping}), |
| or one of the commands executed as part of a command list enclosed |
| by braces (@pxref{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 @code{while} or @code{until} keyword, |
| part of the test in an @code{if} statement, |
| part of any command executed in a @code{&&} or @code{||} list except |
| the command following the final @code{&&} or @code{||}, |
| any command in a pipeline but the last, |
| or if the command's return status is being inverted with @code{!}. |
| A trap on @code{ERR}, if set, is executed before the shell exits. |
| |
| This option applies to the shell environment and each subshell environment |
| separately (@pxref{Command Execution Environment}), and may cause |
| subshells to exit before executing all the commands in the subshell. |
| |
| @item -f |
| Disable file name generation (globbing). |
| |
| @item -h |
| Locate and remember (hash) commands as they are looked up for execution. |
| This option is enabled by default. |
| |
| @item -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. |
| |
| @item -m |
| Job control is enabled (@pxref{Job Control}). |
| |
| @item -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. |
| |
| @item -o @var{option-name} |
| |
| Set the option corresponding to @var{option-name}: |
| |
| @table @code |
| @item allexport |
| Same as @code{-a}. |
| |
| @item braceexpand |
| Same as @code{-B}. |
| |
| @item emacs |
| Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). |
| This also affects the editing interface used for @code{read -e}. |
| |
| @item errexit |
| Same as @code{-e}. |
| |
| @item errtrace |
| Same as @code{-E}. |
| |
| @item functrace |
| Same as @code{-T}. |
| |
| @item hashall |
| Same as @code{-h}. |
| |
| @item histexpand |
| Same as @code{-H}. |
| |
| @item history |
| Enable command history, as described in @ref{Bash History Facilities}. |
| This option is on by default in interactive shells. |
| |
| @item ignoreeof |
| An interactive shell will not exit upon reading EOF. |
| |
| @item keyword |
| Same as @code{-k}. |
| |
| @item monitor |
| Same as @code{-m}. |
| |
| @item noclobber |
| Same as @code{-C}. |
| |
| @item noexec |
| Same as @code{-n}. |
| |
| @item noglob |
| Same as @code{-f}. |
| |
| @item nolog |
| Currently ignored. |
| |
| @item notify |
| Same as @code{-b}. |
| |
| @item nounset |
| Same as @code{-u}. |
| |
| @item onecmd |
| Same as @code{-t}. |
| |
| @item physical |
| Same as @code{-P}. |
| |
| @item 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. |
| |
| @item posix |
| Change the behavior of Bash where the default operation differs |
| from the @sc{posix} standard to match the standard |
| (@pxref{Bash POSIX Mode}). |
| This is intended to make Bash behave as a strict superset of that |
| standard. |
| |
| @item privileged |
| Same as @code{-p}. |
| |
| @item verbose |
| Same as @code{-v}. |
| |
| @item vi |
| Use a @code{vi}-style line editing interface. |
| This also affects the editing interface used for @code{read -e}. |
| |
| @item xtrace |
| Same as @code{-x}. |
| @end table |
| |
| @item -p |
| Turn on privileged mode. |
| In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not |
| processed, shell functions are not inherited from the environment, |
| and the @env{SHELLOPTS}, @env{CDPATH} and @env{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 @code{-p} option is not supplied, these actions |
| are taken and the effective user id is set to the real user id. |
| If the @code{-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. |
| |
| @item -t |
| Exit after reading and executing one command. |
| |
| @item -u |
| Treat unset variables and parameters other than the special parameters |
| @samp{@@} or @samp{*} as an error when performing parameter expansion. |
| An error message will be written to the standard error, and a non-interactive |
| shell will exit. |
| |
| @item -v |
| Print shell input lines as they are read. |
| |
| @item -x |
| Print a trace of simple commands, @code{for} commands, @code{case} |
| commands, @code{select} commands, and arithmetic @code{for} commands |
| and their arguments or associated word lists after they are |
| expanded and before they are executed. The value of the @env{PS4} |
| variable is expanded and the resultant value is printed before |
| the command and its expanded arguments. |
| |
| @item -B |
| The shell will perform brace expansion (@pxref{Brace Expansion}). |
| This option is on by default. |
| |
| @item -C |
| Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>} |
| from overwriting existing files. |
| |
| @item -E |
| If set, any trap on @code{ERR} is inherited by shell functions, command |
| substitutions, and commands executed in a subshell environment. |
| The @code{ERR} trap is normally not inherited in such cases. |
| |
| @item -H |
| Enable @samp{!} style history substitution (@pxref{History Interaction}). |
| This option is on by default for interactive shells. |
| |
| @item -P |
| If set, do not follow symbolic links when performing commands such as |
| @code{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 @file{/usr/sys} is a symbolic link to @file{/usr/local/sys} |
| then: |
| @example |
| $ cd /usr/sys; echo $PWD |
| /usr/sys |
| $ cd ..; pwd |
| /usr |
| @end example |
| |
| @noindent |
| If @code{set -P} is on, then: |
| @example |
| $ cd /usr/sys; echo $PWD |
| /usr/local/sys |
| $ cd ..; pwd |
| /usr/local |
| @end example |
| |
| @item -T |
| If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by |
| shell functions, command substitutions, and commands executed |
| in a subshell environment. |
| The @code{DEBUG} and @code{RETURN} traps are normally not inherited |
| in such cases. |
| |
| @item -- |
| If no arguments follow this option, then the positional parameters are |
| unset. Otherwise, the positional parameters are set to the |
| @var{arguments}, even if some of them begin with a @samp{-}. |
| |
| @item - |
| Signal the end of options, cause all remaining @var{arguments} |
| to be assigned to the positional parameters. The @option{-x} |
| and @option{-v} options are turned off. |
| If there are no arguments, the positional parameters remain unchanged. |
| @end table |
| |
| Using @samp{+} rather than @samp{-} 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 @code{$-}. |
| |
| The remaining N @var{arguments} are positional parameters and are |
| assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. |
| The special parameter @code{#} is set to N. |
| |
| The return status is always zero unless an invalid option is supplied. |
| @end table |
| |
| @node The Shopt Builtin |
| @subsection The Shopt Builtin |
| |
| This builtin allows you to change additional shell optional behavior. |
| |
| @table @code |
| |
| @item shopt |
| @btindex shopt |
| @example |
| shopt [-pqsu] [-o] [@var{optname} @dots{}] |
| @end example |
| Toggle the values of variables controlling optional shell behavior. |
| With no options, or with the @option{-p} option, a list of all settable |
| options is displayed, with an indication of whether or not each is set. |
| The @option{-p} option causes output to be displayed in a form that |
| may be reused as input. |
| Other options have the following meanings: |
| |
| @table @code |
| @item -s |
| Enable (set) each @var{optname}. |
| |
| @item -u |
| Disable (unset) each @var{optname}. |
| |
| @item -q |
| Suppresses normal output; the return status |
| indicates whether the @var{optname} is set or unset. |
| If multiple @var{optname} arguments are given with @option{-q}, |
| the return status is zero if all @var{optnames} are enabled; |
| non-zero otherwise. |
| |
| @item -o |
| Restricts the values of |
| @var{optname} to be those defined for the @option{-o} option to the |
| @code{set} builtin (@pxref{The Set Builtin}). |
| @end table |
| |
| If either @option{-s} or @option{-u} |
| is used with no @var{optname} arguments, the display is limited to |
| those options which are set or unset, respectively. |
| |
| Unless otherwise noted, the @code{shopt} options are disabled (off) |
| by default. |
| |
| The return status when listing options is zero if all @var{optnames} |
| are enabled, non-zero otherwise. When setting or unsetting options, |
| the return status is zero unless an @var{optname} is not a valid shell |
| option. |
| |
| The list of @code{shopt} options is: |
| @table @code |
| |
| @item autocd |
| If set, a command name that is the name of a directory is executed as if |
| it were the argument to the @code{cd} command. |
| This option is only used by interactive shells. |
| |
| @item cdable_vars |
| If this is set, an argument to the @code{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. |
| |
| @item cdspell |
| If set, minor errors in the spelling of a directory component in a |
| @code{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. |
| |
| @item 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. |
| |
| @item 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 (@pxref{Job Control}). |
| The shell always postpones exiting if any jobs are stopped. |
| |
| @item checkwinsize |
| If set, Bash checks the window size after each command |
| and, if necessary, updates the values of |
| @env{LINES} and @env{COLUMNS}. |
| |
| @item 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. |
| |
| @item compat31 |
| If set, Bash |
| changes its behavior to that of version 3.1 with respect to quoted |
| arguments to the conditional command's =~ operator. |
| |
| @item dirspell |
| If set, Bash |
| attempts spelling correction on directory names during word completion |
| if the directory name initially supplied does not exist. |
| |
| @item dotglob |
| If set, Bash includes filenames beginning with a `.' in |
| the results of filename expansion. |
| |
| @item execfail |
| If this is set, a non-interactive shell will not exit if |
| it cannot execute the file specified as an argument to the @code{exec} |
| builtin command. An interactive shell does not exit if @code{exec} |
| fails. |
| |
| @item expand_aliases |
| If set, aliases are expanded as described below under Aliases, |
| @ref{Aliases}. |
| This option is enabled by default for interactive shells. |
| |
| @item extdebug |
| If set, behavior intended for use by debuggers is enabled: |
| |
| @enumerate |
| @item |
| The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins}) |
| displays the source file name and line number corresponding to each function |
| name supplied as an argument. |
| |
| @item |
| If the command run by the @code{DEBUG} trap returns a non-zero value, the |
| next command is skipped and not executed. |
| |
| @item |
| If the command run by the @code{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 @code{.} or @code{source} builtins), a call to |
| @code{return} is simulated. |
| |
| @item |
| @code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their |
| descriptions (@pxref{Bash Variables}). |
| |
| @item |
| Function tracing is enabled: command substitution, shell functions, and |
| subshells invoked with @code{( @var{command} )} inherit the |
| @code{DEBUG} and @code{RETURN} traps. |
| |
| @item |
| Error tracing is enabled: command substitution, shell functions, and |
| subshells invoked with @code{( @var{command} )} inherit the |
| @code{ERROR} trap. |
| @end enumerate |
| |
| @item extglob |
| If set, the extended pattern matching features described above |
| (@pxref{Pattern Matching}) are enabled. |
| |
| @item extquote |
| If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is |
| performed within @code{$@{@var{parameter}@}} expansions |
| enclosed in double quotes. This option is enabled by default. |
| |
| @item failglob |
| If set, patterns which fail to match filenames during pathname expansion |
| result in an expansion error. |
| |
| @item force_fignore |
| If set, the suffixes specified by the @env{FIGNORE} shell variable |
| cause words to be ignored when performing word completion even if |
| the ignored words are the only possible completions. |
| @xref{Bash Variables}, for a description of @env{FIGNORE}. |
| This option is enabled by default. |
| |
| @item globstar |
| If set, the pattern @samp{**} used in a filename expansion context will |
| match a files and zero or more directories and subdirectories. |
| If the pattern is followed by a @samp{/}, only directories and |
| subdirectories match. |
| |
| @item gnu_errfmt |
| If set, shell error messages are written in the standard @sc{gnu} error |
| message format. |
| |
| @item histappend |
| If set, the history list is appended to the file named by the value |
| of the @env{HISTFILE} |
| variable when the shell exits, rather than overwriting the file. |
| |
| @item histreedit |
| If set, and Readline |
| is being used, a user is given the opportunity to re-edit a |
| failed history substitution. |
| |
| @item 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. |
| |
| @item hostcomplete |
| If set, and Readline is being used, Bash will attempt to perform |
| hostname completion when a word containing a @samp{@@} is being |
| completed (@pxref{Commands For Completion}). This option is enabled |
| by default. |
| |
| @item huponexit |
| If set, Bash will send @code{SIGHUP} to all jobs when an interactive |
| login shell exits (@pxref{Signals}). |
| |
| @item interactive_comments |
| Allow a word beginning with @samp{#} |
| to cause that word and all remaining characters on that |
| line to be ignored in an interactive shell. |
| This option is enabled by default. |
| |
| @item lithist |
| If enabled, and the @code{cmdhist} |
| option is enabled, multi-line commands are saved to the history with |
| embedded newlines rather than using semicolon separators where possible. |
| |
| @item login_shell |
| The shell sets this option if it is started as a login shell |
| (@pxref{Invoking Bash}). |
| The value may not be changed. |
| |
| @item mailwarn |
| If set, and a file that Bash is checking for mail has been |
| accessed since the last time it was checked, the message |
| @code{"The mail in @var{mailfile} has been read"} is displayed. |
| |
| @item no_empty_cmd_completion |
| If set, and Readline is being used, Bash will not attempt to search |
| the @env{PATH} for possible completions when completion is attempted |
| on an empty line. |
| |
| @item nocaseglob |
| If set, Bash matches filenames in a case-insensitive fashion when |
| performing filename expansion. |
| |
| @item nocasematch |
| If set, Bash matches patterns in a case-insensitive fashion when |
| performing matching while executing @code{case} or @code{[[} |
| conditional commands. |
| |
| @item nullglob |
| If set, Bash allows filename patterns which match no |
| files to expand to a null string, rather than themselves. |
| |
| @item progcomp |
| If set, the programmable completion facilities |
| (@pxref{Programmable Completion}) are enabled. |
| This option is enabled by default. |
| |
| @item promptvars |
| If set, prompt strings undergo |
| parameter expansion, command substitution, arithmetic |
| expansion, and quote removal after being expanded |
| as described below (@pxref{Printing a Prompt}). |
| This option is enabled by default. |
| |
| @item restricted_shell |
| The shell sets this option if it is started in restricted mode |
| (@pxref{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. |
| |
| @item shift_verbose |
| If this is set, the @code{shift} |
| builtin prints an error message when the shift count exceeds the |
| number of positional parameters. |
| |
| @item sourcepath |
| If set, the @code{source} builtin uses the value of @env{PATH} |
| to find the directory containing the file supplied as an argument. |
| This option is enabled by default. |
| |
| @item xpg_echo |
| If set, the @code{echo} builtin expands backslash-escape sequences |
| by default. |
| |
| @end table |
| |
| @noindent |
| The return status when listing options is zero if all @var{optnames} |
| are enabled, non-zero otherwise. |
| When setting or unsetting options, the return status is zero unless an |
| @var{optname} is not a valid shell option. |
| |
| @end table |
| |
| @node Special Builtins |
| @section Special Builtins |
| @cindex special builtin |
| |
| For historical reasons, the @sc{posix} standard has classified |
| several builtin commands as @emph{special}. |
| When Bash is executing in @sc{posix} mode, the special builtins |
| differ from other builtin commands in three respects: |
| |
| @enumerate |
| @item |
| Special builtins are found before shell functions during command lookup. |
| |
| @item |
| If a special builtin returns an error status, a non-interactive shell exits. |
| |
| @item |
| Assignment statements preceding the command stay in effect in the shell |
| environment after the command completes. |
| @end enumerate |
| |
| When Bash is not executing in @sc{posix} mode, these builtins behave no |
| differently than the rest of the Bash builtin commands. |
| The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. |
| |
| These are the @sc{posix} special builtins: |
| @example |
| @w{break : . continue eval exec exit export readonly return set} |
| @w{shift trap unset} |
| @end example |
| |
| @node Shell Variables |
| @chapter 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. |
| @end menu |
| |
| This chapter describes the shell variables that Bash uses. |
| Bash automatically assigns default values to a number of variables. |
| |
| @node Bourne Shell Variables |
| @section 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. |
| |
| @vtable @code |
| |
| @item CDPATH |
| A colon-separated list of directories used as a search path for |
| the @code{cd} builtin command. |
| |
| @item HOME |
| The current user's home directory; the default for the @code{cd} builtin |
| command. |
| The value of this variable is also used by tilde expansion |
| (@pxref{Tilde Expansion}). |
| |
| @item IFS |
| A list of characters that separate fields; used when the shell splits |
| words as part of expansion. |
| |
| @item MAIL |
| If this parameter is set to a filename and the @env{MAILPATH} variable |
| is not set, Bash informs the user of the arrival of mail in |
| the specified file. |
| |
| @item 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 @samp{?}. |
| When used in the text of the message, @code{$_} expands to the name of |
| the current mail file. |
| |
| @item OPTARG |
| The value of the last option argument processed by the @code{getopts} builtin. |
| |
| @item OPTIND |
| The index of the last option argument processed by the @code{getopts} builtin. |
| |
| @item PATH |
| A colon-separated list of directories in which the shell looks for |
| commands. |
| A zero-length (null) directory name in the value of @code{PATH} indicates the |
| current directory. |
| A null directory name may appear as two adjacent colons, or as an initial |
| or trailing colon. |
| |
| |
| @item PS1 |
| The primary prompt string. The default value is @samp{\s-\v\$ }. |
| @xref{Printing a Prompt}, for the complete list of escape |
| sequences that are expanded before @env{PS1} is displayed. |
| |
| @item PS2 |
| The secondary prompt string. The default value is @samp{> }. |
| |
| @end vtable |
| |
| @node Bash Variables |
| @section 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 |
| (@pxref{Job Control Variables}). |
| |
| @vtable @code |
| |
| @item BASH |
| The full pathname used to execute the current instance of Bash. |
| |
| @item BASHPID |
| Expands to the process id of the current Bash process. |
| This differs from @code{$$} under certain circumstances, such as subshells |
| that do not require Bash to be re-initialized. |
| |
| @item BASH_ALIASES |
| An associative array variable whose members correspond to the internal |
| list of aliases as maintained by the @code{alias} builtin |
| (@pxref{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. |
| |
| @item 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 @code{.} or @code{source}) is at the top of the stack. When a |
| subroutine is executed, the number of parameters passed is pushed onto |
| @code{BASH_ARGC}. |
| The shell sets @code{BASH_ARGC} only when in extended debugging mode |
| (see @ref{The Shopt Builtin} |
| for a description of the @code{extdebug} option to the @code{shopt} |
| builtin). |
| |
| @item 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 @code{BASH_ARGV}. |
| The shell sets @code{BASH_ARGV} only when in extended debugging mode |
| (see @ref{The Shopt Builtin} |
| for a description of the @code{extdebug} option to the @code{shopt} |
| builtin). |
| |
| @item BASH_CMDS |
| An associative array variable whose members correspond to the internal |
| hash table of commands as maintained by the @code{hash} builtin |
| (@pxref{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. |
| |
| @item 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. |
| |
| @item 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. @xref{Bash Startup Files}. |
| |
| @item BASH_EXECUTION_STRING |
| The command argument to the @option{-c} invocation option. |
| |
| @item BASH_LINENO |
| An array variable whose members are the line numbers in source files |
| corresponding to each member of @var{FUNCNAME}. |
| @code{$@{BASH_LINENO[$i]@}} is the line number in the source file where |
| @code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if |
| referenced within another shell function). |
| The corresponding source file name is @code{$@{BASH_SOURCE[$i]@}}. |
| Use @code{LINENO} to obtain the current line number. |
| |
| @item BASH_REMATCH |
| An array variable whose members are assigned by the @samp{=~} binary |
| operator to the @code{[[} conditional command |
| (@pxref{Conditional Constructs}). |
| The element with index 0 is the portion of the string |
| matching the entire regular expression. |
| The element with index @var{n} is the portion of the |
| string matching the @var{n}th parenthesized subexpression. |
| This variable is read-only. |
| |
| @item BASH_SOURCE |
| An array variable whose members are the source filenames corresponding |
| to the elements in the @code{FUNCNAME} array variable. |
| |
| @item BASH_SUBSHELL |
| Incremented by one each time a subshell or subshell environment is spawned. |
| The initial value is 0. |
| |
| @item BASH_VERSINFO |
| A readonly array variable (@pxref{Arrays}) |
| whose members hold version information for this instance of Bash. |
| The values assigned to the array members are as follows: |
| |
| @table @code |
| |
| @item BASH_VERSINFO[0] |
| The major version number (the @var{release}). |
| |
| @item BASH_VERSINFO[1] |
| The minor version number (the @var{version}). |
| |
| @item BASH_VERSINFO[2] |
| The patch level. |
| |
| @item BASH_VERSINFO[3] |
| The build version. |
| |
| @item BASH_VERSINFO[4] |
| The release status (e.g., @var{beta1}). |
| |
| @item BASH_VERSINFO[5] |
| The value of @env{MACHTYPE}. |
| |
| @end table |
| |
| @item BASH_VERSION |
| The version number of the current instance of Bash. |
| |
| @item COLUMNS |
| Used by the @code{select} builtin command to determine the terminal width |
| when printing selection lists. Automatically set upon receipt of a |
| @code{SIGWINCH}. |
| |
| @item COMP_CWORD |
| An index into @env{$@{COMP_WORDS@}} of the word containing the current |
| cursor position. |
| This variable is available only in shell functions invoked by the |
| programmable completion facilities (@pxref{Programmable Completion}). |
| |
| @item COMP_LINE |
| The current command line. |
| This variable is available only in shell functions and external |
| commands invoked by the |
| programmable completion facilities (@pxref{Programmable Completion}). |
| |
| @item 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 @code{$@{#COMP_LINE@}}. |
| This variable is available only in shell functions and external |
| commands invoked by the |
| programmable completion facilities (@pxref{Programmable Completion}). |
| |
| @item COMP_TYPE |
| Set to an integer value corresponding to the type of completion attempted |
| that caused a completion function to be called: |
| @var{TAB}, for normal completion, |
| @samp{?}, for listing completions after successive tabs, |
| @samp{!}, for listing alternatives on partial word completion, |
| @samp{@@}, to list completions if the word is not unmodified, |
| or |
| @samp{%}, for menu completion. |
| This variable is available only in shell functions and external |
| commands invoked by the |
| programmable completion facilities (@pxref{Programmable Completion}). |
| |
| @item COMP_KEY |
| The key (or final key of a key sequence) used to invoke the current |
| completion function. |
| |
| @item COMP_WORDBREAKS |
| The set of characters that the Readline library treats as word |
| separators when performing word completion. |
| If @code{COMP_WORDBREAKS} is unset, it loses its special properties, |
| even if it is subsequently reset. |
| |
| @item 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 |
| @code{COMP_WORDBREAKS} as described above. |
| This variable is available only in shell functions invoked by the |
| programmable completion facilities (@pxref{Programmable Completion}). |
| |
| @item COMPREPLY |
| An array variable from which Bash reads the possible completions |
| generated by a shell function invoked by the programmable completion |
| facility (@pxref{Programmable Completion}). |
| |
| @item 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 |
| @code{dirs} builtin. |
| Assigning to members of this array variable may be used to modify |
| directories already in the stack, but the @code{pushd} and @code{popd} |
| builtins must be used to add and remove directories. |
| Assignment to this variable will not change the current directory. |
| If @env{DIRSTACK} is unset, it loses its special properties, even if |
| it is subsequently reset. |
| |
| @item EMACS |
| If Bash finds this variable in the environment when the shell |
| starts with value @samp{t}, it assumes that the shell is running in an |
| emacs shell buffer and disables line editing. |
| |
| @item EUID |
| The numeric effective user id of the current user. This variable |
| is readonly. |
| |
| @item FCEDIT |
| The editor used as a default by the @option{-e} option to the @code{fc} |
| builtin command. |
| |
| @item FIGNORE |
| A colon-separated list of suffixes to ignore when performing |
| filename completion. |
| A file name whose suffix matches one of the entries in |
| @env{FIGNORE} |
| is excluded from the list of matched file names. A sample |
| value is @samp{.o:~} |
| |
| @item 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 @code{"main"}. |
| This variable exists only when a shell function is executing. |
| Assignments to @env{FUNCNAME} have no effect and return an error status. |
| If @env{FUNCNAME} is unset, it loses its special properties, even if |
| it is subsequently reset. |
| |
| @item 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 @env{GLOBIGNORE}, it is removed from the list |
| of matches. |
| |
| @item GROUPS |
| An array variable containing the list of groups of which the current |
| user is a member. |
| Assignments to @env{GROUPS} have no effect and return an error status. |
| If @env{GROUPS} is unset, it loses its special properties, even if it is |
| subsequently reset. |
| |
| @item histchars |
| Up to three characters which control history expansion, quick |
| substitution, and tokenization (@pxref{History Interaction}). |
| The first character is the |
| @var{history expansion} character, that is, the character which signifies the |
| start of a history expansion, normally @samp{!}. The second character is the |
| character which signifies `quick substitution' when seen as the first |
| character on a line, normally @samp{^}. 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 @samp{#}. 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. |
| |
| @item HISTCMD |
| The history number, or index in the history list, of the current |
| command. If @env{HISTCMD} is unset, it loses its special properties, |
| even if it is subsequently reset. |
| |
| @item HISTCONTROL |
| A colon-separated list of values controlling how commands are saved on |
| the history list. |
| If the list of values includes @samp{ignorespace}, lines which begin |
| with a space character are not saved in the history list. |
| A value of @samp{ignoredups} causes lines which match the previous |
| history entry to not be saved. |
| A value of @samp{ignoreboth} is shorthand for |
| @samp{ignorespace} and @samp{ignoredups}. |
| A value of @samp{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 @env{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 @env{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 |
| @env{HISTCONTROL}. |
| |
| @item HISTFILE |
| The name of the file to which the command history is saved. The |
| default value is @file{~/.bash_history}. |
| |
| @item 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. |
| |
| @item 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 @samp{*} is appended). Each pattern is tested |
| against the line after the checks specified by @env{HISTCONTROL} |
| are applied. In addition to the normal shell pattern matching |
| characters, @samp{&} matches the previous history line. @samp{&} |
| 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 |
| @env{HISTIGNORE}. |
| |
| @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A |
| pattern of @samp{&} is identical to @code{ignoredups}, and a |
| pattern of @samp{[ ]*} is identical to @code{ignorespace}. |
| Combining these two patterns, separating them with a colon, |
| provides the functionality of @code{ignoreboth}. |
| |
| @item HISTSIZE |
| The maximum number of commands to remember on the history list. |
| The default value is 500. |
| |
| @item HISTTIMEFORMAT |
| If this variable is set and not null, its value is used as a format string |
| for @var{strftime} to print the time stamp associated with each history |
| entry displayed by the @code{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. |
| |
| @item HOSTFILE |
| Contains the name of a file in the same format as @file{/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 @env{HOSTFILE} is set, but has no value, Bash attempts to read |
| @file{/etc/hosts} to obtain the list of possible hostname completions. |
| When @env{HOSTFILE} is unset, the hostname list is cleared. |
| |
| @item HOSTNAME |
| The name of the current host. |
| |
| @item HOSTTYPE |
| A string describing the machine Bash is running on. |
| |
| @item IGNOREEOF |
| Controls the action of the shell on receipt of an @code{EOF} character |
| as the sole input. If set, the value denotes the number |
| of consecutive @code{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 @code{EOF} signifies the end of |
| input to the shell. This is only in effect for interactive shells. |
| |
| @item INPUTRC |
| The name of the Readline initialization file, overriding the default |
| of @file{~/.inputrc}. |
| |
| @item LANG |
| Used to determine the locale category for any category not specifically |
| selected with a variable starting with @code{LC_}. |
| |
| @item LC_ALL |
| This variable overrides the value of @env{LANG} and any other |
| @code{LC_} variable specifying a locale category. |
| |
| @item 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 |
| (@pxref{Filename Expansion}). |
| |
| @item LC_CTYPE |
| This variable determines the interpretation of characters and the |
| behavior of character classes within filename expansion and pattern |
| matching (@pxref{Filename Expansion}). |
| |
| @item LC_MESSAGES |
| This variable determines the locale used to translate double-quoted |
| strings preceded by a @samp{$} (@pxref{Locale Translation}). |
| |
| @item LC_NUMERIC |
| This variable determines the locale category used for number formatting. |
| |
| @item LINENO |
| The line number in the script or shell function currently executing. |
| |
| @item LINES |
| Used by the @code{select} builtin command to determine the column length |
| for printing selection lists. Automatically set upon receipt of a |
| @code{SIGWINCH}. |
| |
| @item MACHTYPE |
| A string that fully describes the system type on which Bash |
| is executing, in the standard @sc{gnu} @var{cpu-company-system} format. |
| |
| @item MAILCHECK |
| How often (in seconds) that the shell should check for mail in the |
| files specified in the @env{MAILPATH} or @env{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. |
| |
| @item OLDPWD |
| The previous working directory as set by the @code{cd} builtin. |
| |
| @item OPTERR |
| If set to the value 1, Bash displays error messages |
| generated by the @code{getopts} builtin command. |
| |
| @item OSTYPE |
| A string describing the operating system Bash is running on. |
| |
| @item PIPESTATUS |
| An array variable (@pxref{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). |
| |
| @item POSIXLY_CORRECT |
| If this variable is in the environment when @code{bash} starts, the shell |
| enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the |
| startup files, as if the @option{--posix} invocation option had been supplied. |
| If it is set while the shell is running, @code{bash} enables @sc{posix} mode, |
| as if the command |
| @example |
| @code{set -o posix} |
| @end example |
| @noindent |
| had been executed. |
| |
| @item PPID |
| The process @sc{id} of the shell's parent process. This variable |
| is readonly. |
| |
| @item PROMPT_COMMAND |
| If set, the value is interpreted as a command to execute |
| before the printing of each primary prompt (@env{$PS1}). |
| |
| @item 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 @code{\w} and |
| @code{\W} prompt string escapes (@pxref{Printing a Prompt}). |
| Characters removed are replaced with an ellipsis. |
| |
| @item PS3 |
| The value of this variable is used as the prompt for the |
| @code{select} command. If this variable is not set, the |
| @code{select} command prompts with @samp{#? } |
| |
| @item PS4 |
| The value is the prompt printed before the command line is echoed |
| when the @option{-x} option is set (@pxref{The Set Builtin}). |
| The first character of @env{PS4} is replicated multiple times, as |
| necessary, to indicate multiple levels of indirection. |
| The default is @samp{+ }. |
| |
| @item PWD |
| The current working directory as set by the @code{cd} builtin. |
| |
| @item 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. |
| |
| @item REPLY |
| The default variable for the @code{read} builtin. |
| |
| @item 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. |
| |
| @item 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. |
| |
| @item SHELLOPTS |
| A colon-separated list of enabled shell options. Each word in |
| the list is a valid argument for the @option{-o} option to the |
| @code{set} builtin command (@pxref{The Set Builtin}). |
| The options appearing in @env{SHELLOPTS} are those reported |
| as @samp{on} by @samp{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. |
| |
| @item 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. |
| |
| @item TIMEFORMAT |
| The value of this parameter is used as a format string specifying |
| how the timing information for pipelines prefixed with the @code{time} |
| reserved word should be displayed. |
| The @samp{%} 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. |
| |
| @table @code |
| |
| @item %% |
| A literal @samp{%}. |
| |
| @item %[@var{p}][l]R |
| The elapsed time in seconds. |
| |
| @item %[@var{p}][l]U |
| The number of CPU seconds spent in user mode. |
| |
| @item %[@var{p}][l]S |
| The number of CPU seconds spent in system mode. |
| |
| @item %P |
| The CPU percentage, computed as (%U + %S) / %R. |
| @end table |
| |
| The optional @var{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 @var{p} greater than 3 are changed to 3. |
| If @var{p} is not specified, the value 3 is used. |
| |
| The optional @code{l} specifies a longer format, including minutes, of |
| the form @var{MM}m@var{SS}.@var{FF}s. |
| The value of @var{p} determines whether or not the fraction is included. |
| |
| If this variable is not set, Bash acts as if it had the value |
| @example |
| @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'} |
| @end example |
| If the value is null, no timing information is displayed. |
| A trailing newline is added when the format string is displayed. |
| |
| @item TMOUT |
| If set to a value greater than zero, @code{TMOUT} is treated as the |
| default timeout for the @code{read} builtin (@pxref{Bash Builtins}). |
| The @code{select} command (@pxref{Conditional Constructs}) terminates |
| if input does not arrive after @code{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. |
| |
| @item TMPDIR |
| If set, Bash uses its value as the name of a directory in which |
| Bash creates temporary files for the shell's use. |
| |
| @item UID |
| The numeric real user id of the current user. This variable is readonly. |
| |
| @end vtable |
| |
| @node Bash Features |
| @chapter 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 @code{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. |
| @end menu |
| |
| @node Invoking Bash |
| @section Invoking Bash |
| |
| @example |
| bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] |
| bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}] |
| bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] |
| @end example |
| |
| In addition to the single-character shell command-line options |
| (@pxref{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. |
| |
| @table @code |
| @item --debugger |
| Arrange for the debugger profile to be executed before the shell |
| starts. Turns on extended debugging mode (see @ref{The Shopt Builtin} |
| for a description of the @code{extdebug} option to the @code{shopt} |
| builtin) and shell function tracing |
| (see @ref{The Set Builtin} for a description of the @code{-o functrace} |
| option). |
| |
| @item --dump-po-strings |
| A list of all double-quoted strings preceded by @samp{$} |
| is printed on the standard output |
| in the @sc{gnu} @code{gettext} PO (portable object) file format. |
| Equivalent to @option{-D} except for the output format. |
| |
| @item --dump-strings |
| Equivalent to @option{-D}. |
| |
| @item --help |
| Display a usage message on standard output and exit successfully. |
| |
| @item --init-file @var{filename} |
| @itemx --rcfile @var{filename} |
| Execute commands from @var{filename} (instead of @file{~/.bashrc}) |
| in an interactive shell. |
| |
| @item --login |
| Equivalent to @option{-l}. |
| |
| @item --noediting |
| Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing}) |
| to read command lines when the shell is interactive. |
| |
| @item --noprofile |
| Don't load the system-wide startup file @file{/etc/profile} |
| or any of the personal initialization files |
| @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} |
| when Bash is invoked as a login shell. |
| |
| @item --norc |
| Don't read the @file{~/.bashrc} initialization file in an |
| interactive shell. This is on by default if the shell is |
| invoked as @code{sh}. |
| |
| @item --posix |
| Change the behavior of Bash where the default operation differs |
| from the @sc{posix} standard to match the standard. This |
| is intended to make Bash behave as a strict superset of that |
| standard. @xref{Bash POSIX Mode}, for a description of the Bash |
| @sc{posix} mode. |
| |
| @item --restricted |
| Make the shell a restricted shell (@pxref{The Restricted Shell}). |
| |
| @item --verbose |
| Equivalent to @option{-v}. Print shell input lines as they're read. |
| |
| @item --version |
| Show version information for this instance of |
| Bash on the standard output and exit successfully. |
| |
| @end table |
| |
| There are several single-character options that may be supplied at |
| invocation which are not available with the @code{set} builtin. |
| |
| @table @code |
| @item -c @var{string} |
| Read and execute commands from @var{string} after processing the |
| options, then exit. Any remaining arguments are assigned to the |
| positional parameters, starting with @code{$0}. |
| |
| @item -i |
| Force the shell to run interactively. Interactive shells are |
| described in @ref{Interactive Shells}. |
| |
| @item -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 @samp{exec -l bash}. |
| When the shell is not interactive, the login shell startup files will |
| be executed. |
| @samp{exec bash -l} or @samp{exec bash --login} |
| will replace the current shell with a Bash login shell. |
| @xref{Bash Startup Files}, for a description of the special behavior |
| of a login shell. |
| |
| @item -r |
| Make the shell a restricted shell (@pxref{The Restricted Shell}). |
| |
| @item -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. |
| |
| @item -D |
| A list of all double-quoted strings preceded by @samp{$} |
| is printed on the standard output. |
| These are the strings that |
| are subject to language translation when the current locale |
| is not @code{C} or @code{POSIX} (@pxref{Locale Translation}). |
| This implies the @option{-n} option; no commands will be executed. |
| |
| @item [-+]O [@var{shopt_option}] |
| @var{shopt_option} is one of the shell options accepted by the |
| @code{shopt} builtin (@pxref{The Shopt Builtin}). |
| If @var{shopt_option} is present, @option{-O} sets the value of that option; |
| @option{+O} unsets it. |
| If @var{shopt_option} is not supplied, the names and values of the shell |
| options accepted by @code{shopt} are printed on the standard output. |
| If the invocation option is @option{+O}, the output is displayed in a format |
| that may be reused as input. |
| |
| @item -- |
| A @code{--} signals the end of options and disables further option |
| processing. |
| Any arguments after the @code{--} are treated as filenames and arguments. |
| |
| @end table |
| |
| @cindex login shell |
| A @emph{login} shell is one whose first character of argument zero is |
| @samp{-}, or one invoked with the @option{--login} option. |
| |
| @cindex interactive shell |
| An @emph{interactive} shell is one started without non-option arguments, |
| unless @option{-s} is specified, |
| without specifying the @option{-c} option, and whose input and output are both |
| connected to terminals (as determined by @code{isatty(3)}), or one |
| started with the @option{-i} option. @xref{Interactive Shells}, for more |
| information. |
| |
| If arguments remain after option processing, and neither the |
| @option{-c} nor the @option{-s} |
| option has been supplied, the first argument is assumed to |
| be the name of a file containing shell commands (@pxref{Shell Scripts}). |
| When Bash is invoked in this fashion, @code{$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. |
| |
| @node Bash Startup Files |
| @section Bash Startup Files |
| @cindex 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 (@pxref{Tilde Expansion}). |
| |
| Interactive shells are described in @ref{Interactive Shells}. |
| |
| @subsubheading Invoked as an interactive login shell, or with @option{--login} |
| |
| When Bash is invoked as an interactive login shell, or as a |
| non-interactive shell with the @option{--login} option, it first reads and |
| executes commands from the file @file{/etc/profile}, if that file exists. |
| After reading that file, it looks for @file{~/.bash_profile}, |
| @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads |
| and executes commands from the first one that exists and is readable. |
| The @option{--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 @file{~/.bash_logout}, if it exists. |
| |
| @subsubheading 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 @file{~/.bashrc}, if that file exists. |
| This may be inhibited by using the @option{--norc} option. |
| The @option{--rcfile @var{file}} option will force Bash to read and |
| execute commands from @var{file} instead of @file{~/.bashrc}. |
| |
| So, typically, your @file{~/.bash_profile} contains the line |
| @example |
| @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi} |
| @end example |
| @noindent |
| after (or before) any login-specific initializations. |
| |
| @subsubheading Invoked non-interactively |
| |
| When Bash is started non-interactively, to run a shell script, |
| for example, it looks for the variable @env{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: |
| @example |
| @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} |
| @end example |
| @noindent |
| but the value of the @env{PATH} variable is not used to search for the |
| file name. |
| |
| As noted above, if a non-interactive shell is invoked with the |
| @option{--login} option, Bash attempts to read and execute commands from the |
| login shell startup files. |
| |
| @subsubheading Invoked with name @code{sh} |
| |
| If Bash is invoked with the name @code{sh}, it tries to mimic the |
| startup behavior of historical versions of @code{sh} as closely as |
| possible, while conforming to the @sc{posix} standard as well. |
| |
| When invoked as an interactive login shell, or as a non-interactive |
| shell with the @option{--login} option, it first attempts to read |
| and execute commands from @file{/etc/profile} and @file{~/.profile}, in |
| that order. |
| The @option{--noprofile} option may be used to inhibit this behavior. |
| When invoked as an interactive shell with the name @code{sh}, Bash |
| looks for the variable @env{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 @code{sh} does not attempt to read and execute |
| commands from any other startup files, the @option{--rcfile} option has |
| no effect. |
| A non-interactive shell invoked with the name @code{sh} does not attempt |
| to read any other startup files. |
| |
| When invoked as @code{sh}, Bash enters @sc{posix} mode after |
| the startup files are read. |
| |
| @subsubheading Invoked in @sc{posix} mode |
| |
| When Bash is started in @sc{posix} mode, as with the |
| @option{--posix} command line option, it follows the @sc{posix} standard |
| for startup files. |
| In this mode, interactive shells expand the @env{ENV} variable |
| and commands are read and executed from the file whose name is the |
| expanded value. |
| No other startup files are read. |
| |
| @subsubheading 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 @code{rshd}, or the secure shell daemon @code{sshd}. |
| If Bash determines it is being run in |
| this fashion, it reads and executes commands from @file{~/.bashrc}, if that |
| file exists and is readable. |
| It will not do this if invoked as @code{sh}. |
| The @option{--norc} option may be used to inhibit this behavior, and the |
| @option{--rcfile} option may be used to force another file to be read, but |
| @code{rshd} does not generally invoke the shell with those options or |
| allow them to be specified. |
| |
| @subsubheading Invoked with unequal effective and real @sc{uid/gid}s |
| |
| If Bash is started with the effective user (group) id not equal to the |
| real user (group) id, and the @code{-p} option is not supplied, no startup |
| files are read, shell functions are not inherited from the environment, |
| the @env{SHELLOPTS} variable, if it appears in the environment, is ignored, |
| and the effective user id is set to the real user id. |
| If the @code{-p} option is supplied at invocation, the startup behavior is |
| the same, but the effective user id is not reset. |
| |
| @node Interactive Shells |
| @section Interactive Shells |
| @cindex interactive shell |
| @cindex shell, interactive |
| |
| @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? |
| @end menu |
| |
| @node What is an Interactive Shell? |
| @subsection What is an Interactive Shell? |
| |
| An interactive shell |
| is one started without non-option arguments, unless @option{-s} is |
| specified, without specifying the @option{-c} option, and |
| whose input and error output are both |
| connected to terminals (as determined by @code{isatty(3)}), |
| or one started with the @option{-i} option. |
| |
| An interactive shell generally reads from and writes to a user's |
| terminal. |
| |
| The @option{-s} invocation option may be used to set the positional parameters |
| when an interactive shell is started. |
| |
| @node Is this Shell Interactive? |
| @subsection Is this Shell Interactive? |
| |
| To determine within a startup script whether or not Bash is |
| running interactively, |
| test the value of the @samp{-} special parameter. |
| It contains @code{i} when the shell is interactive. For example: |
| |
| @example |
| case "$-" in |
| *i*) echo This shell is interactive ;; |
| *) echo This shell is not interactive ;; |
| esac |
| @end example |
| |
| Alternatively, startup scripts may examine the variable |
| @env{PS1}; it is unset in non-interactive shells, and set in |
| interactive shells. Thus: |
| |
| @example |
| if [ -z "$PS1" ]; then |
| echo This shell is not interactive |
| else |
| echo This shell is interactive |
| fi |
| @end example |
| |
| @node Interactive Shell Behavior |
| @subsection Interactive Shell Behavior |
| |
| When the shell is running interactively, it changes its behavior in |
| several ways. |
| |
| @enumerate |
| @item |
| Startup files are read and executed as described in @ref{Bash Startup Files}. |
| |
| @item |
| Job Control (@pxref{Job Control}) is enabled by default. When job |
| control is in effect, Bash ignores the keyboard-generated job control |
| signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. |
| |
| @item |
| Bash expands and displays @env{PS1} before reading the first line |
| of a command, and expands and displays @env{PS2} before reading the |
| second and subsequent lines of a multi-line command. |
| |
| @item |
| Bash executes the value of the @env{PROMPT_COMMAND} variable as a command |
| before printing the primary prompt, @env{$PS1} |
| (@pxref{Bash Variables}). |
| |
| @item |
| Readline (@pxref{Command Line Editing}) is used to read commands from |
| the user's terminal. |
| |
| @item |
| Bash inspects the value of the @code{ignoreeof} option to @code{set -o} |
| instead of exiting immediately when it receives an @code{EOF} on its |
| standard input when reading a command (@pxref{The Set Builtin}). |
| |
| @item |
| Command history (@pxref{Bash History Facilities}) |
| and history expansion (@pxref{History Interaction}) |
| are enabled by default. |
| Bash will save the command history to the file named by @env{$HISTFILE} |
| when an interactive shell exits. |
| |
| @item |
| Alias expansion (@pxref{Aliases}) is performed by default. |
| |
| @item |
| In the absence of any traps, Bash ignores @code{SIGTERM} |
| (@pxref{Signals}). |
| |
| @item |
| In the absence of any traps, @code{SIGINT} is caught and handled |
| ((@pxref{Signals}). |
| @code{SIGINT} will interrupt some shell builtins. |
| |
| @item |
| An interactive login shell sends a @code{SIGHUP} to all jobs on exit |
| if the @code{huponexit} shell option has been enabled (@pxref{Signals}). |
| |
| @item |
| The @option{-n} invocation option is ignored, and @samp{set -n} has |
| no effect (@pxref{The Set Builtin}). |
| |
| @item |
| Bash will check for mail periodically, depending on the values of the |
| @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables |
| (@pxref{Bash Variables}). |
| |
| @item |
| Expansion errors due to references to unbound shell variables after |
| @samp{set -u} has been enabled will not cause the shell to exit |
| (@pxref{The Set Builtin}). |
| |
| @item |
| The shell will not exit on expansion errors caused by @var{var} being unset |
| or null in @code{$@{@var{var}:?@var{word}@}} expansions |
| (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| Redirection errors encountered by shell builtins will not cause the |
| shell to exit. |
| |
| @item |
| When running in @sc{posix} mode, a special builtin returning an error |
| status will not cause the shell to exit (@pxref{Bash POSIX Mode}). |
| |
| @item |
| A failed @code{exec} will not cause the shell to exit |
| (@pxref{Bourne Shell Builtins}). |
| |
| @item |
| Parser syntax errors will not cause the shell to exit. |
| |
| @item |
| Simple spelling correction for directory arguments to the @code{cd} |
| builtin is enabled by default (see the description of the @code{cdspell} |
| option to the @code{shopt} builtin in @ref{The Shopt Builtin}). |
| |
| @item |
| The shell will check the value of the @env{TMOUT} variable and exit |
| if a command is not read within the specified number of seconds after |
| printing @env{$PS1} (@pxref{Bash Variables}). |
| |
| @end enumerate |
| |
| @node Bash Conditional Expressions |
| @section Bash Conditional Expressions |
| @cindex expressions, conditional |
| |
| Conditional expressions are used by the @code{[[} compound command |
| and the @code{test} and @code{[} 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 @var{file} argument to one of the primaries is of the form |
| @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked. |
| If the @var{file} argument to one of the primaries is one of |
| @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file |
| descriptor 0, 1, or 2, respectively, is checked. |
| |
| Unless otherwise specified, primaries that operate on files follow symbolic |
| links and operate on the target of the link, rather than the link itself. |
| |
| @table @code |
| @item -a @var{file} |
| True if @var{file} exists. |
| |
| @item -b @var{file} |
| True if @var{file} exists and is a block special file. |
| |
| @item -c @var{file} |
| True if @var{file} exists and is a character special file. |
| |
| @item -d @var{file} |
| True if @var{file} exists and is a directory. |
| |
| @item -e @var{file} |
| True if @var{file} exists. |
| |
| @item -f @var{file} |
| True if @var{file} exists and is a regular file. |
| |
| @item -g @var{file} |
| True if @var{file} exists and its set-group-id bit is set. |
| |
| @item -h @var{file} |
| True if @var{file} exists and is a symbolic link. |
| |
| @item -k @var{file} |
| True if @var{file} exists and its "sticky" bit is set. |
| |
| @item -p @var{file} |
| True if @var{file} exists and is a named pipe (FIFO). |
| |
| @item -r @var{file} |
| True if @var{file} exists and is readable. |
| |
| @item -s @var{file} |
| True if @var{file} exists and has a size greater than zero. |
| |
| @item -t @var{fd} |
| True if file descriptor @var{fd} is open and refers to a terminal. |
| |
| @item -u @var{file} |
| True if @var{file} exists and its set-user-id bit is set. |
| |
| @item -w @var{file} |
| True if @var{file} exists and is writable. |
| |
| @item -x @var{file} |
| True if @var{file} exists and is executable. |
| |
| @item -O @var{file} |
| True if @var{file} exists and is owned by the effective user id. |
| |
| @item -G @var{file} |
| True if @var{file} exists and is owned by the effective group id. |
| |
| @item -L @var{file} |
| True if @var{file} exists and is a symbolic link. |
| |
| @item -S @var{file} |
| True if @var{file} exists and is a socket. |
| |
| @item -N @var{file} |
| True if @var{file} exists and has been modified since it was last read. |
| |
| @item @var{file1} -nt @var{file2} |
| True if @var{file1} is newer (according to modification date) |
| than @var{file2}, or if @var{file1} exists and @var{file2} does not. |
| |
| @item @var{file1} -ot @var{file2} |
| True if @var{file1} is older than @var{file2}, |
| or if @var{file2} exists and @var{file1} does not. |
| |
| @item @var{file1} -ef @var{file2} |
| True if @var{file1} and @var{file2} refer to the same device and |
| inode numbers. |
| |
| @item -o @var{optname} |
| True if shell option @var{optname} is enabled. |
| The list of options appears in the description of the @option{-o} |
| option to the @code{set} builtin (@pxref{The Set Builtin}). |
| |
| @item -z @var{string} |
| True if the length of @var{string} is zero. |
| |
| @item -n @var{string} |
| @itemx @var{string} |
| True if the length of @var{string} is non-zero. |
| |
| @item @var{string1} == @var{string2} |
| True if the strings are equal. |
| @samp{=} may be used in place of @samp{==} for strict @sc{posix} compliance. |
| |
| @item @var{string1} != @var{string2} |
| True if the strings are not equal. |
| |
| @item @var{string1} < @var{string2} |
| True if @var{string1} sorts before @var{string2} lexicographically |
| in the current locale. |
| |
| @item @var{string1} > @var{string2} |
| True if @var{string1} sorts after @var{string2} lexicographically |
| in the current locale. |
| |
| @item @var{arg1} OP @var{arg2} |
| @code{OP} is one of |
| @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. |
| These arithmetic binary operators return true if @var{arg1} |
| is equal to, not equal to, less than, less than or equal to, |
| greater than, or greater than or equal to @var{arg2}, |
| respectively. @var{Arg1} and @var{arg2} |
| may be positive or negative integers. |
| |
| @end table |
| |
| @node Shell Arithmetic |
| @section Shell Arithmetic |
| @cindex arithmetic, shell |
| @cindex shell arithmetic |
| @cindex expressions, arithmetic |
| @cindex evaluation, arithmetic |
| @cindex arithmetic evaluation |
| |
| The shell allows arithmetic expressions to be evaluated, as one of |
| the shell expansions or by the @code{let} and the @option{-i} option |
| to the @code{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. |
| |
| @table @code |
| |
| @item @var{id}++ @var{id}-- |
| variable post-increment and post-decrement |
| |
| @item ++@var{id} --@var{id} |
| variable pre-increment and pre-decrement |
| |
| @item - + |
| unary minus and plus |
| |
| @item ! ~ |
| logical and bitwise negation |
| |
| @item ** |
| exponentiation |
| |
| @item * / % |
| multiplication, division, remainder |
| |
| @item + - |
| addition, subtraction |
| |
| @item << >> |
| left and right bitwise shifts |
| |
| @item <= >= < > |
| comparison |
| |
| @item == != |
| equality and inequality |
| |
| @item & |
| bitwise AND |
| |
| @item ^ |
| bitwise exclusive OR |
| |
| @item | |
| bitwise OR |
| |
| @item && |
| logical AND |
| |
| @item || |
| logical OR |
| |
| @item expr ? expr : expr |
| conditional operator |
| |
| @item = *= /= %= += -= <<= >>= &= ^= |= |
| assignment |
| |
| @item expr1 , expr2 |
| comma |
| @end table |
| |
| 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 |
| @var{integer} attribute using @samp{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 @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, |
| numbers take the form [@var{base}@code{#}]@var{n}, where @var{base} |
| is a decimal number between 2 and 64 representing the arithmetic |
| base, and @var{n} is a number in that base. If @var{base}@code{#} is |
| omitted, then base 10 is used. |
| The digits greater than 9 are represented by the lowercase letters, |
| the uppercase letters, @samp{@@}, and @samp{_}, in that order. |
| If @var{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. |
| |
| @node Aliases |
| @section Aliases |
| @cindex alias expansion |
| |
| @var{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 @code{alias} and @code{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 @samp{/}, @samp{$}, @samp{`}, @samp{=} 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 @code{ls} to @code{"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 @code{alias} |
| command, and removed with the @code{unalias} command. |
| |
| There is no mechanism for using arguments in the replacement text, |
| as in @code{csh}. |
| If arguments are needed, a shell function should be used |
| (@pxref{Shell Functions}). |
| |
| Aliases are not expanded when the shell is not interactive, |
| unless the @code{expand_aliases} shell option is set using |
| @code{shopt} (@pxref{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 @code{alias} |
| in compound commands. |
| |
| For almost every purpose, shell functions are preferred over aliases. |
| |
| @node Arrays |
| @section Arrays |
| @cindex arrays |
| |
| Bash provides one-dimensional indexed and associative array variables. |
| Any variable may be used as an indexed array; |
| the @code{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 (@pxref{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 |
| @example |
| name[@var{subscript}]=@var{value} |
| @end example |
| |
| @noindent |
| The @var{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 |
| @example |
| declare -a @var{name} |
| @end example |
| @noindent |
| The syntax |
| @example |
| declare -a @var{name}[@var{subscript}] |
| @end example |
| @noindent |
| is also accepted; the @var{subscript} is ignored. |
| |
| Associative arrays are created using |
| @example |
| declare -A @var{name}. |
| @end example |
| |
| Attributes may be |
| specified for an array variable using the @code{declare} and |
| @code{readonly} builtins. Each attribute applies to all members of |
| an array. |
| |
| Arrays are assigned to using compound assignments of the form |
| @example |
| name=(value@var{1} @dots{} value@var{n}) |
| @end example |
| @noindent |
| where each |
| @var{value} is of the form @code{[@var{subscript}]=}@var{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 @code{declare} |
| builtin. Individual array elements may be assigned to using the |
| @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above. |
| |
| Any element of an array may be referenced using |
| @code{$@{name[}@var{subscript}@code{]@}}. |
| The braces are required to avoid |
| conflicts with the shell's filename expansion operators. If the |
| @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members |
| of the array @var{name}. These subscripts differ only when the word |
| appears within double quotes. |
| If the word is double-quoted, |
| @code{$@{name[*]@}} expands to a single word with |
| the value of each array member separated by the first character of the |
| @env{IFS} variable, and @code{$@{name[@@]@}} expands each element of |
| @var{name} to a separate word. When there are no array members, |
| @code{$@{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 @samp{@@} and @samp{*}. |
| @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of |
| @code{$@{name[}@var{subscript}@code{]@}}. |
| If @var{subscript} is @samp{@@} or |
| @samp{*}, 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. |
| |
| The @code{unset} builtin is used to destroy arrays. |
| @code{unset} @var{name}[@var{subscript}] |
| destroys the array element at index @var{subscript}. |
| Care must be taken to avoid unwanted side effects caused by filename |
| generation. |
| @code{unset} @var{name}, where @var{name} is an array, removes the |
| entire array. A subscript of @samp{*} or @samp{@@} also removes the |
| entire array. |
| |
| The @code{declare}, @code{local}, and @code{readonly} |
| builtins each accept a @option{-a} option to specify an indexed |
| array and a @option{-A} option to specify an associative array. |
| The @code{read} builtin accepts a @option{-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 @code{set} and @code{declare} |
| builtins display array values in a way that allows them to be |
| reused as input. |
| |
| @node The Directory Stack |
| @section The Directory Stack |
| @cindex directory stack |
| |
| @menu |
| * Directory Stack Builtins:: Bash builtin commands to manipulate |
| the directory stack. |
| @end menu |
| |
| The directory stack is a list of recently-visited directories. The |
| @code{pushd} builtin adds directories to the stack as it changes |
| the current directory, and the @code{popd} builtin removes specified |
| directories from the stack and changes the current directory to |
| the directory removed. The @code{dirs} builtin displays the contents |
| of the directory stack. |
| |
| The contents of the directory stack are also visible |
| as the value of the @env{DIRSTACK} shell variable. |
| |
| @node Directory Stack Builtins |
| @subsection Directory Stack Builtins |
| |
| @table @code |
| |
| @item dirs |
| @btindex dirs |
| @example |
| dirs [+@var{N} | -@var{N}] [-clpv] |
| @end example |
| Display the list of currently remembered directories. Directories |
| are added to the list with the @code{pushd} command; the |
| @code{popd} command removes directories from the list. |
| @table @code |
| @item +@var{N} |
| Displays the @var{N}th directory (counting from the left of the |
| list printed by @code{dirs} when invoked without options), starting |
| with zero. |
| @item -@var{N} |
| Displays the @var{N}th directory (counting from the right of the |
| list printed by @code{dirs} when invoked without options), starting |
| with zero. |
| @item -c |
| Clears the directory stack by deleting all of the elements. |
| @item -l |
| Produces a longer listing; the default listing format uses a |
| tilde to denote the home directory. |
| @item -p |
| Causes @code{dirs} to print the directory stack with one entry per |
| line. |
| @item -v |
| Causes @code{dirs} to print the directory stack with one entry per |
| line, prefixing each entry with its index in the stack. |
| @end table |
| |
| @item popd |
| @btindex popd |
| @example |
| popd [+@var{N} | -@var{N}] [-n] |
| @end example |
| |
| Remove the top entry from the directory stack, and @code{cd} |
| to the new top directory. |
| When no arguments are given, @code{popd} |
| removes the top directory from the stack and |
| performs a @code{cd} to the new top directory. The |
| elements are numbered from 0 starting at the first directory listed with |
| @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}. |
| @table @code |
| @item +@var{N} |
| Removes the @var{N}th directory (counting from the left of the |
| list printed by @code{dirs}), starting with zero. |
| @item -@var{N} |
| Removes the @var{N}th directory (counting from the right of the |
| list printed by @code{dirs}), starting with zero. |
| @item -n |
| Suppresses the normal change of directory when removing directories |
| from the stack, so that only the stack is manipulated. |
| @end table |
| |
| @btindex pushd |
| @item pushd |
| @example |
| pushd [-n] [@var{+N} | @var{-N} | @var{dir} ] |
| @end example |
| |
| Save the current directory on the top of the directory stack |
| and then @code{cd} to @var{dir}. |
| With no arguments, @code{pushd} exchanges the top two directories. |
| |
| @table @code |
| @item -n |
| Suppresses the normal change of directory when adding directories |
| to the stack, so that only the stack is manipulated. |
| @item +@var{N} |
| Brings the @var{N}th directory (counting from the left of the |
| list printed by @code{dirs}, starting with zero) to the top of |
| the list by rotating the stack. |
| @item -@var{N} |
| Brings the @var{N}th directory (counting from the right of the |
| list printed by @code{dirs}, starting with zero) to the top of |
| the list by rotating the stack. |
| @item @var{dir} |
| Makes the current working directory be the top of the stack, and then |
| executes the equivalent of `@code{cd} @var{dir}'. |
| @code{cd}s to @var{dir}. |
| @end table |
| |
| @end table |
| |
| @node Printing a Prompt |
| @section Controlling the Prompt |
| @cindex prompting |
| |
| The value of the variable @env{PROMPT_COMMAND} is examined just before |
| Bash prints each primary prompt. If @env{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: |
| |
| @table @code |
| @item \a |
| A bell character. |
| @item \d |
| The date, in "Weekday Month Date" format (e.g., "Tue May 26"). |
| @item \D@{@var{format}@} |
| The @var{format} is passed to @code{strftime}(3) and the result is inserted |
| into the prompt string; an empty @var{format} results in a locale-specific |
| time representation. The braces are required. |
| @item \e |
| An escape character. |
| @item \h |
| The hostname, up to the first `.'. |
| @item \H |
| The hostname. |
| @item \j |
| The number of jobs currently managed by the shell. |
| @item \l |
| The basename of the shell's terminal device name. |
| @item \n |
| A newline. |
| @item \r |
| A carriage return. |
| @item \s |
| The name of the shell, the basename of @code{$0} (the portion |
| following the final slash). |
| @item \t |
| The time, in 24-hour HH:MM:SS format. |
| @item \T |
| The time, in 12-hour HH:MM:SS format. |
| @item \@@ |
| The time, in 12-hour am/pm format. |
| @item \A |
| The time, in 24-hour HH:MM format. |
| @item \u |
| The username of the current user. |
| @item \v |
| The version of Bash (e.g., 2.00) |
| @item \V |
| The release of Bash, version + patchlevel (e.g., 2.00.0) |
| @item \w |
| The current working directory, with @env{$HOME} abbreviated with a tilde |
| (uses the @env{$PROMPT_DIRTRIM} variable). |
| @item \W |
| The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde. |
| @item \! |
| The history number of this command. |
| @item \# |
| The command number of this command. |
| @item \$ |
| If the effective uid is 0, @code{#}, otherwise @code{$}. |
| @item \@var{nnn} |
| The character whose ASCII code is the octal value @var{nnn}. |
| @item \\ |
| A backslash. |
| @item \[ |
| Begin a sequence of non-printing characters. This could be used to |
| embed a terminal control sequence into the prompt. |
| @item \] |
| End a sequence of non-printing characters. |
| @end table |
| |
| 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 |
| (@pxref{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 |
| @code{promptvars} shell option (@pxref{Bash Builtins}). |
| |
| @node The Restricted Shell |
| @section The Restricted Shell |
| @cindex restricted shell |
| |
| If Bash is started with the name @code{rbash}, or the |
| @option{--restricted} |
| or |
| @option{-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 @code{bash} |
| with the exception that the following are disallowed or not performed: |
| |
| @itemize @bullet |
| @item |
| Changing directories with the @code{cd} builtin. |
| @item |
| Setting or unsetting the values of the @env{SHELL}, @env{PATH}, |
| @env{ENV}, or @env{BASH_ENV} variables. |
| @item |
| Specifying command names containing slashes. |
| @item |
| Specifying a filename containing a slash as an argument to the @code{.} |
| builtin command. |
| @item |
| Specifying a filename containing a slash as an argument to the @option{-p} |
| option to the @code{hash} builtin command. |
| @item |
| Importing function definitions from the shell environment at startup. |
| @item |
| Parsing the value of @env{SHELLOPTS} from the shell environment at startup. |
| @item |
| Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, |
| @samp{&>}, and @samp{>>} redirection operators. |
| @item |
| Using the @code{exec} builtin to replace the shell with another command. |
| @item |
| Adding or deleting builtin commands with the |
| @option{-f} and @option{-d} options to the @code{enable} builtin. |
| @item |
| Using the @code{enable} builtin command to enable disabled shell builtins. |
| @item |
| Specifying the @option{-p} option to the @code{command} builtin. |
| @item |
| Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}. |
| @end itemize |
| |
| These restrictions are enforced after any startup files are read. |
| |
| When a command that is found to be a shell script is executed |
| (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in |
| the shell spawned to execute the script. |
| |
| @node Bash POSIX Mode |
| @section Bash POSIX Mode |
| @cindex POSIX Mode |
| |
| Starting Bash with the @option{--posix} command-line option or executing |
| @samp{set -o posix} while Bash is running will cause Bash to conform more |
| closely to the @sc{posix} standard by changing the behavior to |
| match that specified by @sc{posix} in areas where the Bash default differs. |
| |
| When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the |
| startup files. |
| |
| The following list is what's changed when `@sc{posix} mode' is in effect: |
| |
| @enumerate |
| @item |
| When a command in the hash table no longer exists, Bash will re-search |
| @env{$PATH} to find the new location. This is also available with |
| @samp{shopt -s checkhash}. |
| |
| @item |
| The message printed by the job control code and builtins when a job |
| exits with a non-zero status is `Done(status)'. |
| |
| @item |
| The message printed by the job control code and builtins when a job |
| is stopped is `Stopped(@var{signame})', where @var{signame} is, for |
| example, @code{SIGTSTP}. |
| |
| @item |
| The @code{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. |
| |
| @item |
| Reserved words appearing in a context where reserved words are recognized |
| do not undergo alias expansion. |
| |
| @item |
| The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to |
| the history number and @samp{!!} to @samp{!} are enabled, |
| and parameter expansion is performed on the values of @env{PS1} and |
| @env{PS2} regardless of the setting of the @code{promptvars} option. |
| |
| @item |
| The @sc{posix} startup files are executed (@env{$ENV}) rather than |
| the normal Bash files. |
| |
| @item |
| Tilde expansion is only performed on assignments preceding a command |
| name, rather than on all assignment statements on the line. |
| |
| @item |
| The default history file is @file{~/.sh_history} (this is the |
| default value of @env{$HISTFILE}). |
| |
| @item |
| The output of @samp{kill -l} prints all the signal names on a single line, |
| separated by spaces, without the @samp{SIG} prefix. |
| |
| @item |
| The @code{kill} builtin does not accept signal names with a @samp{SIG} |
| prefix. |
| |
| @item |
| Non-interactive shells exit if @var{filename} in @code{.} @var{filename} |
| is not found. |
| |
| @item |
| Non-interactive shells exit if a syntax error in an arithmetic expansion |
| results in an invalid expression. |
| |
| @item |
| Redirection operators do not perform filename expansion on the word |
| in the redirection unless the shell is interactive. |
| |
| @item |
| Redirection operators do not perform word splitting on the word in the |
| redirection. |
| |
| @item |
| Function names must be valid shell @code{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. |
| |
| @item |
| @sc{posix} special builtins are found before shell functions |
| during command lookup. |
| |
| @item |
| If a @sc{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. |
| |
| @item |
| If @env{CDPATH} is set, the @code{cd} builtin will not implicitly |
| append the current directory to it. This means that @code{cd} will |
| fail if no valid directory name can be constructed from |
| any of the entries in @env{$CDPATH}, even if the a directory with |
| the same name as the name given as an argument to @code{cd} exists |
| in the current directory. |
| |
| @item |
| 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. |
| |
| @item |
| A non-interactive shell exits with an error status if the iteration |
| variable in a @code{for} statement or the selection variable in a |
| @code{select} statement is a readonly variable. |
| |
| @item |
| Process substitution is not available. |
| |
| @item |
| Assignment statements preceding @sc{posix} special builtins |
| persist in the shell environment after the builtin completes. |
| |
| @item |
| Assignment statements preceding shell function calls persist in the |
| shell environment after the function returns, as if a @sc{posix} |
| special builtin command had been executed. |
| |
| @item |
| The @code{export} and @code{readonly} builtin commands display their |
| output in the format required by @sc{posix}. |
| |
| @item |
| The @code{trap} builtin displays signal names without the leading |
| @code{SIG}. |
| |
| @item |
| The @code{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 @samp{-} as the |
| first argument. |
| |
| @item |
| The @code{.} and @code{source} builtins do not search the current directory |
| for the filename argument if it is not found by searching @env{PATH}. |
| |
| @item |
| Subshells spawned to execute command substitutions inherit the value of |
| the @option{-e} option from the parent shell. When not in @sc{posix} mode, |
| Bash clears the @option{-e} option in such subshells. |
| |
| @item |
| Alias expansion is always enabled, even in non-interactive shells. |
| |
| @item |
| When the @code{alias} builtin displays alias definitions, it does not |
| display them with a leading @samp{alias } unless the @option{-p} option |
| is supplied. |
| |
| @item |
| When the @code{set} builtin is invoked without options, it does not display |
| shell function names and definitions. |
| |
| @item |
| When the @code{set} builtin is invoked without options, it displays |
| variable values without quotes, unless they contain shell metacharacters, |
| even if the result contains nonprinting characters. |
| |
| @item |
| When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname |
| constructed from @code{$PWD} and the directory name supplied as an argument |
| does not refer to an existing directory, @code{cd} will fail instead of |
| falling back to @var{physical} mode. |
| |
| @item |
| When the @code{pwd} builtin is supplied the @option{-P} option, it resets |
| @code{$PWD} to a pathname containing no symlinks. |
| |
| @item |
| The @code{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 |
| @option{-P} option. |
| |
| @item |
| When listing the history, the @code{fc} builtin does not include an |
| indication of whether or not a history entry has been modified. |
| |
| @item |
| The default editor used by @code{fc} is @code{ed}. |
| |
| @item |
| The @code{type} and @code{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 @code{$PATH}. |
| |
| @item |
| The @code{vi} editing mode will invoke the @code{vi} editor directly when |
| the @samp{v} command is run, instead of checking @code{$VISUAL} and |
| @code{$EDITOR}. |
| |
| @item |
| When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret |
| any arguments to @code{echo} as options. Each argument is displayed, after |
| escape characters are converted. |
| |
| @item |
| The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c} |
| and @option{-f} options. |
| |
| @end enumerate |
| |
| There is other @sc{posix} behavior that Bash does not implement by |
| default even when in @sc{posix} mode. |
| Specifically: |
| |
| @enumerate |
| |
| @item |
| The @code{fc} builtin checks @code{$EDITOR} as a program to edit history |
| entries if @code{FCEDIT} is unset, rather than defaulting directly to |
| @code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset. |
| |
| @item |
| As noted above, Bash requires the @code{xpg_echo} option to be enabled for |
| the @code{echo} builtin to be fully conformant. |
| |
| @end enumerate |
| |
| Bash can be configured to be @sc{posix}-conformant by default, by specifying |
| the @option{--enable-strict-posix-default} to @code{configure} when building |
| (@pxref{Optional Features}). |
| |
| @node Job Control |
| @chapter 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. |
| @end menu |
| |
| @node Job Control Basics |
| @section Job Control Basics |
| @cindex job control |
| @cindex foreground |
| @cindex background |
| @cindex suspending jobs |
| |
| 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 system's terminal driver and Bash. |
| |
| The shell associates a @var{job} with each pipeline. It keeps a |
| table of currently executing jobs, which may be listed with the |
| @code{jobs} command. When Bash starts a job |
| asynchronously, it prints a line that looks |
| like: |
| @example |
| [1] 25647 |
| @end example |
| @noindent |
| indicating that this job is job number 1 and that the process @sc{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 @var{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 @sc{id}. Members of this process group (processes whose |
| process group @sc{id} is equal to the current terminal process group |
| @sc{id}) receive keyboard-generated signals such as @code{SIGINT}. |
| These processes are said to be in the foreground. Background |
| processes are those whose process group @sc{id} differs from the |
| terminal's; such processes are immune to keyboard-generated |
| signals. Only foreground processes are allowed to read from or |
| write to the terminal. Background processes which attempt to |
| read from (write to) the terminal are sent a @code{SIGTTIN} |
| (@code{SIGTTOU}) signal by the 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 |
| @var{suspend} character (typically @samp{^Z}, Control-Z) while a |
| process is running causes that process to be stopped and returns |
| control to Bash. Typing the @var{delayed suspend} character |
| (typically @samp{^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 @code{bg} command to continue it in the |
| background, the @code{fg} command to continue it in the |
| foreground, or the @code{kill} command to kill it. A @samp{^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 @samp{%} introduces a job specification (@var{jobspec}). |
| |
| Job number @code{n} may be referred to as @samp{%n}. |
| The symbols @samp{%%} and @samp{%+} 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 @samp{%} (with no accompanying job specification) also refers |
| to the current job. |
| The previous job may be referenced using @samp{%-}. |
| If there is only a single job, @samp{%+} and @samp{%-} can both be used |
| to refer to that job. |
| In output pertaining to jobs (e.g., the output of the @code{jobs} |
| command), the current job is always flagged with a @samp{+}, and the |
| previous job with a @samp{-}. |
| |
| 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, @samp{%ce} refers |
| to a stopped @code{ce} job. Using @samp{%?ce}, on the |
| other hand, refers to any job containing the string @samp{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: |
| @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the |
| background into the foreground. Similarly, @samp{%1 &} resumes |
| job 1 in the background, equivalent to @samp{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 @option{-b} option to the @code{set} builtin is enabled, |
| Bash reports such changes immediately (@pxref{The Set Builtin}). |
| Any trap on @code{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 @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the |
| shell prints a warning message, and if the @code{checkjobs} option is |
| enabled, lists the jobs and their statuses. |
| The @code{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. |
| |
| @node Job Control Builtins |
| @section Job Control Builtins |
| |
| @table @code |
| |
| @item bg |
| @btindex bg |
| @example |
| bg [@var{jobspec} @dots{}] |
| @end example |
| Resume each suspended job @var{jobspec} in the background, as if it |
| had been started with @samp{&}. |
| If @var{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 |
| @var{jobspec} was not found or specifies a job |
| that was started without job control. |
| |
| @item fg |
| @btindex fg |
| @example |
| fg [@var{jobspec}] |
| @end example |
| Resume the job @var{jobspec} in the foreground and make it the current job. |
| If @var{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, @var{jobspec} does not specify a valid job or |
| @var{jobspec} specifies a job that was started without job control. |
| |
| @item jobs |
| @btindex jobs |
| @example |
| jobs [-lnprs] [@var{jobspec}] |
| jobs -x @var{command} [@var{arguments}] |
| @end example |
| |
| The first form lists the active jobs. The options have the |
| following meanings: |
| |
| @table @code |
| @item -l |
| List process @sc{id}s in addition to the normal information. |
| |
| @item -n |
| Display information only about jobs that have changed status since |
| the user was last notified of their status. |
| |
| @item -p |
| List only the process @sc{id} of the job's process group leader. |
| |
| @item -r |
| Restrict output to running jobs. |
| |
| @item -s |
| Restrict output to stopped jobs. |
| @end table |
| |
| If @var{jobspec} is given, |
| output is restricted to information about that job. |
| If @var{jobspec} is not supplied, the status of all jobs is |
| listed. |
| |
| If the @option{-x} option is supplied, @code{jobs} replaces any |
| @var{jobspec} found in @var{command} or @var{arguments} with the |
| corresponding process group @sc{id}, and executes @var{command}, |
| passing it @var{argument}s, returning its exit status. |
| |
| @item kill |
| @btindex kill |
| @example |
| kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid} |
| kill -l [@var{exit_status}] |
| @end example |
| Send a signal specified by @var{sigspec} or @var{signum} to the process |
| named by job specification @var{jobspec} or process @sc{id} @var{pid}. |
| @var{sigspec} is either a case-insensitive signal name such as |
| @code{SIGINT} (with or without the @code{SIG} prefix) |
| or a signal number; @var{signum} is a signal number. |
| If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used. |
| The @option{-l} option lists the signal names. |
| If any arguments are supplied when @option{-l} is given, the names of the |
| signals corresponding to the arguments are listed, and the return status |
| is zero. |
| @var{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. |
| |
| @item wait |
| @btindex wait |
| @example |
| wait [@var{jobspec} or @var{pid} ...] |
| @end example |
| Wait until the child process specified by each process @sc{id} @var{pid} |
| or job specification @var{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 @var{jobspec} nor @var{pid} specifies an active child process |
| of the shell, the return status is 127. |
| |
| @item disown |
| @btindex disown |
| @example |
| disown [-ar] [-h] [@var{jobspec} @dots{}] |
| @end example |
| Without options, each @var{jobspec} is removed from the table of |
| active jobs. |
| If the @option{-h} option is given, the job is not removed from the table, |
| but is marked so that @code{SIGHUP} is not sent to the job if the shell |
| receives a @code{SIGHUP}. |
| If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r} |
| option is supplied, the current job is used. |
| If no @var{jobspec} is supplied, the @option{-a} option means to remove or |
| mark all jobs; the @option{-r} option without a @var{jobspec} |
| argument restricts operation to running jobs. |
| |
| @item suspend |
| @btindex suspend |
| @example |
| suspend [-f] |
| @end example |
| Suspend the execution of this shell until it receives a |
| @code{SIGCONT} signal. |
| A login shell cannot be suspended; the @option{-f} |
| option can be used to override this and force the suspension. |
| |
| @end table |
| |
| When job control is not active, the @code{kill} and @code{wait} |
| builtins do not accept @var{jobspec} arguments. They must be |
| supplied process @sc{id}s. |
| |
| @node Job Control Variables |
| @section Job Control Variables |
| |
| @vtable @code |
| |
| @item 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 @samp{exact}, |
| the string supplied must match the name of a stopped job exactly; |
| if set to @samp{substring}, |
| the string supplied needs to match a substring of the name of a |
| stopped job. The @samp{substring} value provides functionality |
| analogous to the @samp{%?} job @sc{id} (@pxref{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 @samp{%} job @sc{id}. |
| |
| @end vtable |
| |
| @set readline-appendix |
| @set history-appendix |
| @cindex Readline, how to use |
| @include rluser.texi |
| @cindex History, how to use |
| @include hsuser.texi |
| @clear readline-appendix |
| @clear history-appendix |
| |
| @node Installing Bash |
| @chapter Installing Bash |
| |
| This chapter provides basic instructions for installing Bash on |
| the various supported platforms. The distribution supports the |
| @sc{gnu} operating systems, nearly every version of Unix, and several |
| non-Unix systems such as BeOS and Interix. |
| Other independent ports exist for |
| @sc{ms-dos}, @sc{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. |
| @end menu |
| |
| @node Basic Installation |
| @section Basic Installation |
| @cindex installation |
| @cindex configuration |
| @cindex Bash installation |
| @cindex Bash configuration |
| |
| These are installation instructions for Bash. |
| |
| The simplest way to compile Bash is: |
| |
| @enumerate |
| @item |
| @code{cd} to the directory containing the source code and type |
| @samp{./configure} to configure Bash for your system. If you're |
| using @code{csh} on an old version of System V, you might need to |
| type @samp{sh ./configure} instead to prevent @code{csh} from trying |
| to execute @code{configure} itself. |
| |
| Running @code{configure} takes some time. |
| While running, it prints messages telling which features it is |
| checking for. |
| |
| @item |
| Type @samp{make} to compile Bash and build the @code{bashbug} bug |
| reporting script. |
| |
| @item |
| Optionally, type @samp{make tests} to run the Bash test suite. |
| |
| @item |
| Type @samp{make install} to install @code{bash} and @code{bashbug}. |
| This will also install the manual pages and Info file. |
| |
| @end enumerate |
| |
| The @code{configure} shell script attempts to guess correct |
| values for various system-dependent variables used during |
| compilation. It uses those values to create a @file{Makefile} in |
| each directory of the package (the top directory, the |
| @file{builtins}, @file{doc}, and @file{support} directories, |
| each directory under @file{lib}, and several others). It also creates a |
| @file{config.h} file containing system-dependent definitions. |
| Finally, it creates a shell script named @code{config.status} that you |
| can run in the future to recreate the current configuration, a |
| file @file{config.cache} that saves the results of its tests to |
| speed up reconfiguring, and a file @file{config.log} containing |
| compiler output (useful mainly for debugging @code{configure}). |
| If at some point |
| @file{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 |
| @code{configure} script understands, type |
| |
| @example |
| bash-2.04$ ./configure --help |
| @end example |
| |
| @noindent |
| 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 @code{configure} could check whether or not |
| to do them, and mail diffs or instructions to |
| @email{bash-maintainers@@gnu.org} so they can be |
| considered for the next release. |
| |
| The file @file{configure.in} is used to create @code{configure} |
| by a program called Autoconf. You only need |
| @file{configure.in} if you want to change it or regenerate |
| @code{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 @samp{make clean}. To also remove the |
| files that @code{configure} created (so you can compile Bash for |
| a different kind of computer), type @samp{make distclean}. |
| |
| @node Compilers and Options |
| @section Compilers and Options |
| |
| Some systems require unusual options for compilation or linking |
| that the @code{configure} script does not know about. You can |
| give @code{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: |
| |
| @example |
| CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure |
| @end example |
| |
| On systems that have the @code{env} program, you can do it like this: |
| |
| @example |
| env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure |
| @end example |
| |
| The configuration process uses GCC to build Bash if it |
| is available. |
| |
| @node Compiling For Multiple Architectures |
| @section 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 @code{make} that |
| supports the @code{VPATH} variable, such as GNU @code{make}. |
| @code{cd} to the |
| directory where you want the object files and executables to go and run |
| the @code{configure} script from the source directory. You may need to |
| supply the @option{--srcdir=PATH} argument to tell @code{configure} where the |
| source files are. @code{configure} automatically checks for the |
| source code in the directory that @code{configure} is in and in `..'. |
| |
| If you have to use a @code{make} that does not supports the @code{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 @samp{make distclean} before |
| reconfiguring for another architecture. |
| |
| Alternatively, if your system supports symbolic links, you can use the |
| @file{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 @file{/usr/gnu/src/bash-2.0}: |
| |
| @example |
| bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . |
| @end example |
| |
| @noindent |
| The @code{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. |
| |
| @node Installation Names |
| @section Installation Names |
| |
| By default, @samp{make install} will install into |
| @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can |
| specify an installation prefix other than @file{/usr/local} by |
| giving @code{configure} the option @option{--prefix=@var{PATH}}, |
| or by specifying a value for the @code{DESTDIR} @samp{make} |
| variable when running @samp{make install}. |
| |
| You can specify separate installation prefixes for |
| architecture-specific files and architecture-independent files. |
| If you give @code{configure} the option |
| @option{--exec-prefix=@var{PATH}}, @samp{make install} will use |
| @var{PATH} as the prefix for installing programs and libraries. |
| Documentation and other data files will still use the regular prefix. |
| |
| @node Specifying the System Type |
| @section Specifying the System Type |
| |
| There may be some features @code{configure} can not figure out |
| automatically, but need to determine by the type of host Bash |
| will run on. Usually @code{configure} can figure that |
| out, but if it prints a message saying it can not guess the host |
| type, give it the @option{--host=TYPE} option. @samp{TYPE} can |
| either be a short name for the system type, such as @samp{sun4}, |
| or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} |
| (e.g., @samp{i386-unknown-freebsd4.2}). |
| |
| See the file @file{support/config.sub} for the possible |
| values of each field. |
| |
| @node Sharing Defaults |
| @section Sharing Defaults |
| |
| If you want to set default values for @code{configure} scripts to |
| share, you can create a site shell script called |
| @code{config.site} that gives default values for variables like |
| @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} |
| looks for @file{PREFIX/share/config.site} if it exists, then |
| @file{PREFIX/etc/config.site} if it exists. Or, you can set the |
| @code{CONFIG_SITE} environment variable to the location of the site |
| script. A warning: the Bash @code{configure} looks for a site script, |
| but not all @code{configure} scripts do. |
| |
| @node Operation Controls |
| @section Operation Controls |
| |
| @code{configure} recognizes the following options to control how it |
| operates. |
| |
| @table @code |
| |
| @item --cache-file=@var{file} |
| Use and save the results of the tests in |
| @var{file} instead of @file{./config.cache}. Set @var{file} to |
| @file{/dev/null} to disable caching, for debugging |
| @code{configure}. |
| |
| @item --help |
| Print a summary of the options to @code{configure}, and exit. |
| |
| @item --quiet |
| @itemx --silent |
| @itemx -q |
| Do not print messages saying which checks are being made. |
| |
| @item --srcdir=@var{dir} |
| Look for the Bash source code in directory @var{dir}. Usually |
| @code{configure} can determine that directory automatically. |
| |
| @item --version |
| Print the version of Autoconf used to generate the @code{configure} |
| script, and exit. |
| @end table |
| |
| @code{configure} also accepts some other, not widely used, boilerplate |
| options. @samp{configure --help} prints the complete list. |
| |
| @node Optional Features |
| @section Optional Features |
| |
| The Bash @code{configure} has a number of @option{--enable-@var{feature}} |
| options, where @var{feature} indicates an optional part of Bash. |
| There are also several @option{--with-@var{package}} options, |
| where @var{package} is something like @samp{bash-malloc} or @samp{purify}. |
| To turn off the default use of a package, use |
| @option{--without-@var{package}}. To configure Bash without a feature |
| that is enabled by default, use @option{--disable-@var{feature}}. |
| |
| Here is a complete list of the @option{--enable-} and |
| @option{--with-} options that the Bash @code{configure} recognizes. |
| |
| @table @code |
| @item --with-afs |
| Define if you are using the Andrew File System from Transarc. |
| |
| @item --with-bash-malloc |
| Use the Bash version of |
| @code{malloc} in the directory @file{lib/malloc}. This is not the same |
| @code{malloc} that appears in @sc{gnu} libc, but an older version |
| originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} |
| is very fast, but wastes some space on each allocation. |
| This option is enabled by default. |
| The @file{NOTES} file contains a list of systems for |
| which this should be turned off, and @code{configure} disables this |
| option automatically for a number of systems. |
| |
| @item --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. |
| |
| @item --with-gnu-malloc |
| A synonym for @code{--with-bash-malloc}. |
| |
| @item --with-installed-readline[=@var{PREFIX}] |
| Define this to make Bash link with a locally-installed version of Readline |
| rather than the version in @file{lib/readline}. This works only with |
| Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not |
| supplied, @code{configure} uses the values of the make variables |
| @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix} |
| by default, to find the installed version of Readline if it is not in |
| the standard system include and library directories. |
| If @var{PREFIX} is @code{no}, Bash links with the version in |
| @file{lib/readline}. |
| If @var{PREFIX} is set to any other value, @code{configure} treats it as |
| a directory pathname and looks for |
| the installed version of Readline in subdirectories of that directory |
| (include files in @var{PREFIX}/@code{include} and the library in |
| @var{PREFIX}/@code{lib}). |
| |
| @item --with-purify |
| Define this to use the Purify memory allocation checker from Rational |
| Software. |
| |
| @item --enable-minimal-config |
| This produces a shell with minimal features, close to the historical |
| Bourne shell. |
| @end table |
| |
| There are several @option{--enable-} options that alter how Bash is |
| compiled and linked, rather than changing run-time features. |
| |
| @table @code |
| @item --enable-largefile |
| Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html, |
| large files} 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. |
| |
| @item --enable-profiling |
| This builds a Bash binary that produces profiling information to be |
| processed by @code{gprof} each time it is executed. |
| |
| @item --enable-static-link |
| This causes Bash to be linked statically, if @code{gcc} is being used. |
| This could be used to build a version to use as root's shell. |
| @end table |
| |
| The @samp{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 @samp{enable-@var{feature}}. |
| |
| All of the following options except for @samp{disabled-builtins} and |
| @samp{xpg-echo-default} are |
| enabled by default, unless the operating system does not provide the |
| necessary support. |
| |
| @table @code |
| @item --enable-alias |
| Allow alias expansion and include the @code{alias} and @code{unalias} |
| builtins (@pxref{Aliases}). |
| |
| @item --enable-arith-for-command |
| Include support for the alternate form of the @code{for} command |
| that behaves like the C language @code{for} statement |
| (@pxref{Looping Constructs}). |
| |
| @item --enable-array-variables |
| Include support for one-dimensional array shell variables |
| (@pxref{Arrays}). |
| |
| @item --enable-bang-history |
| Include support for @code{csh}-like history substitution |
| (@pxref{History Interaction}). |
| |
| @item --enable-brace-expansion |
| Include @code{csh}-like brace expansion |
| ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). |
| See @ref{Brace Expansion}, for a complete description. |
| |
| @item --enable-casemod-attributes |
| Include support for case-modifying attributes in the @code{declare} builtin |
| and assignment statements. Variables with the @var{uppercase} attribute, |
| for example, will have their values converted to uppercase upon assignment. |
| |
| @item --enable-casemod-expansion |
| Include support for case-modifying word expansions. |
| |
| @item --enable-command-timing |
| Include support for recognizing @code{time} as a reserved word and for |
| displaying timing statistics for the pipeline following @code{time} |
| (@pxref{Pipelines}). |
| This allows pipelines as well as shell builtins and functions to be timed. |
| |
| @item --enable-cond-command |
| Include support for the @code{[[} conditional command. |
| (@pxref{Conditional Constructs}). |
| |
| @item --enable-cond-regexp |
| Include support for matching POSIX regular expressions using the |
| @samp{=~} binary operator in the @code{[[} conditional command. |
| (@pxref{Conditional Constructs}). |
| |
| @item --enable-coprocesses |
| Include support for coprocesses and the @code{coproc} reserved word |
| (@pxref{Pipelines}). |
| |
| @item --enable-debugger |
| Include support for the bash debugger (distributed separately). |
| |
| @item --enable-directory-stack |
| Include support for a @code{csh}-like directory stack and the |
| @code{pushd}, @code{popd}, and @code{dirs} builtins |
| (@pxref{The Directory Stack}). |
| |
| @item --enable-disabled-builtins |
| Allow builtin commands to be invoked via @samp{builtin xxx} |
| even after @code{xxx} has been disabled using @samp{enable -n xxx}. |
| See @ref{Bash Builtins}, for details of the @code{builtin} and |
| @code{enable} builtin commands. |
| |
| @item --enable-dparen-arithmetic |
| Include support for the @code{((@dots{}))} command |
| (@pxref{Conditional Constructs}). |
| |
| @item --enable-extended-glob |
| Include support for the extended pattern matching features described |
| above under @ref{Pattern Matching}. |
| |
| @item --enable-help-builtin |
| Include the @code{help} builtin, which displays help on shell builtins and |
| variables (@pxref{Bash Builtins}). |
| |
| @item --enable-history |
| Include command history and the @code{fc} and @code{history} |
| builtin commands (@pxref{Bash History Facilities}). |
| |
| @item --enable-job-control |
| This enables the job control features (@pxref{Job Control}), |
| if the operating system supports them. |
| |
| @item --enable-multibyte |
| This enables support for multibyte characters if the operating |
| system provides the necessary support. |
| |
| @item --enable-net-redirections |
| This enables the special handling of filenames of the form |
| @code{/dev/tcp/@var{host}/@var{port}} and |
| @code{/dev/udp/@var{host}/@var{port}} |
| when used in redirections (@pxref{Redirections}). |
| |
| @item --enable-process-substitution |
| This enables process substitution (@pxref{Process Substitution}) if |
| the operating system provides the necessary support. |
| |
| @item --enable-progcomp |
| Enable the programmable completion facilities |
| (@pxref{Programmable Completion}). |
| If Readline is not enabled, this option has no effect. |
| |
| @item --enable-prompt-string-decoding |
| Turn on the interpretation of a number of backslash-escaped characters |
| in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt |
| strings. See @ref{Printing a Prompt}, for a complete list of prompt |
| string escape sequences. |
| |
| @item --enable-readline |
| Include support for command-line editing and history with the Bash |
| version of the Readline library (@pxref{Command Line Editing}). |
| |
| @item --enable-restricted |
| Include support for a @dfn{restricted shell}. If this is enabled, Bash, |
| when called as @code{rbash}, enters a restricted mode. See |
| @ref{The Restricted Shell}, for a description of restricted mode. |
| |
| @item --enable-select |
| Include the @code{select} builtin, which allows the generation of simple |
| menus (@pxref{Conditional Constructs}). |
| |
| @item --enable-separate-helpfiles |
| Use external files for the documentation displayed by the @code{help} builtin |
| instead of storing the text internally. |
| |
| @item --enable-single-help-strings |
| Store the text displayed by the @code{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. |
| |
| @item --enable-strict-posix-default |
| Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}). |
| |
| @item --enable-usg-echo-default |
| A synonym for @code{--enable-xpg-echo-default}. |
| |
| @item --enable-xpg-echo-default |
| Make the @code{echo} builtin expand backslash-escaped characters by default, |
| without requiring the @option{-e} option. |
| This sets the default value of the @code{xpg_echo} shell option to @code{on}, |
| which makes the Bash @code{echo} behave more like the version specified in |
| the Single Unix Specification, version 3. |
| @xref{Bash Builtins}, for a description of the escape sequences that |
| @code{echo} recognizes. |
| |
| @end table |
| |
| The file @file{config-top.h} contains C Preprocessor |
| @samp{#define} statements for options which are not settable from |
| @code{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. |
| |
| @node Reporting Bugs |
| @appendix 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 |
| @uref{ftp://ftp.gnu.org/pub/bash/}. |
| |
| Once you have determined that a bug actually exists, use the |
| @code{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 @email{bug-bash@@gnu.org} or posted to the Usenet |
| newsgroup @code{gnu.bash.bug}. |
| |
| All bug reports should include: |
| @itemize @bullet |
| @item |
| The version number of Bash. |
| @item |
| The hardware and operating system. |
| @item |
| The compiler used to compile Bash. |
| @item |
| A description of the bug behaviour. |
| @item |
| A short script or `recipe' which exercises the bug and may be used |
| to reproduce it. |
| @end itemize |
| |
| @noindent |
| @code{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 |
| @email{chet.ramey@@case.edu}. |
| |
| @node Major Differences From The Bourne Shell |
| @appendix 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 @sc{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 @code{sh} included in SVR4.2 (the |
| last version of the historical Bourne shell) as the baseline reference. |
| |
| @itemize @bullet |
| |
| @item |
| Bash is @sc{posix}-conformant, even where the @sc{posix} specification |
| differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}). |
| |
| @item |
| Bash has multi-character invocation options (@pxref{Invoking Bash}). |
| |
| @item |
| Bash has command-line editing (@pxref{Command Line Editing}) and |
| the @code{bind} builtin. |
| |
| @item |
| Bash provides a programmable word completion mechanism |
| (@pxref{Programmable Completion}), and builtin commands |
| @code{complete}, @code{compgen}, and @code{compopt}, to |
| manipulate it. |
| |
| @item |
| Bash has command history (@pxref{Bash History Facilities}) and the |
| @code{history} and @code{fc} builtins to manipulate it. |
| The Bash history list maintains timestamp information and uses the |
| value of the @code{HISTTIMEFORMAT} variable to display it. |
| |
| @item |
| Bash implements @code{csh}-like history expansion |
| (@pxref{History Interaction}). |
| |
| @item |
| Bash has one-dimensional array variables (@pxref{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. |
| |
| @item |
| The @code{$'@dots{}'} quoting syntax, which expands ANSI-C |
| backslash-escaped characters in the text between the single quotes, |
| is supported (@pxref{ANSI-C Quoting}). |
| |
| @item |
| Bash supports the @code{$"@dots{}"} quoting syntax to do |
| locale-specific translation of the characters between the double |
| quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings} |
| invocation options list the translatable strings found in a script |
| (@pxref{Locale Translation}). |
| |
| @item |
| Bash implements the @code{!} keyword to negate the return value of |
| a pipeline (@pxref{Pipelines}). |
| Very useful when an @code{if} statement needs to act only if a test fails. |
| The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to |
| return a failure status if any command fails. |
| |
| @item |
| Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}). |
| The display of the timing statistics may be controlled with the |
| @env{TIMEFORMAT} variable. |
| |
| @item |
| Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))} |
| arithmetic for command, similar to the C language (@pxref{Looping Constructs}). |
| |
| @item |
| Bash includes the @code{select} compound command, which allows the |
| generation of simple menus (@pxref{Conditional Constructs}). |
| |
| @item |
| Bash includes the @code{[[} compound command, which makes conditional |
| testing part of the shell grammar (@pxref{Conditional Constructs}), including |
| optional regular expression matching. |
| |
| @item |
| Bash provides optional case-insensitive matching for the @code{case} and |
| @code{[[} constructs. |
| |
| @item |
| Bash includes brace expansion (@pxref{Brace Expansion}) and tilde |
| expansion (@pxref{Tilde Expansion}). |
| |
| @item |
| Bash implements command aliases and the @code{alias} and @code{unalias} |
| builtins (@pxref{Aliases}). |
| |
| @item |
| Bash provides shell arithmetic, the @code{((} compound command |
| (@pxref{Conditional Constructs}), |
| and arithmetic expansion (@pxref{Shell Arithmetic}). |
| |
| @item |
| 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 @code{export} |
| command. |
| |
| @item |
| Bash supports the @samp{+=} assignment operator, which appends to the value |
| of the variable named on the left hand side. |
| |
| @item |
| Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%} |
| and @samp{##} expansions to remove leading or trailing substrings from |
| variable values (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}}, |
| is supported (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}}, |
| which expands to the substring of @code{var}'s value of length |
| @var{length}, beginning at @var{offset}, is present |
| (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| The expansion |
| @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, |
| which matches @var{pattern} and replaces it with @var{replacement} in |
| the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to |
| the names of all shell variables whose names begin with @var{prefix}, |
| is available (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| Bash has @var{indirect} variable expansion using @code{$@{!word@}} |
| (@pxref{Shell Parameter Expansion}). |
| |
| @item |
| Bash can expand positional parameters beyond @code{$9} using |
| @code{$@{@var{num}@}}. |
| |
| @item |
| The @sc{posix} @code{$()} form of command substitution |
| is implemented (@pxref{Command Substitution}), |
| and preferred to the Bourne shell's @code{``} (which |
| is also implemented for backwards compatibility). |
| |
| @item |
| Bash has process substitution (@pxref{Process Substitution}). |
| |
| @item |
| Bash automatically assigns variables that provide information about the |
| current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host |
| (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}), |
| and the instance of Bash that is running (@env{BASH}, |
| @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables}, |
| for details. |
| |
| @item |
| The @env{IFS} variable is used to split only the results of expansion, |
| not all words (@pxref{Word Splitting}). |
| This closes a longstanding shell security hole. |
| |
| @item |
| Bash implements the full set of @sc{posix} filename expansion operators, |
| including @var{character classes}, @var{equivalence classes}, and |
| @var{collating symbols} (@pxref{Filename Expansion}). |
| |
| @item |
| Bash implements extended pattern matching features when the @code{extglob} |
| shell option is enabled (@pxref{Pattern Matching}). |
| |
| @item |
| It is possible to have a variable and a function with the same name; |
| @code{sh} does not separate the two name spaces. |
| |
| @item |
| Bash functions are permitted to have local variables using the |
| @code{local} builtin, and thus useful recursive functions may be written |
| (@pxref{Bash Builtins}). |
| |
| @item |
| Variable assignments preceding commands affect only that command, even |
| builtins and functions (@pxref{Environment}). |
| In @code{sh}, all variable assignments |
| preceding commands are global unless the command is executed from the |
| file system. |
| |
| @item |
| Bash performs filename expansion on filenames specified as operands |
| to input and output redirection operators (@pxref{Redirections}). |
| |
| @item |
| Bash contains the @samp{<>} redirection operator, allowing a file to be |
| opened for both reading and writing, and the @samp{&>} redirection |
| operator, for directing standard output and standard error to the same |
| file (@pxref{Redirections}). |
| |
| @item |
| Bash includes the @samp{<<<} redirection operator, allowing a string to |
| be used as the standard input to a command. |
| |
| @item |
| Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}} |
| redirection operators, which move one file descriptor to another. |
| |
| @item |
| Bash treats a number of filenames specially when they are |
| used in redirection operators (@pxref{Redirections}). |
| |
| @item |
| Bash can open network connections to arbitrary machines and services |
| with the redirection operators (@pxref{Redirections}). |
| |
| @item |
| The @code{noclobber} option is available to avoid overwriting existing |
| files with output redirection (@pxref{The Set Builtin}). |
| The @samp{>|} redirection operator may be used to override @code{noclobber}. |
| |
| @item |
| The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins}) |
| each take @option{-L} and @option{-P} options to switch between logical and |
| physical modes. |
| |
| @item |
| 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 |
| @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). |
| |
| @item |
| The @code{command} builtin allows selective disabling of functions |
| when command lookup is performed (@pxref{Bash Builtins}). |
| |
| @item |
| Individual builtins may be enabled or disabled using the @code{enable} |
| builtin (@pxref{Bash Builtins}). |
| |
| @item |
| The Bash @code{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 |
| (@pxref{Bourne Shell Builtins}). |
| |
| @item |
| Shell functions may be exported to children via the environment |
| using @code{export -f} (@pxref{Shell Functions}). |
| |
| @item |
| The Bash @code{export}, @code{readonly}, and @code{declare} builtins can |
| take a @option{-f} option to act on shell functions, a @option{-p} option to |
| display variables with various attributes set in a format that can be |
| used as shell input, a @option{-n} option to remove various variable |
| attributes, and @samp{name=value} arguments to set variable attributes |
| and values simultaneously. |
| |
| @item |
| The Bash @code{hash} builtin allows a name to be associated with |
| an arbitrary filename, even when that filename cannot be found by |
| searching the @env{$PATH}, using @samp{hash -p} |
| (@pxref{Bourne Shell Builtins}). |
| |
| @item |
| Bash includes a @code{help} builtin for quick reference to shell |
| facilities (@pxref{Bash Builtins}). |
| |
| @item |
| The @code{printf} builtin is available to display formatted output |
| (@pxref{Bash Builtins}). |
| |
| @item |
| The Bash @code{read} builtin (@pxref{Bash Builtins}) |
| will read a line ending in @samp{\} with |
| the @option{-r} option, and will use the @env{REPLY} variable as a |
| default if no non-option arguments are supplied. |
| The Bash @code{read} builtin |
| also accepts a prompt string with the @option{-p} option and will use |
| Readline to obtain the line when given the @option{-e} option. |
| The @code{read} builtin also has additional options to control input: |
| the @option{-s} option will turn off echoing of input characters as |
| they are read, the @option{-t} option will allow @code{read} to time out |
| if input does not arrive within a specified number of seconds, the |
| @option{-n} option will allow reading only a specified number of |
| characters rather than a full line, and the @option{-d} option will read |
| until a particular character rather than newline. |
| |
| @item |
| The @code{return} builtin may be used to abort execution of scripts |
| executed with the @code{.} or @code{source} builtins |
| (@pxref{Bourne Shell Builtins}). |
| |
| @item |
| Bash includes the @code{shopt} builtin, for finer control of shell |
| optional capabilities (@pxref{The Shopt Builtin}), and allows these options |
| to be set and unset at shell invocation (@pxref{Invoking Bash}). |
| |
| @item |
| Bash has much more optional behavior controllable with the @code{set} |
| builtin (@pxref{The Set Builtin}). |
| |
| @item |
| The @samp{-x} (@code{xtrace}) option displays commands other than |
| simple commands when performing an execution trace |
| (@pxref{The Set Builtin}). |
| |
| @item |
| The @code{test} builtin (@pxref{Bourne Shell Builtins}) |
| is slightly different, as it implements the @sc{posix} algorithm, |
| which specifies the behavior based on the number of arguments. |
| |
| @item |
| Bash includes the @code{caller} builtin, which displays the context of |
| any active subroutine call (a shell function or a script executed with |
| the @code{.} or @code{source} builtins). This supports the bash |
| debugger. |
| |
| @item |
| The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a |
| @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}. |
| Commands specified with a @code{DEBUG} trap are executed before every |
| simple command, @code{for} command, @code{case} command, |
| @code{select} command, every arithmetic @code{for} command, and before |
| the first command executes in a shell function. |
| The @code{DEBUG} trap is not inherited by shell functions unless the |
| function has been given the @code{trace} attribute or the |
| @code{functrace} option has been enabled using the @code{shopt} builtin. |
| The @code{extdebug} shell option has additional effects on the |
| @code{DEBUG} trap. |
| |
| The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an |
| @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}. |
| Commands specified with an @code{ERR} trap are executed after a simple |
| command fails, with a few exceptions. |
| The @code{ERR} trap is not inherited by shell functions unless the |
| @code{-o errtrace} option to the @code{set} builtin is enabled. |
| |
| The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a |
| @code{RETURN} pseudo-signal specification, similar to |
| @code{EXIT} and @code{DEBUG}. |
| Commands specified with an @code{RETURN} trap are executed before |
| execution resumes after a shell function or a shell script executed with |
| @code{.} or @code{source} returns. |
| The @code{RETURN} trap is not inherited by shell functions unless the |
| function has been given the @code{trace} attribute or the |
| @code{functrace} option has been enabled using the @code{shopt} builtin. |
| |
| @item |
| The Bash @code{type} builtin is more extensive and gives more information |
| about the names it finds (@pxref{Bash Builtins}). |
| |
| @item |
| The Bash @code{umask} builtin permits a @option{-p} option to cause |
| the output to be displayed in the form of a @code{umask} command |
| that may be reused as input (@pxref{Bourne Shell Builtins}). |
| |
| @item |
| Bash implements a @code{csh}-like directory stack, and provides the |
| @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it |
| (@pxref{The Directory Stack}). |
| Bash also makes the directory stack visible as the value of the |
| @env{DIRSTACK} shell variable. |
| |
| @item |
| Bash interprets special backslash-escaped characters in the prompt |
| strings when interactive (@pxref{Printing a Prompt}). |
| |
| @item |
| The Bash restricted mode is more useful (@pxref{The Restricted Shell}); |
| the SVR4.2 shell restricted mode is too limited. |
| |
| @item |
| The @code{disown} builtin can remove a job from the internal shell |
| job table (@pxref{Job Control Builtins}) or suppress the sending |
| of @code{SIGHUP} to a job when the shell exits as the result of a |
| @code{SIGHUP}. |
| |
| @item |
| Bash includes a number of features to support a separate debugger for |
| shell scripts. |
| |
| @item |
| The SVR4.2 shell has two privilege-related builtins |
| (@code{mldmode} and @code{priv}) not present in Bash. |
| |
| @item |
| Bash does not have the @code{stop} or @code{newgrp} builtins. |
| |
| @item |
| Bash does not use the @env{SHACCT} variable or perform shell accounting. |
| |
| @item |
| The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses |
| @env{TMOUT}. |
| |
| @end itemize |
| |
| @noindent |
| More features unique to Bash may be found in @ref{Bash Features}. |
| |
| |
| @appendixsec 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: |
| |
| @itemize @bullet |
| |
| @item |
| Bash does not fork a subshell when redirecting into or out of |
| a shell control structure such as an @code{if} or @code{while} |
| statement. |
| |
| @item |
| Bash does not allow unbalanced quotes. The SVR4.2 shell will silently |
| insert a needed closing quote at @code{EOF} under certain circumstances. |
| This can be the cause of some hard-to-find errors. |
| |
| @item |
| The SVR4.2 shell uses a baroque memory management scheme based on |
| trapping @code{SIGSEGV}. If the shell is started from a process with |
| @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library |
| function call), it misbehaves badly. |
| |
| @item |
| In a questionable attempt at security, the SVR4.2 shell, |
| when invoked without the @option{-p} option, will alter its real |
| and effective @sc{uid} and @sc{gid} if they are less than some |
| magic threshold value, commonly 100. |
| This can lead to unexpected results. |
| |
| @item |
| The SVR4.2 shell does not allow users to trap @code{SIGSEGV}, |
| @code{SIGALRM}, or @code{SIGCHLD}. |
| |
| @item |
| The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK}, |
| @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset. |
| |
| @item |
| The SVR4.2 shell treats @samp{^} as the undocumented equivalent of |
| @samp{|}. |
| |
| @item |
| Bash allows multiple option arguments when it is invoked (@code{-x -v}); |
| the SVR4.2 shell allows only one option argument (@code{-xv}). In |
| fact, some versions of the shell dump core if the second argument begins |
| with a @samp{-}. |
| |
| @item |
| The SVR4.2 shell exits a script if any builtin fails; Bash exits |
| a script only if one of the @sc{posix} special builtins fails, and |
| only for certain failures, as enumerated in the @sc{posix} standard. |
| |
| @item |
| The SVR4.2 shell behaves differently when invoked as @code{jsh} |
| (it turns on job control). |
| @end itemize |
| |
| @node GNU Free Documentation License |
| @appendix GNU Free Documentation License |
| |
| @include fdl.texi |
| |
| @node Indexes |
| @appendix 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. |
| @end menu |
| |
| @node Builtin Index |
| @appendixsec Index of Shell Builtin Commands |
| @printindex bt |
| |
| @node Reserved Word Index |
| @appendixsec Index of Shell Reserved Words |
| @printindex rw |
| |
| @node Variable Index |
| @appendixsec Parameter and Variable Index |
| @printindex vr |
| |
| @node Function Index |
| @appendixsec Function Index |
| @printindex fn |
| |
| @node Concept Index |
| @appendixsec Concept Index |
| @printindex cp |
| |
| @bye |