.\" Case Western Reserve University
.\" chet@ins.CWRU.Edu
.\"
-.\" Last Change: Tue Jan 22 09:18:25 EST 2002
+.\" Last Change: Sat Aug 28 18:56:32 EDT 2010
.\"
-.TH READLINE 3 "2002 January 22" "GNU Readline 4.3"
+.TH READLINE 3 "2010 August 28" "GNU Readline 6.2"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
\fBreadline\fP (\fIconst char *prompt\fP);
.fi
.SH COPYRIGHT
-.if n Readline is Copyright (C) 1989\-2002 by the Free Software Foundation, Inc.
-.if t Readline is Copyright \(co 1989\-2002 by the Free Software Foundation, Inc.
+.if n Readline is Copyright (C) 1989\-2011 Free Software Foundation, Inc.
+.if t Readline is Copyright \(co 1989\-2011 Free Software Foundation, Inc.
.SH DESCRIPTION
.LP
.B readline
treated as a newline.
.SH NOTATION
.LP
-An emacs-style notation is used to denote
+An Emacs-style notation is used to denote
keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
means Control\-N. Similarly,
.I meta
.B INPUTRC
environment variable. If that variable is unset, the default is
.IR ~/.inputrc .
+If that file does not exist or cannot be read, the ultimate default is
+.IR /etc/inputrc .
When a program which uses the readline library starts up, the
init file is read, and the key bindings and variables are set.
There are only a few basic constructs allowed in the
it should be bound. The name may be specified in one of two ways:
as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
prefixes, or as a key sequence.
+The name and key sequence are separated by a colon. There can be no
+whitespace between the name and the colon.
.PP
When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP,
.I keyname
or
.B Off
(without regard to case).
+Unrecognized variable names are ignored.
+When a variable value is read, empty or null values, "on" (case-insensitive),
+and "1" are equivalent to \fBOn\fP. All other values are equivalent to
+\fBOff\fP.
The variables and their default values are:
.PP
.PD 0
\fBvisible\fP, readline uses a visible bell if one is available.
If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
.TP
+.B bind\-tty\-special\-chars (On)
+If set to \fBOn\fP, readline attempts to bind the control characters
+treated specially by the kernel's terminal driver to their readline
+equivalents.
+.TP
.B comment\-begin (``#'')
The string that is inserted in \fBvi\fP mode when the
.B insert\-comment
in emacs mode and to
.B #
in vi command mode.
+.TP
+.B completion\-display\-width (-1)
+The number of screen columns used to display possible matches
+when performing completion.
+The value is ignored if it is less than 0 or greater than the terminal
+screen width.
+A value of 0 will cause matches to be displayed one per line.
+The default value is -1.
.TP
.B completion\-ignore\-case (Off)
If set to \fBOn\fP, readline performs filename matching and completion
in a case\-insensitive fashion.
.TP
+.B completion\-map\-case (Off)
+If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline
+treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
+performing case\-insensitive filename matching and completion.
+.TP
+.B completion\-prefix\-display\-length (0)
+The length in characters of the common prefix of a list of possible
+completions that is displayed without modification. When set to a
+value greater than zero, common prefixes longer than this value are
+replaced with an ellipsis when displaying possible completions.
+.TP
.B completion\-query\-items (100)
This determines when the user is queried about viewing
the number of possible completions
zero. If the number of possible completions is greater than
or equal to the value of this variable, the user is asked whether
or not he wishes to view them; otherwise they are simply listed
-on the terminal.
+on the terminal. A negative value causes readline to never ask.
.TP
.B convert\-meta (On)
If set to \fBOn\fP, readline will convert characters with the
.TP
.B editing\-mode (emacs)
Controls whether readline begins with a set of key bindings similar
-to emacs or vi.
+to \fIEmacs\fP or \fIvi\fP.
.B editing\-mode
can be set to either
.B emacs
or
.BR vi .
.TP
+.B echo\-control\-characters (On)
+When set to \fBOn\fP, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.
+.TP
.B enable\-keypad (Off)
When set to \fBOn\fP, readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys.
.TP
+.B enable\-meta\-key (On)
+When set to \fBOn\fP, readline will try to enable any meta modifier
+key the terminal claims to support when it is called. On many terminals,
+the meta key is used to send eight-bit characters.
+.TP
.B expand\-tilde (Off)
-If set to \fBon\fP, tilde expansion is performed when readline
+If set to \fBOn\fP, tilde expansion is performed when readline
attempts word completion.
.TP
-.B history-preserve-point
-If set to \fBon\fP, the history code attempts to place point at the
-same location on each history line retrived with \fBprevious-history\fP
+.B history\-preserve\-point (Off)
+If set to \fBOn\fP, the history code attempts to place point at the
+same location on each history line retrieved with \fBprevious-history\fP
or \fBnext-history\fP.
.TP
+.B history\-size (0)
+Set the maximum number of history entries saved in the history list. If
+set to zero, the number of entries in the history list is not limited.
+.TP
.B horizontal\-scroll\-mode (Off)
When set to \fBOn\fP, makes readline use a single line for display,
scrolling the input horizontally on a single screen line when it
.B match\-hidden\-files (On)
This variable, when set to \fBOn\fP, causes readline to match files whose
names begin with a `.' (hidden files) when performing filename
-completion, unless the leading `.' is
+completion.
+If set to \fBOff\fP, the leading `.' must be
supplied by the user in the filename to be completed.
.TP
+.B menu\-complete\-display\-prefix (Off)
+If set to \fBOn\fP, menu completion displays the common prefix of the
+list of possible completions (which may be empty) before cycling through
+the list.
+.TP
.B output\-meta (Off)
If set to \fBOn\fP, readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
If set to \fBOn\fP, readline will display completions with matches
sorted horizontally in alphabetical order, rather than down the screen.
.TP
+.B revert\-all\-at\-newline (Off)
+If set to \fBOn\fP, readline will undo all changes to history lines
+before returning when \fBaccept\-line\fP is executed. By default,
+history lines may be modified and retain individual undo lists across
+calls to \fBreadline\fP.
+.TP
.B show\-all\-if\-ambiguous (Off)
This alters the default behavior of the completion functions. If
set to
-.BR on ,
+.BR On ,
words which have more than one possible completion cause the
matches to be listed immediately instead of ringing the bell.
.TP
+.B show\-all\-if\-unmodified (Off)
+This alters the default behavior of the completion functions in
+a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
+If set to
+.BR On ,
+words which have more than one possible completion without any
+possible partial completion (the possible completions don't share
+a common prefix) cause the matches to be listed immediately instead
+of ringing the bell.
+.TP
+.B skip\-completed\-text (Off)
+If set to \fBOn\fP, this alters the default completion behavior when
+inserting a single match into the line. It's only active when
+performing completion in the middle of a word. If enabled, readline
+does not insert characters from the completion that match characters
+after point in the word being completed, so portions of the word
+following the cursor are not duplicated.
+.TP
.B visible\-stats (Off)
If set to \fBOn\fP, a character denoting a file's type as reported
by \fIstat\fP(2) is appended to the filename when listing possible
file 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:
+key sequence that quotes the current or previous word in \fBbash\fP:
.sp 1
.RS
.nf
insert the \fIn\fPth word from the previous command (the words
in the previous command begin with word 0). A negative argument
inserts the \fIn\fPth word from the end of the previous command.
+Once the argument \fIn\fP is computed, the argument is extracted
+as if the "!\fIn\fP" history expansion had been specified.
.TP
.B
yank\-last\-arg (M\-.\^, M\-_\^)
Insert the last argument to the previous command (the last word of
-the previous history entry). With an argument,
-behave exactly like \fByank\-nth\-arg\fP.
+the previous history entry).
+With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
Successive calls to \fByank\-last\-arg\fP move back through the history
-list, inserting the last argument of each line in turn.
+list, inserting the last word (or the word specified by the argument to
+the first call) of each line in turn.
+Any numeric argument supplied to these successive calls determines
+the direction to move through the history. A negative argument switches
+the direction through the history (back or forward).
+The history expansion facilities are used to extract the last argument,
+as if the "!$" history expansion had been specified.
.PD
.SS Commands for Changing Text
.PP
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
.TP
+.B unix\-filename\-rubout
+Kill the word behind point, using white space and the slash character
+as the word boundaries.
+The killed text is saved on the kill-ring.
+.TP
.B delete\-horizontal\-space (M\-\e)
Delete all spaces and tabs around point.
.TP
.TP
.B possible\-completions (M\-?)
List the possible completions of the text before point.
+When displaying completions, readline sets the number of columns used
+for display to the value of \fBcompletion-display-width\fP, the value of
+the environment variable
+.SM
+.BR COLUMNS ,
+or the screen width, in that order.
.TP
.B insert\-completions (M\-*)
Insert all completions of the text before point
Repeated execution of \fBmenu\-complete\fP 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 \Bbell\-style\fP)
+(subject to the setting of \fBbell\-style\fP)
and the original text is restored.
An argument of \fIn\fP moves \fIn\fP positions forward in the list
of matches; a negative argument may be used to move backward
This command is intended to be bound to \fBTAB\fP, but is unbound
by default.
.TP
+.B menu\-complete\-backward
+Identical to \fBmenu\-complete\fP, but moves backward through the list
+of possible completions, as if \fBmenu\-complete\fP had been given a
+negative argument. This command is unbound by default.
+.TP
.B delete\-char\-or\-list
Deletes the character under the cursor if not at the beginning or
end of the line (like \fBdelete-char\fP).
A character is read and point is moved to the previous occurrence of that
character. A negative count searches for subsequent occurrences.
.TP
+.B skip\-csi\-sequence
+Read enough characters to consume a multi-key sequence such as those
+defined for keys like Home and End. Such sequences begin with a
+Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is
+bound to "\e[", keys producing such sequences will have no effect
+unless explicitly bound to a readline command, instead of inserting
+stray characters into the editing buffer. This is unbound by default,
+but usually bound to ESC\-[.
+.TP
.B insert\-comment (M\-#)
Without a numeric argument, the value of the readline
.B comment\-begin
.TP
.B dump\-macros
Print all of the readline key sequences bound to macros and the
-strings they ouput. If a numeric argument is supplied,
+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 \fIinputrc\fP file.
.TP
projects / deliverable / binutils-gdb.git / blobdiff