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: The Restricted Shell,  Next: Bash POSIX Mode,  Prev: Printing a Prompt,  Up: Bash Features

The Restricted Shell
====================

   If Bash is started with the name `rbash', or the `--restricted'
option is supplied at invocation, the shell becomes restricted.  A
restricted shell is used to set up an environment more controlled than
the standard shell.  A restricted shell behaves identically to `bash'
with the exception that the following are disallowed:
   * Changing directories with the `cd' builtin.

   * Setting or unsetting the values of the `SHELL', `PATH', `ENV', or
     `BASH_ENV' variables.

   * Specifying command names containing slashes.

   * Specifying a filename containing a slash as an argument to the `.'
     builtin command.

   * Specifying a filename containing a slash as an argument to the `-p'
     option to the `hash' builtin command.

   * Importing function definitions from the shell environment at
     startup.

   * Parsing the value of `SHELLOPTS' from the shell environment at
     startup.

   * Redirecting output using the `>', `>|', `<>', `>&', `&>', and `>>'
     redirection operators.

   * Using the `exec' builtin to replace the shell with another command.

   * Adding or deleting builtin commands with the `-f' and `-d' options
     to the `enable' builtin.

   * Specifying the `-p' option to the `command' builtin.

   * Turning off restricted mode with `set +r' or `set +o restricted'.


File: bashref.info,  Node: Bash POSIX Mode,  Prev: The Restricted Shell,  Up: Bash Features

Bash POSIX Mode
===============

   Starting Bash with the `--posix' command-line option or executing
`set -o posix' while Bash is running will cause Bash to conform more
closely to the POSIX 1003.2 standard by changing the behavior to match
that specified by POSIX in areas where the Bash default differs.

   The following list is what's changed when `POSIX mode' is in effect:

  1. When a command in the hash table no longer exists, Bash will
     re-search `$PATH' to find the new location.  This is also
     available with `shopt -s checkhash'.

  2. The message printed by the job control code and builtins when a job
     exits with a non-zero status is `Done(status)'.

  3. The message printed by the job control code and builtins when a job
     is stopped is `Stopped(SIGNAME)', where SIGNAME is, for example,
     `SIGTSTP'.

  4. Reserved words may not be aliased.

  5. The POSIX 1003.2 `PS1' and `PS2' expansions of `!' to the history
     number and `!!' to `!' are enabled, and parameter expansion is
     performed on the values of `PS1' and `PS2' regardless of the
     setting of the `promptvars' option.

  6. Interactive comments are enabled by default.  (Bash has them on by
     default anyway.)

  7. The POSIX 1003.2 startup files are executed (`$ENV') rather than
     the normal Bash files.

  8. Tilde expansion is only performed on assignments preceding a
     command name, rather than on all assignment statements on the line.

  9. The default history file is `~/.sh_history' (this is the default
     value of `$HISTFILE').

 10. The output of `kill -l' prints all the signal names on a single
     line, separated by spaces.

 11. Non-interactive shells exit if FILENAME in `.' FILENAME is not
     found.

 12. Non-interactive shells exit if a syntax error in an arithmetic
     expansion results in an invalid expression.

 13. Redirection operators do not perform filename expansion on the word
     in the redirection unless the shell is interactive.

 14. Redirection operators do not perform word splitting on the word in
     the redirection.

 15. Function names must be valid shell `name's.  That is, they may not
     contain characters other than letters, digits, and underscores, and
     may not start with a digit.  Declaring a function with an invalid
     name causes a fatal syntax error in non-interactive shells.

 16. POSIX 1003.2 `special' builtins are found before shell functions
     during command lookup.

 17. If a POSIX 1003.2 special builtin returns an error status, a
     non-interactive shell exits.  The fatal errors are those listed in
     the POSIX.2 standard, and include things like passing incorrect
     options, redirection errors, variable assignment errors for
     assignments preceding the command name, and so on.

 18. If the `cd' builtin finds a directory to change to using
     `$CDPATH', the value it assigns to the `PWD' variable does not
     contain any symbolic links, as if `cd -P' had been executed.

 19. If `CDPATH' is set, the `cd' builtin will not implicitly append
     the current directory to it.  This means that `cd' will fail if no
     valid directory name can be constructed from any of the entries in
     `$CDPATH', even if the a directory with the same name as the name
     given as an argument to `cd' exists in the current directory.

 20. A non-interactive shell exits with an error status if a variable
     assignment error occurs when no command name follows the assignment
     statements.  A variable assignment error occurs, for example, when
     trying to assign a value to a readonly variable.

 21. A non-interactive shell exits with an error status if the iteration
     variable in a `for' statement or the selection variable in a
     `select' statement is a readonly variable.

 22. Process substitution is not available.

 23. Assignment statements preceding POSIX 1003.2 special builtins
     persist in the shell environment after the builtin completes.

 24. Assignment statements preceding shell function calls persist in the
     shell environment after the function returns, as if a POSIX
     special builtin command had been executed.

 25. The `export' and `readonly' builtin commands display their output
     in the format required by POSIX 1003.2.

 26. The `trap' builtin displays signal names without the leading `SIG'.

 27. The `.' and `source' builtins do not search the current directory
     for the filename argument if it is not found by searching `PATH'.

 28. Subshells spawned to execute command substitutions inherit the
     value of the `-e' option from the parent shell.  When not in POSIX
     mode, Bash clears the `-e' option in such subshells.

 29. Alias expansion is always enabled, even in non-interactive shells.

 30. When the `set' builtin is invoked without options, it does not
     display shell function names and definitions.

 31. When the `set' builtin is invoked without options, it displays
     variable values without quotes, unless they contain shell
     metacharacters, even if the result contains nonprinting characters.

   There is other POSIX 1003.2 behavior that Bash does not implement.
Specifically:

  1. Assignment statements affect the execution environment of all
     builtins, not just special ones.

  2. When a subshell is created to execute a shell script with execute
     permission, but without a leading `#!', Bash sets `$0' to the full
     pathname of the script as found by searching `$PATH', rather than
     the command as typed by the user.

  3. When using `.' to source a shell script found in `$PATH', bash
     checks execute permission bits rather than read permission bits,
     just as if it were searching for a command.



File: bashref.info,  Node: Job Control,  Next: Using History Interactively,  Prev: Bash Features,  Up: Top

Job Control
***********

   This chapter discusses what job control is, how it works, and how
Bash allows you to access its facilities.

* Menu:

* Job Control Basics::		How job control works.
* Job Control Builtins::	Bash builtin commands used to interact
				with job control.
* Job Control Variables::	Variables Bash uses to customize job
				control.


File: bashref.info,  Node: Job Control Basics,  Next: Job Control Builtins,  Up: Job Control

Job Control Basics
==================

   Job control refers to the ability to selectively stop (suspend) the
execution of processes and continue (resume) their execution at a later
point.  A user typically employs this facility via an interactive
interface supplied jointly by the system's terminal driver and Bash.

   The shell associates a JOB with each pipeline.  It keeps a table of
currently executing jobs, which may be listed with the `jobs' command.
When Bash starts a job asynchronously, it prints a line that looks like:
     [1] 25647

indicating that this job is job number 1 and that the process ID of the
last process in the pipeline associated with this job is 25647.  All of
the processes in a single pipeline are members of the same job.  Bash
uses the JOB abstraction as the basis for job control.

   To facilitate the implementation of the user interface to job
control, the operating system maintains the notion of a current terminal
process group ID.  Members of this process group (processes whose
process group ID is equal to the current terminal process group ID)
receive keyboard-generated signals such as `SIGINT'.  These processes
are said to be in the foreground.  Background processes are those whose
process group ID differs from the terminal's; such processes are immune
to keyboard-generated signals.  Only foreground processes are allowed
to read from or write to the terminal.  Background processes which
attempt to read from (write to) the terminal are sent a `SIGTTIN'
(`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 SUSPEND
character (typically `^Z', Control-Z) while a process is running causes
that process to be stopped and returns control to Bash.  Typing the
DELAYED SUSPEND character (typically `^Y', Control-Y) causes the
process to be stopped when it attempts to read input from the terminal,
and control to be returned to Bash.  The user then manipulates the
state of this job, using the `bg' command to continue it in the
background, the `fg' command to continue it in the foreground, or the
`kill' command to kill it.  A `^Z' takes effect immediately, and has
the additional side effect of causing pending output and typeahead to
be discarded.

   There are a number of ways to refer to a job in the shell.  The
character `%' introduces a job name.

   Job number `n' may be referred to as `%n'.  The symbols `%%' and
`%+' refer to the shell's notion of the current job, which is the last
job stopped while it was in the foreground or started in the
background.  The previous job may be referenced using `%-'.  In output
pertaining to jobs (e.g., the output of the `jobs' command), the
current job is always flagged with a `+', and the previous job with a
`-'.

   A job may also be referred to using a prefix of the name used to
start it, or using a substring that appears in its command line.  For
example, `%ce' refers to a stopped `ce' job. Using `%?ce', on the other
hand, refers to any job containing the string `ce' in its command line.
If the prefix or substring matches more than one job, Bash reports an
error.

   Simply naming a job can be used to bring it into the foreground:
`%1' is a synonym for `fg %1', bringing job 1 from the background into
the foreground.  Similarly, `%1 &' resumes job 1 in the background,
equivalent to `bg %1'

   The shell learns immediately whenever a job changes state.
Normally, Bash waits until it is about to print a prompt before
reporting changes in a job's status so as to not interrupt any other
output.  If the `-b' option to the `set' builtin is enabled, Bash
reports such changes immediately (*note The Set Builtin::).  Any trap
on `SIGCHLD' is executed for each child process that exits.

   If an attempt to exit Bash is while jobs are stopped, the shell
prints a message warning that there are stopped jobs.  The `jobs'
command may then be used to inspect their status.  If a second attempt
to exit is made without an intervening command, Bash does not print
another warning, and the stopped jobs are terminated.


File: bashref.info,  Node: Job Control Builtins,  Next: Job Control Variables,  Prev: Job Control Basics,  Up: Job Control

Job Control Builtins
====================

`bg'
          bg [JOBSPEC]
     Resume the suspended job JOBSPEC in the background, as if it had
     been started with `&'.  If JOBSPEC is not supplied, the current
     job is used.  The return status is zero unless it is run when job
     control is not enabled, or, when run with job control enabled, if
     JOBSPEC was not found or JOBSPEC specifies a job that was started
     without job control.

`fg'
          fg [JOBSPEC]
     Resume the job JOBSPEC in the foreground and make it the current
     job.  If JOBSPEC is not supplied, the current job is used.  The
     return status is that of the command placed into the foreground,
     or non-zero if run when job control is disabled or, when run with
     job control enabled, JOBSPEC does not specify a valid job or
     JOBSPEC specifies a job that was started without job control.

`jobs'
          jobs [-lnprs] [JOBSPEC]
          jobs -x COMMAND [ARGUMENTS]

     The first form lists the active jobs.  The options have the
     following meanings:

    `-l'
          List process IDs in addition to the normal information.

    `-n'
          Display information only about jobs that have changed status
          since the user was last notified of their status.

    `-p'
          List only the process ID of the job's process group leader.

    `-r'
          Restrict output to running jobs.

    `-s'
          Restrict output to stopped jobs.

     If JOBSPEC is given, output is restricted to information about
     that job.  If JOBSPEC is not supplied, the status of all jobs is
     listed.

     If the `-x' option is supplied, `jobs' replaces any JOBSPEC found
     in COMMAND or ARGUMENTS with the corresponding process group ID,
     and executes COMMAND, passing it ARGUMENTs, returning its exit
     status.

`kill'
          kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID
          kill -l [EXIT_STATUS]
     Send a signal specified by SIGSPEC or SIGNUM to the process named
     by job specification JOBSPEC or process ID PID.  SIGSPEC is either
     a signal name such as `SIGINT' (with or without the `SIG' prefix)
     or a signal number; SIGNUM is a signal number.  If SIGSPEC and
     SIGNUM are not present, `SIGTERM' is used.  The `-l' option lists
     the signal names.  If any arguments are supplied when `-l' is
     given, the names of the signals corresponding to the arguments are
     listed, and the return status is zero.  EXIT_STATUS is a number
     specifying a signal number or the exit status of a process
     terminated by a signal.  The return status is zero if at least one
     signal was successfully sent, or non-zero if an error occurs or an
     invalid option is encountered.

`wait'
          wait [JOBSPEC or PID]
     Wait until the child process specified by process ID PID or job
     specification JOBSPEC exits and return the exit status of the last
     command waited for.  If a job spec is given, all processes in the
     job are waited for.  If no arguments are given, all currently
     active child processes are waited for, and the return status is
     zero.  If neither JOBSPEC nor PID specifies an active child process
     of the shell, the return status is 127.

`disown'
          disown [-ar] [-h] [JOBSPEC ...]
     Without options, each JOBSPEC is removed from the table of active
     jobs.  If the `-h' option is given, the job is not removed from
     the table, but is marked so that `SIGHUP' is not sent to the job
     if the shell receives a `SIGHUP'.  If JOBSPEC is not present, and
     neither the `-a' nor `-r' option is supplied, the current job is
     used.  If no JOBSPEC is supplied, the `-a' option means to remove
     or mark all jobs; the `-r' option without a JOBSPEC argument
     restricts operation to running jobs.

`suspend'
          suspend [-f]
     Suspend the execution of this shell until it receives a `SIGCONT'
     signal.  The `-f' option means to suspend even if the shell is a
     login shell.

   When job control is not active, the `kill' and `wait' builtins do
not accept JOBSPEC arguments.  They must be supplied process IDs.


File: bashref.info,  Node: Job Control Variables,  Prev: Job Control Builtins,  Up: Job Control

Job Control Variables
=====================

`auto_resume'
     This variable controls how the shell interacts with the user and
     job control.  If this variable exists then single word simple
     commands without redirections are treated as candidates for
     resumption of an existing job.  There is no ambiguity allowed; if
     there is more than one job beginning with the string typed, then
     the most recently accessed job will be selected.  The name of a
     stopped job, in this context, is the command line used to start
     it.  If this variable is set to the value `exact', the string
     supplied must match the name of a stopped job exactly; if set to
     `substring', the string supplied needs to match a substring of the
     name of a stopped job.  The `substring' value provides
     functionality analogous to the `%?' job ID (*note Job Control
     Basics::).  If set to any other value, the supplied string must be
     a prefix of a stopped job's name; this provides functionality
     analogous to the `%' job ID.


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

Command Line Editing
********************

   This chapter describes the basic features of the GNU command line
editing interface.  Command line editing is provided by the Readline
library, which is used by several different programs, including Bash.

* Menu:

* Introduction and Notation::	Notation used in this text.
* Readline Interaction::	The minimum set of commands for editing a line.
* Readline Init File::		Customizing Readline from a user's view.
* Bindable Readline Commands::	A description of most of the Readline commands
				available for binding
* Readline vi Mode::		A short description of how to make Readline
				behave like the vi editor.

* Programmable Completion::	How to specify the possible completions for
				a specific command.
* Programmable Completion Builtins::	Builtin commands to specify how to
				complete arguments for a particular command.


File: bashref.info,  Node: Introduction and Notation,  Next: Readline Interaction,  Up: Command Line Editing

Introduction to Line Editing
============================

   The following paragraphs describe the notation used to represent
keystrokes.

   The text `C-k' is read as `Control-K' and describes the character
produced when the <k> key is pressed while the Control key is depressed.

   The text `M-k' is read as `Meta-K' and describes the character
produced when the Meta key (if you have one) is depressed, and the <k>
key is pressed.  The Meta key is labeled <ALT> on many keyboards.  On
keyboards with two keys labeled <ALT> (usually to either side of the
space bar), the <ALT> on the left side is generally set to work as a
Meta key.  The <ALT> key on the right may also be configured to work as
a Meta key or may be configured as some other modifier, such as a
Compose key for typing accented characters.

   If you do not have a Meta or <ALT> key, or another key working as a
Meta key, the identical keystroke can be generated by typing <ESC>
_first_, and then typing <k>.  Either process is known as "metafying"
the <k> key.

   The text `M-C-k' is read as `Meta-Control-k' and describes the
character produced by "metafying" `C-k'.

   In addition, several keys have their own names.  Specifically,
<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
when seen in this text, or in an init file (*note Readline Init File::).
If your keyboard lacks a <LFD> key, typing <C-j> will produce the
desired character.  The <RET> key may be labeled <Return> or <Enter> on
some keyboards.


File: bashref.info,  Node: Readline Interaction,  Next: Readline Init File,  Prev: Introduction and Notation,  Up: Command Line Editing

Readline Interaction
====================

   Often during an interactive session you type in a long line of text,
only to notice that the first word on the line is misspelled.  The
Readline library gives you a set of commands for manipulating the text
as you type it in, allowing you to just fix your typo, and not forcing
you to retype the majority of the line.  Using these editing commands,
you move the cursor to the place that needs correction, and delete or
insert the text of the corrections.  Then, when you are satisfied with
the line, you simply press <RET>.  You do not have to be at the end of
the line to press <RET>; the entire line is accepted regardless of the
location of the cursor within the line.

* Menu:

* Readline Bare Essentials::	The least you need to know about Readline.
* Readline Movement Commands::	Moving about the input line.
* Readline Killing Commands::	How to delete text, and how to get it back!
* Readline Arguments::		Giving numeric arguments to commands.
* Searching::			Searching through previous lines.


File: bashref.info,  Node: Readline Bare Essentials,  Next: Readline Movement Commands,  Up: Readline Interaction

Readline Bare Essentials
------------------------

   In order to enter characters into the line, simply type them.  The
typed character appears where the cursor was, and then the cursor moves
one space to the right.  If you mistype a character, you can use your
erase character to back up and delete the mistyped character.

   Sometimes you may mistype a character, and not notice the error
until you have typed several other characters.  In that case, you can
type `C-b' to move the cursor to the left, and then correct your
mistake.  Afterwards, you can move the cursor to the right with `C-f'.

   When you add text in the middle of a line, you will notice that
characters to the right of the cursor are `pushed over' to make room
for the text that you have inserted.  Likewise, when you delete text
behind the cursor, characters to the right of the cursor are `pulled
back' to fill in the blank space created by the removal of the text.  A
list of the bare essentials for editing the text of an input line
follows.

`C-b'
     Move back one character.

`C-f'
     Move forward one character.

<DEL> or <Backspace>
     Delete the character to the left of the cursor.

`C-d'
     Delete the character underneath the cursor.

Printing characters
     Insert the character into the line at the cursor.

`C-_' or `C-x C-u'
     Undo the last editing command.  You can undo all the way back to an
     empty line.

(Depending on your configuration, the <Backspace> key be set to delete
the character to the left of the cursor and the <DEL> key set to delete
the character underneath the cursor, like `C-d', rather than the
character to the left of the cursor.)


File: bashref.info,  Node: Readline Movement Commands,  Next: Readline Killing Commands,  Prev: Readline Bare Essentials,  Up: Readline Interaction

Readline Movement Commands
--------------------------

   The above table describes the most basic keystrokes that you need in
order to do editing of the input line.  For your convenience, many
other commands have been added in addition to `C-b', `C-f', `C-d', and
<DEL>.  Here are some commands for moving more rapidly about the line.

`C-a'
     Move to the start of the line.

`C-e'
     Move to the end of the line.

`M-f'
     Move forward a word, where a word is composed of letters and
     digits.

`M-b'
     Move backward a word.

`C-l'
     Clear the screen, reprinting the current line at the top.

   Notice how `C-f' moves forward a character, while `M-f' moves
forward a word.  It is a loose convention that control keystrokes
operate on characters while meta keystrokes operate on words.


File: bashref.info,  Node: Readline Killing Commands,  Next: Readline Arguments,  Prev: Readline Movement Commands,  Up: Readline Interaction

Readline Killing Commands
-------------------------

   "Killing" text means to delete the text from the line, but to save
it away for later use, usually by "yanking" (re-inserting) it back into
the line.  (`Cut' and `paste' are more recent jargon for `kill' and
`yank'.)

   If the description for a command says that it `kills' text, then you
can be sure that you can get the text back in a different (or the same)
place later.

   When you use a kill command, the text is saved in a "kill-ring".
Any number of consecutive kills save all of the killed text together, so
that when you yank it back, you get it all.  The kill ring is not line
specific; the text that you killed on a previously typed line is
available to be yanked back later, when you are typing another line.

   Here is the list of commands for killing text.

`C-k'
     Kill the text from the current cursor position to the end of the
     line.

`M-d'
     Kill from the cursor to the end of the current word, or, if between
     words, to the end of the next word.  Word boundaries are the same
     as those used by `M-f'.

`M-<DEL>'
     Kill from the cursor the start of the current word, or, if between
     words, to the start of the previous word.  Word boundaries are the
     same as those used by `M-b'.

`C-w'
     Kill from the cursor to the previous whitespace.  This is
     different than `M-<DEL>' because the word boundaries differ.

   Here is how to "yank" the text back into the line.  Yanking means to
copy the most-recently-killed text from the kill buffer.

`C-y'
     Yank the most recently killed text back into the buffer at the
     cursor.

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


File: bashref.info,  Node: Readline Arguments,  Next: Searching,  Prev: Readline Killing Commands,  Up: Readline Interaction

Readline Arguments
------------------

   You can pass numeric arguments to Readline commands.  Sometimes the
argument acts as a repeat count, other times it is the sign of the
argument that is significant.  If you pass a negative argument to a
command which normally acts in a forward direction, that command will
act in a backward direction.  For example, to kill text back to the
start of the line, you might type `M-- C-k'.

   The general way to pass numeric arguments to a command is to type
meta digits before the command.  If the first `digit' typed is a minus
sign (`-'), then the sign of the argument will be negative.  Once you
have typed one meta digit to get the argument started, you can type the
remainder of the digits, and then the command.  For example, to give
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
will delete the next ten characters on the input line.


File: bashref.info,  Node: Searching,  Prev: Readline Arguments,  Up: Readline Interaction

Searching for Commands in the History
-------------------------------------

   Readline provides commands for searching through the command history
(*note Bash History Facilities::) for lines containing a specified
string.  There are two search modes:  "incremental" and
"non-incremental".

   Incremental searches begin before the user has finished typing the
search string.  As each character of the search string is typed,
Readline displays the next entry from the history matching the string
typed so far.  An incremental search requires only as many characters
as needed to find the desired history entry.  To search backward in the
history for a particular string, type `C-r'.  Typing `C-s' searches
forward through the history.  The characters present in the value of
the `isearch-terminators' variable are used to terminate an incremental
search.  If that variable has not been assigned a value, the <ESC> and
`C-J' characters will terminate an incremental search.  `C-g' will
abort an incremental search and restore the original line.  When the
search is terminated, the history entry containing the search string
becomes the current line.

   To find other matching entries in the history list, type `C-r' or
`C-s' as appropriate.  This will search backward or forward in the
history for the next entry matching the search string typed so far.
Any other key sequence bound to a Readline command will terminate the
search and execute that command.  For instance, a <RET> will terminate
the search and accept the line, thereby executing the command from the
history list.  A movement command will terminate the search, make the
last line found the current line, and begin editing.

   Readline remembers the last incremental search string.  If two
`C-r's are typed without any intervening characters defining a new
search string, any remembered search string is used.

   Non-incremental searches read the entire search string before
starting to search for matching history lines.  The search string may be
typed by the user or be part of the contents of the current line.


File: bashref.info,  Node: Readline Init File,  Next: Bindable Readline Commands,  Prev: Readline Interaction,  Up: Command Line Editing

Readline Init File
==================

   Although the Readline library comes with a set of Emacs-like
keybindings installed by default, it is possible to use a different set
of keybindings.  Any user can customize programs that use Readline by
putting commands in an "inputrc" file, conventionally in his home
directory.  The name of this file is taken from the value of the shell
variable `INPUTRC'.  If that variable is unset, the default is
`~/.inputrc'.

   When a program which uses the Readline library starts up, the init
file is read, and the key bindings are set.

   In addition, the `C-x C-r' command re-reads this init file, thus
incorporating any changes that you might have made to it.

* Menu:

* Readline Init File Syntax::	Syntax for the commands in the inputrc file.

* Conditional Init Constructs::	Conditional key bindings in the inputrc file.

* Sample Init File::		An example inputrc file.


File: bashref.info,  Node: Readline Init File Syntax,  Next: Conditional Init Constructs,  Up: Readline Init File

Readline Init File Syntax
-------------------------

   There are only a few basic constructs allowed in the Readline init
file.  Blank lines are ignored.  Lines beginning with a `#' are
comments.  Lines beginning with a `$' indicate conditional constructs
(*note Conditional Init Constructs::).  Other lines denote variable
settings and key bindings.

Variable Settings
     You can modify the run-time behavior of Readline by altering the
     values of variables in Readline using the `set' command within the
     init file.  The syntax is simple:

          set VARIABLE VALUE

     Here, for example, is how to change from the default Emacs-like
     key binding to use `vi' line editing commands:

          set editing-mode vi

     Variable names and values, where appropriate, are recognized
     without regard to case.

     The `bind -V' command lists the current Readline variable names
     and values.  *Note Bash Builtins::.

     A great deal of run-time behavior is changeable with the following
     variables.

    `bell-style'
          Controls what happens when Readline wants to ring the
          terminal bell.  If set to `none', Readline never rings the
          bell.  If set to `visible', Readline uses a visible bell if
          one is available.  If set to `audible' (the default),
          Readline attempts to ring the terminal's bell.

    `comment-begin'
          The string to insert at the beginning of the line when the
          `insert-comment' command is executed.  The default value is
          `"#"'.

    `completion-ignore-case'
          If set to `on', Readline performs filename matching and
          completion in a case-insensitive fashion.  The default value
          is `off'.

    `completion-query-items'
          The number of possible completions that determines when the
          user is asked whether he wants to see the list of
          possibilities.  If the number of possible completions is
          greater than this value, Readline will ask the user whether
          or not he wishes to view them; otherwise, they are simply
          listed.  This variable must be set to an integer value
          greater than or equal to 0.  The default limit is `100'.

    `convert-meta'
          If set to `on', Readline will convert characters with the
          eighth bit set to an ASCII key sequence by stripping the
          eighth bit and prefixing an <ESC> character, converting them
          to a meta-prefixed key sequence.  The default value is `on'.

    `disable-completion'
          If set to `On', Readline will inhibit word completion.
          Completion  characters will be inserted into the line as if
          they had been mapped to `self-insert'.  The default is `off'.

    `editing-mode'
          The `editing-mode' variable controls which default set of key
          bindings is used.  By default, Readline starts up in Emacs
          editing mode, where the keystrokes are most similar to Emacs.
          This variable can be set to either `emacs' or `vi'.

    `enable-keypad'
          When set to `on', Readline will try to enable the application
          keypad when it is called.  Some systems need this to enable
          the arrow keys.  The default is `off'.

    `expand-tilde'
          If set to `on', tilde expansion is performed when Readline
          attempts word completion.  The default is `off'.

          If set to `on', the history code attempts to place point at
          the same location on each history line retrived with
          `previous-history' or `next-history'.

    `horizontal-scroll-mode'
          This variable can be set to either `on' or `off'.  Setting it
          to `on' means that the text of the lines being edited will
          scroll horizontally on a single screen line when they are
          longer than the width of the screen, instead of wrapping onto
          a new screen line.  By default, this variable is set to `off'.

    `input-meta'
          If set to `on', Readline will enable eight-bit input (it will
          not clear the eighth bit in the characters it reads),
          regardless of what the terminal claims it can support.  The
          default value is `off'.  The name `meta-flag' is a synonym
          for this variable.

    `isearch-terminators'
          The string of characters that should terminate an incremental
          search without subsequently executing the character as a
          command (*note Searching::).  If this variable has not been
          given a value, the characters <ESC> and `C-J' will terminate
          an incremental search.

    `keymap'
          Sets Readline's idea of the current keymap for key binding
          commands.  Acceptable `keymap' names are `emacs',
          `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
          `vi-command', and `vi-insert'.  `vi' is equivalent to
          `vi-command'; `emacs' is equivalent to `emacs-standard'.  The
          default value is `emacs'.  The value of the `editing-mode'
          variable also affects the default keymap.

    `mark-directories'
          If set to `on', completed directory names have a slash
          appended.  The default is `on'.

    `mark-modified-lines'
          This variable, when set to `on', causes Readline to display an
          asterisk (`*') at the start of history lines which have been
          modified.  This variable is `off' by default.

    `match-hidden-files'
          This variable, when set to `on', causes Readline to match
          files whose names begin with a `.' (hidden files) when
          performing filename completion, unless the leading `.' is
          supplied by the user in the filename to be completed.  This
          variable is `on' by default.

    `output-meta'
          If set to `on', Readline will display characters with the
          eighth bit set directly rather than as a meta-prefixed escape
          sequence.  The default is `off'.

    `print-completions-horizontally'
          If set to `on', Readline will display completions with matches
          sorted horizontally in alphabetical order, rather than down
          the screen.  The default is `off'.

    `show-all-if-ambiguous'
          This alters the default behavior of the completion functions.
          If set to `on', words which have more than one possible
          completion cause the matches to be listed immediately instead
          of ringing the bell.  The default value is `off'.

    `visible-stats'
          If set to `on', a character denoting a file's type is
          appended to the filename when listing possible completions.
          The default is `off'.

Key Bindings
     The syntax for controlling key bindings in the init file is
     simple.  First you need to find the name of the command that you
     want to change.  The following sections contain tables of the
     command name, the default keybinding, if any, and a short
     description of what the command does.

     Once you know the name of the command, simply place on a line in
     the init file the name of the key you wish to bind the command to,
     a colon, and then the name of the command.  The name of the key
     can be expressed in different ways, depending on what you find most
     comfortable.

     In addition to command names, readline allows keys to be bound to
     a string that is inserted when the key is pressed (a MACRO).

     The `bind -p' command displays Readline function names and
     bindings in a format that can put directly into an initialization
     file.  *Note Bash Builtins::.

    KEYNAME: FUNCTION-NAME or MACRO
          KEYNAME is the name of a key spelled out in English.  For
          example:
               Control-u: universal-argument
               Meta-Rubout: backward-kill-word
               Control-o: "> output"

          In the above example, `C-u' is bound to the function
          `universal-argument', `M-DEL' is bound to the function
          `backward-kill-word', and `C-o' is bound to run the macro
          expressed on the right hand side (that is, to insert the text
          `> output' into the line).

          A number of symbolic character names are recognized while
          processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
          NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.

    "KEYSEQ": FUNCTION-NAME or MACRO
          KEYSEQ differs from KEYNAME above in that strings denoting an
          entire key sequence can be specified, by placing the key
          sequence in double quotes.  Some GNU Emacs style key escapes
          can be used, as in the following example, but the special
          character names are not recognized.

               "\C-u": universal-argument
               "\C-x\C-r": re-read-init-file
               "\e[11~": "Function Key 1"

          In the above example, `C-u' is again bound to the function
          `universal-argument' (just as it was in the first example),
          `C-x C-r' is bound to the function `re-read-init-file', and
          `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
          Key 1'.

     The following GNU Emacs style escape sequences are available when
     specifying key sequences:

    `\C-'
          control prefix

    `\M-'
          meta prefix

    `\e'
          an escape character

    `\\'
          backslash

    `\"'
          <">, a double quotation mark

    `\''
          <'>, a single quote or apostrophe

     In addition to the GNU Emacs style escape sequences, a second set
     of backslash escapes is available:

    `\a'
          alert (bell)

    `\b'
          backspace

    `\d'
          delete

    `\f'
          form feed

    `\n'
          newline

    `\r'
          carriage return

    `\t'
          horizontal tab

    `\v'
          vertical tab

    `\NNN'
          the eight-bit character whose value is the octal value NNN
          (one to three digits)

    `\xHH'
          the eight-bit character whose value is the hexadecimal value
          HH (one or two hex digits)

     When entering the text of a macro, single or double quotes must be
     used to indicate a macro definition.  Unquoted text is assumed to
     be a function name.  In the macro body, the backslash escapes
     described above are expanded.  Backslash will quote any other
     character in the macro text, including `"' and `''.  For example,
     the following binding will make `C-x \' insert a single `\' into
     the line:
          "\C-x\\": "\\"


File: bashref.info,  Node: Conditional Init Constructs,  Next: Sample Init File,  Prev: Readline Init File Syntax,  Up: Readline Init File

Conditional Init Constructs
---------------------------

   Readline implements a facility similar in spirit to the conditional
compilation features of the C preprocessor which allows key bindings
and variable settings to be performed as the result of tests.  There
are four parser directives used.

`$if'
     The `$if' construct allows bindings to be made based on the
     editing mode, the terminal being used, or the application using
     Readline.  The text of the test extends to the end of the line; no
     characters are required to isolate it.

    `mode'
          The `mode=' form of the `$if' directive is used to test
          whether Readline is in `emacs' or `vi' mode.  This may be
          used in conjunction with the `set keymap' command, for
          instance, to set bindings in the `emacs-standard' and
          `emacs-ctlx' keymaps only if Readline is starting out in
          `emacs' mode.

    `term'
          The `term=' form may be used to include terminal-specific key
          bindings, perhaps to bind the key sequences output by the
          terminal's function keys.  The word on the right side of the
          `=' is tested against both the full name of the terminal and
          the portion of the terminal name before the first `-'.  This
          allows `sun' to match both `sun' and `sun-cmd', for instance.

    `application'
          The APPLICATION construct is used to include
          application-specific settings.  Each program using the
          Readline library sets the APPLICATION NAME, and you can test
          for a particular value.  This could be used to bind key
          sequences to functions useful for a specific program.  For
          instance, the following command adds a key sequence that
          quotes the current or previous word in Bash:
               $if Bash
               # Quote the current or previous word
               "\C-xq": "\eb\"\ef\""
               $endif

`$endif'
     This command, as seen in the previous example, terminates an `$if'
     command.

`$else'
     Commands in this branch of the `$if' directive are executed if the
     test fails.

`$include'
     This directive takes a single filename as an argument and reads
     commands and bindings from that file.  For example, the following
     directive reads from `/etc/inputrc':
          $include /etc/inputrc


File: bashref.info,  Node: Sample Init File,  Prev: Conditional Init Constructs,  Up: Readline Init File

Sample Init File
----------------

   Here is an example of an INPUTRC file.  This illustrates key
binding, variable assignment, and conditional syntax.


     # This file controls the behaviour of line input editing for
     # programs that use the Gnu Readline library.  Existing programs
     # include FTP, Bash, and Gdb.
     #
     # You can re-read the inputrc file with C-x C-r.
     # Lines beginning with '#' are comments.
     #
     # First, include any systemwide bindings and variable assignments from
     # /etc/Inputrc
     $include /etc/Inputrc
     
     #
     # Set various bindings for emacs mode.
     
     set editing-mode emacs
     
     $if mode=emacs
     
     Meta-Control-h:	backward-kill-word	Text after the function name is ignored
     
     #
     # Arrow keys in keypad mode
     #
     #"\M-OD":        backward-char
     #"\M-OC":        forward-char
     #"\M-OA":        previous-history
     #"\M-OB":        next-history
     #
     # Arrow keys in ANSI mode
     #
     "\M-[D":        backward-char
     "\M-[C":        forward-char
     "\M-[A":        previous-history
     "\M-[B":        next-history
     #
     # Arrow keys in 8 bit keypad mode
     #
     #"\M-\C-OD":       backward-char
     #"\M-\C-OC":       forward-char
     #"\M-\C-OA":       previous-history
     #"\M-\C-OB":       next-history
     #
     # Arrow keys in 8 bit ANSI mode
     #
     #"\M-\C-[D":       backward-char
     #"\M-\C-[C":       forward-char
     #"\M-\C-[A":       previous-history
     #"\M-\C-[B":       next-history
     
     C-q: quoted-insert
     
     $endif
     
     # An old-style binding.  This happens to be the default.
     TAB: complete
     
     # Macros that are convenient for shell interaction
     $if Bash
     # edit the path
     "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
     # prepare to type a quoted word -- insert open and close double quotes
     # and move to just after the open quote
     "\C-x\"": "\"\"\C-b"
     # insert a backslash (testing backslash escapes in sequences and macros)
     "\C-x\\": "\\"
     # Quote the current or previous word
     "\C-xq": "\eb\"\ef\""
     # Add a binding to refresh the line, which is unbound
     "\C-xr": redraw-current-line
     # Edit variable on current line.
     "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
     $endif
     
     # use a visible bell if one is available
     set bell-style visible
     
     # don't strip characters to 7 bits when reading
     set input-meta on
     
     # allow iso-latin1 characters to be inserted rather than converted to
     # prefix-meta sequences
     set convert-meta off
     
     # display characters with the eighth bit set directly rather than
     # as meta-prefixed characters
     set output-meta on
     
     # if there are more than 150 possible completions for a word, ask the
     # user if he wants to see all of them
     set completion-query-items 150
     
     # For FTP
     $if Ftp
     "\C-xg": "get \M-?"
     "\C-xt": "put \M-?"
     "\M-.": yank-last-arg
     $endif


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

Bindable Readline Commands
==========================

* Menu:

* Commands For Moving::		Moving about the line.
* Commands For History::	Getting at previous lines.
* Commands For Text::		Commands for changing text.
* Commands For Killing::	Commands for killing and yanking.
* Numeric Arguments::		Specifying numeric arguments, repeat counts.
* Commands For Completion::	Getting Readline to do the typing for you.
* Keyboard Macros::		Saving and re-executing typed characters
* Miscellaneous Commands::	Other miscellaneous commands.

   This section describes Readline commands that may be bound to key
sequences.  You can list your key bindings by executing `bind -P' or,
for a more terse format, suitable for an INPUTRC file, `bind -p'.
(*Note Bash Builtins::.)  Command names without an accompanying key
sequence are unbound by default.

   In the following descriptions, "point" refers to the current cursor
position, and "mark" refers to a cursor position saved by the
`set-mark' command.  The text between the point and mark is referred to
as the "region".


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

Commands For Moving
-------------------

`beginning-of-line (C-a)'
     Move to the start of the current line.

`end-of-line (C-e)'
     Move to the end of the line.

`forward-char (C-f)'
     Move forward a character.

`backward-char (C-b)'
     Move back a character.

`forward-word (M-f)'
     Move forward to the end of the next word.  Words are composed of
     letters and digits.

`backward-word (M-b)'
     Move back to the start of the current or previous word.  Words are
     composed of letters and digits.

`clear-screen (C-l)'
     Clear the screen and redraw the current line, leaving the current
     line at the top of the screen.

`redraw-current-line ()'
     Refresh the current line.  By default, this is unbound.

