This is bashref.info, produced by makeinfo version 4.0f from
bashref.texi.

INFO-DIR-SECTION Utilities
START-INFO-DIR-ENTRY
* Bash: (bash).                     The GNU Bourne-Again SHell.
END-INFO-DIR-ENTRY

This text is a brief description of the features that are present in
the Bash shell.

This is Edition 2.5a, last updated 13 November 2001,
of `The GNU Bash Reference Manual',
for `Bash', Version 2.05a.

Copyright (C) 1991-2001 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.


File: bashref.info,  Node: Commands For History,  Next: Commands For Text,  Prev: Commands For Moving,  Up: Bindable Readline Commands

Commands For Manipulating The History
-------------------------------------

`accept-line (Newline or Return)'
     Accept the line regardless of where the cursor is.  If this line is
     non-empty, add it to the history list according to the setting of
     the `HISTCONTROL' and `HISTIGNORE' variables.  If this line is a
     modified history line, then restore the history line to its
     original state.

`previous-history (C-p)'
     Move `back' through the history list, fetching the previous
     command.

`next-history (C-n)'
     Move `forward' through the history list, fetching the next command.

`beginning-of-history (M-<)'
     Move to the first line in the history.

`end-of-history (M->)'
     Move to the end of the input history, i.e., the line currently
     being entered.

`reverse-search-history (C-r)'
     Search backward starting at the current line and moving `up'
     through the history as necessary.  This is an incremental search.

`forward-search-history (C-s)'
     Search forward starting at the current line and moving `down'
     through the the history as necessary.  This is an incremental
     search.

`non-incremental-reverse-search-history (M-p)'
     Search backward starting at the current line and moving `up'
     through the history as necessary using a non-incremental search
     for a string supplied by the user.

`non-incremental-forward-search-history (M-n)'
     Search forward starting at the current line and moving `down'
     through the the history as necessary using a non-incremental search
     for a string supplied by the user.

`history-search-forward ()'
     Search forward through the history for the string of characters
     between the start of the current line and the point.  This is a
     non-incremental search.  By default, this command is unbound.

`history-search-backward ()'
     Search backward through the history for the string of characters
     between the start of the current line and the point.  This is a
     non-incremental search.  By default, this command is unbound.

`yank-nth-arg (M-C-y)'
     Insert the first argument to the previous command (usually the
     second word on the previous line) at point.  With an argument N,
     insert the Nth word from the previous command (the words in the
     previous command begin with word 0).  A negative argument inserts
     the Nth word from the end of the previous command.

`yank-last-arg (M-. or M-_)'
     Insert last argument to the previous command (the last word of the
     previous history entry).  With an argument, behave exactly like
     `yank-nth-arg'.  Successive calls to `yank-last-arg' move back
     through the history list, inserting the last argument of each line
     in turn.


File: bashref.info,  Node: Commands For Text,  Next: Commands For Killing,  Prev: Commands For History,  Up: Bindable Readline Commands

Commands For Changing Text
--------------------------

`delete-char (C-d)'
     Delete the character at point.  If point is at the beginning of
     the line, there are no characters in the line, and the last
     character typed was not bound to `delete-char', then return EOF.

`backward-delete-char (Rubout)'
     Delete the character behind the cursor.  A numeric argument means
     to kill the characters instead of deleting them.

`forward-backward-delete-char ()'
     Delete the character under the cursor, unless the cursor is at the
     end of the line, in which case the character behind the cursor is
     deleted.  By default, this is not bound to a key.

`quoted-insert (C-q or C-v)'
     Add the next character typed to the line verbatim.  This is how to
     insert key sequences like `C-q', for example.

`self-insert (a, b, A, 1, !, ...)'
     Insert yourself.

`transpose-chars (C-t)'
     Drag the character before the cursor forward over the character at
     the cursor, moving the cursor forward as well.  If the insertion
     point is at the end of the line, then this transposes the last two
     characters of the line.  Negative arguments have no effect.

`transpose-words (M-t)'
     Drag the word before point past the word after point, moving point
     past that word as well.  If the insertion point is at the end of
     the line, this transposes the last two words on the line.

`upcase-word (M-u)'
     Uppercase the current (or following) word.  With a negative
     argument, uppercase the previous word, but do not move the cursor.

`downcase-word (M-l)'
     Lowercase the current (or following) word.  With a negative
     argument, lowercase the previous word, but do not move the cursor.

`capitalize-word (M-c)'
     Capitalize the current (or following) word.  With a negative
     argument, capitalize the previous word, but do not move the cursor.


File: bashref.info,  Node: Commands For Killing,  Next: Numeric Arguments,  Prev: Commands For Text,  Up: Bindable Readline Commands

Killing And Yanking
-------------------

`kill-line (C-k)'
     Kill the text from point to the end of the line.

`backward-kill-line (C-x Rubout)'
     Kill backward to the beginning of the line.

`unix-line-discard (C-u)'
     Kill backward from the cursor to the beginning of the current line.

`kill-whole-line ()'
     Kill all characters on the current line, no matter where point is.
     By default, this is unbound.

`kill-word (M-d)'
     Kill from point to the end of the current word, or if between
     words, to the end of the next word.  Word boundaries are the same
     as `forward-word'.

`backward-kill-word (M-<DEL>)'
     Kill the word behind point.  Word boundaries are the same as
     `backward-word'.

`unix-word-rubout (C-w)'
     Kill the word behind point, using white space as a word boundary.
     The killed text is saved on the kill-ring.

`delete-horizontal-space ()'
     Delete all spaces and tabs around point.  By default, this is
     unbound.

`kill-region ()'
     Kill the text in the current region.  By default, this command is
     unbound.

`copy-region-as-kill ()'
     Copy the text in the region to the kill buffer, so it can be yanked
     right away.  By default, this command is unbound.

`copy-backward-word ()'
     Copy the word before point to the kill buffer.  The word
     boundaries are the same as `backward-word'.  By default, this
     command is unbound.

`copy-forward-word ()'
     Copy the word following point to the kill buffer.  The word
     boundaries are the same as `forward-word'.  By default, this
     command is unbound.

`yank (C-y)'
     Yank the top of the kill ring into the buffer at point.

`yank-pop (M-y)'
     Rotate the kill-ring, and yank the new top.  You can only do this
     if the prior command is `yank' or `yank-pop'.


File: bashref.info,  Node: Numeric Arguments,  Next: Commands For Completion,  Prev: Commands For Killing,  Up: Bindable Readline Commands

Specifying Numeric Arguments
----------------------------

`digit-argument (M-0, M-1, ... M--)'
     Add this digit to the argument already accumulating, or start a new
     argument.  `M--' starts a negative argument.

`universal-argument ()'
     This is another way to specify an argument.  If this command is
     followed by one or more digits, optionally with a leading minus
     sign, those digits define the argument.  If the command is
     followed by digits, executing `universal-argument' again ends the
     numeric argument, but is otherwise ignored.  As a special case, if
     this command is immediately followed by a character that is
     neither a digit or minus sign, the argument count for the next
     command is multiplied by four.  The argument count is initially
     one, so executing this function the first time makes the argument
     count four, a second time makes the argument count sixteen, and so
     on.  By default, this is not bound to a key.


File: bashref.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Prev: Numeric Arguments,  Up: Bindable Readline Commands

Letting Readline Type For You
-----------------------------

`complete (<TAB>)'
     Attempt to perform completion on the text before point.  The
     actual completion performed is application-specific.  Bash
     attempts completion treating the text as a variable (if the text
     begins with `$'), username (if the text begins with `~'), hostname
     (if the text begins with `@'), or command (including aliases and
     functions) in turn.  If none of these produces a match, filename
     completion is attempted.

`possible-completions (M-?)'
     List the possible completions of the text before point.

`insert-completions (M-*)'
     Insert all completions of the text before point that would have
     been generated by `possible-completions'.

`menu-complete ()'
     Similar to `complete', but replaces the word to be completed with
     a single match from the list of possible completions.  Repeated
     execution of `menu-complete' steps through the list of possible
     completions, inserting each match in turn.  At the end of the list
     of completions, the bell is rung (subject to the setting of
     `bell-style') and the original text is restored.  An argument of N
     moves N positions forward in the list of matches; a negative
     argument may be used to move backward through the list.  This
     command is intended to be bound to <TAB>, but is unbound by
     default.

`delete-char-or-list ()'
     Deletes the character under the cursor if not at the beginning or
     end of the line (like `delete-char').  If at the end of the line,
     behaves identically to `possible-completions'.  This command is
     unbound by default.

`complete-filename (M-/)'
     Attempt filename completion on the text before point.

`possible-filename-completions (C-x /)'
     List the possible completions of the text before point, treating
     it as a filename.

`complete-username (M-~)'
     Attempt completion on the text before point, treating it as a
     username.

`possible-username-completions (C-x ~)'
     List the possible completions of the text before point, treating
     it as a username.

`complete-variable (M-$)'
     Attempt completion on the text before point, treating it as a
     shell variable.

`possible-variable-completions (C-x $)'
     List the possible completions of the text before point, treating
     it as a shell variable.

`complete-hostname (M-@)'
     Attempt completion on the text before point, treating it as a
     hostname.

`possible-hostname-completions (C-x @)'
     List the possible completions of the text before point, treating
     it as a hostname.

`complete-command (M-!)'
     Attempt completion on the text before point, treating it as a
     command name.  Command completion attempts to match the text
     against aliases, reserved words, shell functions, shell builtins,
     and finally executable filenames, in that order.

`possible-command-completions (C-x !)'
     List the possible completions of the text before point, treating
     it as a command name.

`dynamic-complete-history (M-<TAB>)'
     Attempt completion on the text before point, comparing the text
     against lines from the history list for possible completion
     matches.

`complete-into-braces (M-{)'
     Perform filename completion and insert the list of possible
     completions enclosed within braces so the list is available to the
     shell (*note Brace Expansion::).


File: bashref.info,  Node: Keyboard Macros,  Next: Miscellaneous Commands,  Prev: Commands For Completion,  Up: Bindable Readline Commands

Keyboard Macros
---------------

`start-kbd-macro (C-x ()'
     Begin saving the characters typed into the current keyboard macro.

`end-kbd-macro (C-x ))'
     Stop saving the characters typed into the current keyboard macro
     and save the definition.

`call-last-kbd-macro (C-x e)'
     Re-execute the last keyboard macro defined, by making the
     characters in the macro appear as if typed at the keyboard.


File: bashref.info,  Node: Miscellaneous Commands,  Prev: Keyboard Macros,  Up: Bindable Readline Commands

Some Miscellaneous Commands
---------------------------

`re-read-init-file (C-x C-r)'
     Read in the contents of the INPUTRC file, and incorporate any
     bindings or variable assignments found there.

`abort (C-g)'
     Abort the current editing command and ring the terminal's bell
     (subject to the setting of `bell-style').

`do-uppercase-version (M-a, M-b, M-X, ...)'
     If the metafied character X is lowercase, run the command that is
     bound to the corresponding uppercase character.

`prefix-meta (<ESC>)'
     Metafy the next character typed.  This is for keyboards without a
     meta key.  Typing `<ESC> f' is equivalent to typing `M-f'.

`undo (C-_ or C-x C-u)'
     Incremental undo, separately remembered for each line.

`revert-line (M-r)'
     Undo all changes made to this line.  This is like executing the
     `undo' command enough times to get back to the beginning.

`tilde-expand (M-&)'
     Perform tilde expansion on the current word.

`set-mark (C-@)'
     Set the mark to the point.  If a numeric argument is supplied, the
     mark is set to that position.

`exchange-point-and-mark (C-x C-x)'
     Swap the point with the mark.  The current cursor position is set
     to the saved position, and the old cursor position is saved as the
     mark.

`character-search (C-])'
     A character is read and point is moved to the next occurrence of
     that character.  A negative count searches for previous
     occurrences.

`character-search-backward (M-C-])'
     A character is read and point is moved to the previous occurrence
     of that character.  A negative count searches for subsequent
     occurrences.

`insert-comment (M-#)'
     The value of the `comment-begin' variable is inserted at the
     beginning of the current line, and the line is accepted as if a
     newline had been typed.  The default value of `comment-begin'
     causes this command to make the current line a shell comment.

`dump-functions ()'
     Print all of the functions and their key bindings to the Readline
     output stream.  If a numeric argument is supplied, the output is
     formatted in such a way that it can be made part of an INPUTRC
     file.  This command is unbound by default.

`dump-variables ()'
     Print all of the settable variables and their values to the
     Readline output stream.  If a numeric argument is supplied, the
     output is formatted in such a way that it can be made part of an
     INPUTRC file.  This command is unbound by default.

`dump-macros ()'
     Print all of the Readline key sequences bound to macros and the
     strings they output.  If a numeric argument is supplied, the
     output is formatted in such a way that it can be made part of an
     INPUTRC file.  This command is unbound by default.

`glob-expand-word (C-x *)'
     The word before point is treated as a pattern for pathname
     expansion, and the list of matching file names is inserted,
     replacing the word.

`glob-list-expansions (C-x g)'
     The list of expansions that would have been generated by
     `glob-expand-word' is displayed, and the line is redrawn.

`display-shell-version (C-x C-v)'
     Display version information about the current instance of Bash.

`shell-expand-line (M-C-e)'
     Expand the line as the shell does.  This performs alias and
     history expansion as well as all of the shell word expansions
     (*note Shell Expansions::).

`history-expand-line (M-^)'
     Perform history expansion on the current line.

`magic-space ()'
     Perform history expansion on the current line and insert a space
     (*note History Interaction::).

`alias-expand-line ()'
     Perform alias expansion on the current line (*note Aliases::).

`history-and-alias-expand-line ()'
     Perform history and alias expansion on the current line.

`insert-last-argument (M-. or M-_)'
     A synonym for `yank-last-arg'.

`operate-and-get-next (C-o)'
     Accept the current line for execution and fetch the next line
     relative to the current line from the history for editing.  Any
     argument is ignored.

`emacs-editing-mode (C-e)'
     When in `vi' editing mode, this causes a switch back to `emacs'
     editing mode, as if the command `set -o emacs' had been executed.


File: bashref.info,  Node: Readline vi Mode,  Next: Programmable Completion,  Prev: Bindable Readline Commands,  Up: Command Line Editing

Readline vi Mode
================

   While the Readline library does not have a full set of `vi' editing
functions, it does contain enough to allow simple editing of the line.
The Readline `vi' mode behaves as specified in the POSIX 1003.2
standard.

   In order to switch interactively between `emacs' and `vi' editing
modes, use the `set -o emacs' and `set -o vi' commands (*note The Set
Builtin::).  The Readline default is `emacs' mode.

   When you enter a line in `vi' mode, you are already placed in
`insertion' mode, as if you had typed an `i'.  Pressing <ESC> switches
you into `command' mode, where you can edit the text of the line with
the standard `vi' movement keys, move to previous history lines with
`k' and subsequent lines with `j', and so forth.


File: bashref.info,  Node: Programmable Completion,  Next: Programmable Completion Builtins,  Prev: Readline vi Mode,  Up: Command Line Editing

Programmable Completion
=======================

   When word completion is attempted for an argument to a command for
which a completion specification (a COMPSPEC) has been defined using
the `complete' builtin (*note Programmable Completion Builtins::), the
programmable completion facilities are invoked.

   First, the command name is identified.  If a compspec has been
defined for that command, the compspec is used to generate the list of
possible completions for the word.  If the command word is a full
pathname, a compspec for the full pathname is searched for first.  If
no compspec is found for the full pathname, an attempt is made to find
a compspec for the portion following the final slash.

   Once a compspec has been found, it is used to generate the list of
matching words.  If a compspec is not found, the default Bash completion
described above (*note Commands For Completion::) is performed.

   First, the actions specified by the compspec are used.  Only matches
which are prefixed by the word being completed are returned.  When the
`-f' or `-d' option is used for filename or directory name completion,
the shell variable `FIGNORE' is used to filter the matches.  *Note Bash
Variables::, for a description of `FIGNORE'.

   Any completions specified by a filename expansion pattern to the
`-G' option are generated next.  The words generated by the pattern
need not match the word being completed.  The `GLOBIGNORE' shell
variable is not used to filter the matches, but the `FIGNORE' shell
variable is used.

   Next, the string specified as the argument to the `-W' option is
considered.  The string is first split using the characters in the `IFS'
special variable as delimiters.  Shell quoting is honored.  Each word
is then expanded using brace expansion, tilde expansion, parameter and
variable expansion, command substitution, arithmetic expansion, and
pathname expansion, as described above (*note Shell Expansions::).  The
results are split using the rules described above (*note Word
Splitting::).  The results of the expansion are prefix-matched against
the word being completed, and the matching words become the possible
completions.

   After these matches have been generated, any shell function or
command specified with the `-F' and `-C' options is invoked.  When the
command or function is invoked, the `COMP_LINE' and `COMP_POINT'
variables are assigned values as described above (*note Bash
Variables::).  If a shell function is being invoked, the `COMP_WORDS'
and `COMP_CWORD' variables are also set.  When the function or command
is invoked, the first argument is the name of the command whose
arguments are being completed, the second argument is the word being
completed, and the third argument is the word preceding the word being
completed on the current command line.  No filtering of the generated
completions against the word being completed is performed; the function
or command has complete freedom in generating the matches.

   Any function specified with `-F' is invoked first.  The function may
use any of the shell facilities, including the `compgen' builtin
described below (*note Programmable Completion Builtins::), to generate
the matches.  It must put the possible completions in the `COMPREPLY'
array variable.

   Next, any command specified with the `-C' option is invoked in an
environment equivalent to command substitution.  It should print a list
of completions, one per line, to the standard output.  Backslash may be
used to escape a newline, if necessary.

   After all of the possible completions are generated, any filter
specified with the `-X' option is applied to the list.  The filter is a
pattern as used for pathname expansion; a `&' in the pattern is
replaced with the text of the word being completed.  A literal `&' may
be escaped with a backslash; the backslash is removed before attempting
a match.  Any completion that matches the pattern will be removed from
the list.  A leading `!' negates the pattern; in this case any
completion not matching the pattern will be removed.

   Finally, any prefix and suffix specified with the `-P' and `-S'
options are added to each member of the completion list, and the result
is returned to the Readline completion code as the list of possible
completions.

   If the previously-applied actions do not generate any matches, and
the `-o dirnames' option was supplied to `complete' when the compspec
was defined, directory name completion is attempted.

   By default, if a compspec is found, whatever it generates is
returned to the completion code as the full set of possible completions.
The default Bash completions are not attempted, and the Readline default
of filename completion is disabled.  If the `-o default' option was
supplied to `complete' when the compspec was defined, Readline's
default completion will be performed if the compspec generates no
matches.


File: bashref.info,  Node: Programmable Completion Builtins,  Prev: Programmable Completion,  Up: Command Line Editing

Programmable Completion Builtins
================================

   Two builtin commands are available to manipulate the programmable
completion facilities.

`compgen'
          `compgen [OPTION] [WORD]'

     Generate possible completion matches for WORD according to the
     OPTIONs, which may be any option accepted by the `complete'
     builtin with the exception of `-p' and `-r', and write the matches
     to the standard output.  When using the `-F' or `-C' options, the
     various shell variables set by the programmable completion
     facilities, while available, will not have useful values.

     The matches will be generated in the same way as if the
     programmable completion code had generated them directly from a
     completion specification with the same flags.  If WORD is
     specified, only those completions matching WORD will be displayed.

     The return value is true unless an invalid option is supplied, or
     no matches were generated.

`complete'
          `complete [-abcdefgjkvu] [-o COMP-OPTION] [-A ACTION] [-G GLOBPAT] [-W WORDLIST]
          [-P PREFIX] [-S SUFFIX] [-X FILTERPAT] [-F FUNCTION]
          [-C COMMAND] NAME [NAME ...]'
          `complete -pr [NAME ...]'

     Specify how arguments to each NAME should be completed.  If the
     `-p' option is supplied, or if no options are supplied, existing
     completion specifications are printed in a way that allows them to
     be reused as input.  The `-r' option removes a completion
     specification for each NAME, or, if no NAMEs are supplied, all
     completion specifications.

     The process of applying these completion specifications when word
     completion is attempted is described above (*note Programmable
     Completion::).

     Other options, if specified, have the following meanings.  The
     arguments to the `-G', `-W', and `-X' options (and, if necessary,
     the `-P' and `-S' options) should be quoted to protect them from
     expansion before the `complete' builtin is invoked.

    `-o COMP-OPTION'
          The COMP-OPTION controls several aspects of the compspec's
          behavior beyond the simple generation of completions.
          COMP-OPTION may be one of:

         `default'
               Use readline's default completion if the compspec
               generates no matches.

         `dirnames'
               Perform directory name completion if the compspec
               generates no matches.

         `filenames'
               Tell Readline that the compspec generates filenames, so
               it can perform any filename\-specific processing (like
               adding a slash to directory names or suppressing
               trailing spaces).  This option is intended to be used
               with shell functions specified with `-F'.

    `-A ACTION'
          The ACTION may be one of the following to generate a list of
          possible completions:

         `alias'
               Alias names.  May also be specified as `-a'.

         `arrayvar'
               Array variable names.

         `binding'
               Readline key binding names (*note Bindable Readline
               Commands::).

         `builtin'
               Names of shell builtin commands.  May also be specified
               as `-b'.

         `command'
               Command names.  May also be specified as `-c'.

         `directory'
               Directory names.  May also be specified as `-d'.

         `disabled'
               Names of disabled shell builtins.

         `enabled'
               Names of enabled shell builtins.

         `export'
               Names of exported shell variables.  May also be
               specified as `-e'.

         `file'
               File names.  May also be specified as `-f'.

         `function'
               Names of shell functions.

         `group'
               Group names.  May also be specified as `-g'.

         `helptopic'
               Help topics as accepted by the `help' builtin (*note
               Bash Builtins::).

         `hostname'
               Hostnames, as taken from the file specified by the
               `HOSTFILE' shell variable (*note Bash Variables::).

         `job'
               Job names, if job control is active.  May also be
               specified as `-j'.

         `keyword'
               Shell reserved words.  May also be specified as `-k'.

         `running'
               Names of running jobs, if job control is active.

         `setopt'
               Valid arguments for the `-o' option to the `set' builtin
               (*note The Set Builtin::).

         `shopt'
               Shell option names as accepted by the `shopt' builtin
               (*note Bash Builtins::).

         `signal'
               Signal names.

         `stopped'
               Names of stopped jobs, if job control is active.

         `user'
               User names.  May also be specified as `-u'.

         `variable'
               Names of all shell variables.  May also be specified as
               `-v'.

    `-G GLOBPAT'
          The filename expansion pattern GLOBPAT is expanded to generate
          the possible completions.

    `-W WORDLIST'
          The WORDLIST is split using the characters in the `IFS'
          special variable as delimiters, and each resultant word is
          expanded.  The possible completions are the members of the
          resultant list which match the word being completed.

    `-C COMMAND'
          COMMAND is executed in a subshell environment, and its output
          is used as the possible completions.

    `-F FUNCTION'
          The shell function FUNCTION is executed in the current shell
          environment.  When it finishes, the possible completions are
          retrieved from the value of the `COMPREPLY' array variable.

    `-X FILTERPAT'
          FILTERPAT is a pattern as used for filename expansion.  It is
          applied to the list of possible completions generated by the
          preceding options and arguments, and each completion matching
          FILTERPAT is removed from the list.  A leading `!' in
          FILTERPAT negates the pattern; in this case, any completion
          not matching FILTERPAT is removed.

    `-P PREFIX'
          PREFIX is added at the beginning of each possible completion
          after all other options have been applied.

    `-S SUFFIX'
          SUFFIX is appended to each possible completion after all
          other options have been applied.

     The return value is true unless an invalid option is supplied, an
     option other than `-p' or `-r' is supplied without a NAME
     argument, an attempt is made to remove a completion specification
     for a NAME for which no specification exists, or an error occurs
     adding a completion specification.


File: bashref.info,  Node: Using History Interactively,  Next: Command Line Editing,  Prev: Job Control,  Up: Top

Using History Interactively
***************************

   This chapter describes how to use the GNU History Library
interactively, from a user's standpoint.  It should be considered a
user's guide.  For information on using the GNU History Library in
other programs, see the GNU Readline Library Manual.

* Menu:

* Bash History Facilities::	How Bash lets you manipulate your command
				history.
* Bash History Builtins::	The Bash builtin commands that manipulate
				the command history.
* History Interaction::		What it feels like using History as a user.


File: bashref.info,  Node: Bash History Facilities,  Next: Bash History Builtins,  Up: Using History Interactively

Bash History Facilities
=======================

   When the `-o history' option to the `set' builtin is enabled (*note
The Set Builtin::), the shell provides access to the "command history",
the list of commands previously typed.  The value of the `HISTSIZE'
shell variable is used as the number of commands to save in a history
list.  The text of the last `$HISTSIZE' commands (default 500) is saved.
The shell stores each command in the history list prior to parameter
and variable expansion but after history expansion is performed,
subject to the values of the shell variables `HISTIGNORE' and
`HISTCONTROL'.

   When the shell starts up, the history is initialized from the file
named by the `HISTFILE' variable (default `~/.bash_history').  The file
named by the value of `HISTFILE' is truncated, if necessary, to contain
no more than the number of lines specified by the value of the
`HISTFILESIZE' variable.  When an interactive shell exits, the last
`$HISTSIZE' lines are copied from the history list to the file named by
`$HISTFILE'.  If the `histappend' shell option is set (*note Bash
Builtins::), the lines are appended to the history file, otherwise the
history file is overwritten.  If `HISTFILE' is unset, or if the history
file is unwritable, the history is not saved.  After saving the
history, the history file is truncated to contain no more than
`$HISTFILESIZE' lines.  If `HISTFILESIZE' is not set, no truncation is
performed.

   The builtin command `fc' may be used to list or edit and re-execute
a portion of the history list.  The `history' builtin may be used to
display or modify the history list and manipulate the history file.
When using command-line editing, search commands are available in each
editing mode that provide access to the history list (*note Commands
For History::).

   The shell allows control over which commands are saved on the history
list.  The `HISTCONTROL' and `HISTIGNORE' variables may be set to cause
the shell to save only a subset of the commands entered.  The `cmdhist'
shell option, if enabled, causes the shell to attempt to save each line
of a multi-line command in the same history entry, adding semicolons
where necessary to preserve syntactic correctness.  The `lithist' shell
option causes the shell to save the command with embedded newlines
instead of semicolons.  The `shopt' builtin is used to set these
options.  *Note Bash Builtins::, for a description of `shopt'.


File: bashref.info,  Node: Bash History Builtins,  Next: History Interaction,  Prev: Bash History Facilities,  Up: Using History Interactively

Bash History Builtins
=====================

   Bash provides two builtin commands which manipulate the history list
and history file.

`fc'
          `fc [-e ENAME] [-nlr] [FIRST] [LAST]'
          `fc -s [PAT=REP] [COMMAND]'

     Fix Command.  In the first form, a range of commands from FIRST to
     LAST is selected from the history list.  Both FIRST and LAST may
     be specified as a string (to locate the most recent command
     beginning with that string) or as a number (an index into the
     history list, where a negative number is used as an offset from the
     current command number).  If LAST is not specified it is set to
     FIRST.  If FIRST is not specified it is set to the previous
     command for editing and -16 for listing.  If the `-l' flag is
     given, the commands are listed on standard output.  The `-n' flag
     suppresses the command numbers when listing.  The `-r' flag
     reverses the order of the listing.  Otherwise, the editor given by
     ENAME is invoked on a file containing those commands.  If ENAME is
     not given, the value of the following variable expansion is used:
     `${FCEDIT:-${EDITOR:-vi}}'.  This says to use the value of the
     `FCEDIT' variable if set, or the value of the `EDITOR' variable if
     that is set, or `vi' if neither is set.  When editing is complete,
     the edited commands are echoed and executed.

     In the second form, COMMAND is re-executed after each instance of
     PAT in the selected command is replaced by REP.

     A useful alias to use with the `fc' command is `r='fc -s'', so
     that typing `r cc' runs the last command beginning with `cc' and
     typing `r' re-executes the last command (*note Aliases::).

`history'
          history [N]
          history -c
          history -d OFFSET
          history [-anrw] [FILENAME]
          history -ps ARG

     With no options, display the history list with line numbers.
     Lines prefixed with a `*' have been modified.  An argument of N
     lists only the last N lines.  Options, if supplied, have the
     following meanings:

    `-c'
          Clear the history list.  This may be combined with the other
          options to replace the history list completely.

    `-d OFFSET'
          Delete the history entry at position OFFSET.  OFFSET should
          be specified as it appears when the history is displayed.

    `-a'
          Append the new history lines (history lines entered since the
          beginning of the current Bash session) to the history file.

    `-n'
          Append the history lines not already read from the history
          file to the current history list.  These are lines appended
          to the history file since the beginning of the current Bash
          session.

    `-r'
          Read the current history file and append its contents to the
          history list.

    `-w'
          Write out the current history to the history file.

    `-p'
          Perform history substitution on the ARGs and display the
          result on the standard output, without storing the results in
          the history list.

    `-s'
          The ARGs are added to the end of the history list as a single
          entry.

     When any of the `-w', `-r', `-a', or `-n' options is used, if
     FILENAME is given, then it is used as the history file.  If not,
     then the value of the `HISTFILE' variable is used.


File: bashref.info,  Node: History Interaction,  Prev: Bash History Builtins,  Up: Using History Interactively

History Expansion
=================

   The History library provides a history expansion feature that is
similar to the history expansion provided by `csh'.  This section
describes the syntax used to manipulate the history information.

   History expansions introduce words from the history list into the
input stream, making it easy to repeat commands, insert the arguments
to a previous command into the current input line, or fix errors in
previous commands quickly.

   History expansion takes place in two parts.  The first is to
determine which line from the history list should be used during
substitution.  The second is to select portions of that line for
inclusion into the current one.  The line selected from the history is
called the "event", and the portions of that line that are acted upon
are called "words".  Various "modifiers" are available to manipulate
the selected words.  The line is broken into words in the same fashion
that Bash does, so that several words surrounded by quotes are
considered one word.  History expansions are introduced by the
appearance of the history expansion character, which is `!' by default.
Only `\' and `'' may be used to escape the history expansion character.

   Several shell options settable with the `shopt' builtin (*note Bash
Builtins::) may be used to tailor the behavior of history expansion.
If the `histverify' shell option is enabled, and Readline is being
used, history substitutions are not immediately passed to the shell
parser.  Instead, the expanded line is reloaded into the Readline
editing buffer for further modification.  If Readline is being used,
and the `histreedit' shell option is enabled, a failed history
expansion will be reloaded into the Readline editing buffer for
correction.  The `-p' option to the `history' builtin command may be
used to see what a history expansion will do before using it.  The `-s'
option to the `history' builtin may be used to add commands to the end
of the history list without actually executing them, so that they are
available for subsequent recall.  This is most useful in conjunction
with Readline.

   The shell allows control of the various characters used by the
history expansion mechanism with the `histchars' variable.

* Menu:

* Event Designators::	How to specify which history line to use.
* Word Designators::	Specifying which words are of interest.
* Modifiers::		Modifying the results of substitution.


File: bashref.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction

Event Designators
-----------------

   An event designator is a reference to a command line entry in the
history list.

`!'
     Start a history substitution, except when followed by a space, tab,
     the end of the line, `=' or `('.

`!N'
     Refer to command line N.

`!-N'
     Refer to the command N lines back.

`!!'
     Refer to the previous command.  This is a synonym for `!-1'.

`!STRING'
     Refer to the most recent command starting with STRING.

`!?STRING[?]'
     Refer to the most recent command containing STRING.  The trailing
     `?' may be omitted if the STRING is followed immediately by a
     newline.

`^STRING1^STRING2^'
     Quick Substitution.  Repeat the last command, replacing STRING1
     with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.

`!#'
     The entire command line typed so far.


File: bashref.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction

Word Designators
----------------

   Word designators are used to select desired words from the event.  A
`:' separates the event specification from the word designator.  It may
be omitted if the word designator begins with a `^', `$', `*', `-', or
`%'.  Words are numbered from the beginning of the line, with the first
word being denoted by 0 (zero).  Words are inserted into the current
line separated by single spaces.

   For example,

`!!'
     designates the preceding command.  When you type this, the
     preceding command is repeated in toto.

`!!:$'
     designates the last argument of the preceding command.  This may be
     shortened to `!$'.

`!fi:2'
     designates the second argument of the most recent command starting
     with the letters `fi'.

   Here are the word designators:

`0 (zero)'
     The `0'th word.  For many applications, this is the command word.

`N'
     The Nth word.

`^'
     The first argument; that is, word 1.

`$'
     The last argument.

`%'
     The word matched by the most recent `?STRING?' search.

`X-Y'
     A range of words; `-Y' abbreviates `0-Y'.

`*'
     All of the words, except the `0'th.  This is a synonym for `1-$'.
     It is not an error to use `*' if there is just one word in the
     event; the empty string is returned in that case.

`X*'
     Abbreviates `X-$'

`X-'
     Abbreviates `X-$' like `X*', but omits the last word.

   If a word designator is supplied without an event specification, the
previous command is used as the event.


File: bashref.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction

Modifiers
---------

   After the optional word designator, you can add a sequence of one or
more of the following modifiers, each preceded by a `:'.

`h'
     Remove a trailing pathname component, leaving only the head.

`t'
     Remove all leading  pathname  components, leaving the tail.

`r'
     Remove a trailing suffix of the form `.SUFFIX', leaving the
     basename.

`e'
     Remove all but the trailing suffix.

`p'
     Print the new command but do not execute it.

`q'
     Quote the substituted words, escaping further substitutions.

`x'
     Quote the substituted words as with `q', but break into words at
     spaces, tabs, and newlines.

`s/OLD/NEW/'
     Substitute NEW for the first occurrence of OLD in the event line.
     Any delimiter may be used in place of `/'.  The delimiter may be
     quoted in OLD and NEW with a single backslash.  If `&' appears in
     NEW, it is replaced by OLD.  A single backslash will quote the
     `&'.  The final delimiter is optional if it is the last character
     on the input line.

`&'
     Repeat the previous substitution.

`g'
     Cause changes to be applied over the entire event line.  Used in
     conjunction with `s', as in `gs/OLD/NEW/', or with `&'.


File: bashref.info,  Node: Installing Bash,  Next: Reporting Bugs,  Prev: Command Line Editing,  Up: Top

Installing Bash
***************

   This chapter provides basic instructions for installing Bash on the
various supported platforms.  The distribution supports the GNU
operating systems, nearly every version of Unix, and several non-Unix
systems such as BeOS and Interix.  Other independent ports exist for
MS-DOS, OS/2, Windows 95/98, and Windows NT.

* Menu:

* Basic Installation::	Installation instructions.

* Compilers and Options::	How to set special options for various
				systems.

* Compiling For Multiple Architectures::	How to compile Bash for more
						than one kind of system from
						the same source tree.

* Installation Names::	How to set the various paths used by the installation.

* Specifying the System Type::	How to configure Bash for a particular system.

* Sharing Defaults::	How to share default configuration values among GNU
			programs.

* Operation Controls::	Options recognized by the configuration program.

* Optional Features::	How to enable and disable optional features when
			building Bash.


File: bashref.info,  Node: Basic Installation,  Next: Compilers and Options,  Up: Installing Bash

Basic Installation
==================

   These are installation instructions for Bash.

   The simplest way to compile Bash is:

  1. `cd' to the directory containing the source code and type
     `./configure' to configure Bash for your system.  If you're using
     `csh' on an old version of System V, you might need to type `sh
     ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes some time.  While running, it prints
     messages telling which features it is checking for.

  2. Type `make' to compile Bash and build the `bashbug' bug reporting
     script.

  3. Optionally, type `make tests' to run the Bash test suite.

  4. Type `make install' to install `bash' and `bashbug'.  This will
     also install the manual pages and Info file.


   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package
(the top directory, the `builtins', `doc', and `support' directories,
each directory under `lib', and several others).  It also creates a
`config.h' file containing system-dependent definitions.  Finally, it
creates a shell script named `config.status' that you can run in the
future to recreate the current configuration, a file `config.cache'
that saves the results of its tests to speed up reconfiguring, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').  If at some point `config.cache' contains
results you don't want to keep, you may remove or edit it.

   To find out more about the options and arguments that the
`configure' script understands, type

     bash-2.04$ ./configure --help

at the Bash prompt in your Bash source directory.

   If you need to do unusual things to compile Bash, please try to
figure out how `configure' could check whether or not to do them, and
mail diffs or instructions to <bash-maintainers@gnu.org> so they can be
considered for the next release.

   The file `configure.in' is used to create `configure' by a program
called Autoconf.  You only need `configure.in' if you want to change it
or regenerate `configure' using a newer version of Autoconf.  If you do
this, make sure you are using Autoconf version 2.50 or newer.

   You can remove the program binaries and object files from the source
code directory by typing `make clean'.  To also remove the files that
`configure' created (so you can compile Bash for a different kind of
computer), type `make distclean'.


File: bashref.info,  Node: Compilers and Options,  Next: Compiling For Multiple Architectures,  Prev: Basic Installation,  Up: Installing Bash

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:

     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

   On systems that have the `env' program, you can do it like this:

     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

   The configuration process uses GCC to build Bash if it is available.


File: bashref.info,  Node: Compiling For Multiple Architectures,  Next: Installation Names,  Prev: Compilers and Options,  Up: Installing Bash

Compiling For Multiple Architectures
====================================

   You can compile Bash for more than one kind of computer at the same
time, by placing the object files for each architecture in their own
directory.  To do this, you must use a version of `make' that supports
the `VPATH' variable, such as GNU `make'.  `cd' to the directory where
you want the object files and executables to go and run the `configure'
script from the source directory.  You may need to supply the
`--srcdir=PATH' argument to tell `configure' where the source files
are.  `configure' automatically checks for the source code in the
directory that `configure' is in and in `..'.

   If you have to use a `make' that does not supports the `VPATH'
variable, you can compile Bash for one architecture at a time in the
source code directory.  After you have installed Bash for one
architecture, use `make distclean' before reconfiguring for another
architecture.

   Alternatively, if your system supports symbolic links, you can use
the `support/mkclone' script to create a build tree which has symbolic
links back to each file in the source directory.  Here's an example
that creates a build directory in the current directory from a source
directory `/usr/gnu/src/bash-2.0':

     bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .

The `mkclone' script requires Bash, so you must have already built Bash
for at least one architecture before you can create build directories
for other architectures.


File: bashref.info,  Node: Installation Names,  Next: Specifying the System Type,  Prev: Compiling For Multiple Architectures,  Up: Installing Bash

Installation Names
==================

   By default, `make install' will install into `/usr/local/bin',
`/usr/local/man', etc.  You can specify an installation prefix other
than `/usr/local' by giving `configure' the option `--prefix=PATH', or
by specifying a value for the `DESTDIR' `make' variable when running
`make install'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', `make install' will
use PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

