GNU Readline Library
Edition 6.2, for Readline Library Version 6.2.
September 2010
Chet Ramey, Case Western Reserve University
Brian Fox, Free Software Foundation
This manual describes the GNU Readline Library (version 6.2, September 6 2010), a library
which aids in the consistency of user interface across discrete programs which provide a
command line interface.
Copyright
c
° 1988–2011 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the
copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant Sections,
with the Front-Cover texts being “A GNU Manual”, and with the Back-Cover
Texts as in (a) below. A copy of the license is included in the section entitled
“GNU Free Documentation License”.
(a) The FSF’s Back-Cover Text is: You are free to copy and modify this GNU
manual. Buying copies from GNU Press supports the FSF in developing GNU
and promoting software freedom.”
Published by the Free Software Foundation
59 Temple Place, Suite 330,
Boston, MA 02111-1307
USA
i
Table of Contents
1 Command Line Editing . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Introduction to Line Editing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Readline Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2.1 Readline Bare Essentials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2.2 Readline Movement Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.3 Readline Killing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.4 Readline Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.5 Searching for Commands in the History. . . . . . . . . . . . . . . . . . . . 3
1.3 Readline Init File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.1 Readline Init File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.2 Conditional Init Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.3 Sample Init File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4 Bindable Readline Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.4.1 Commands For Moving. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.4.2 Commands For Manipulating The History . . . . . . . . . . . . . . . . 14
1.4.3 Commands For Changing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.4.4 Killing And Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.5 Specifying Numeric Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.4.6 Letting Readline Type For You . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.4.7 Keyboard Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.4.8 Some Miscellaneous Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.5 Readline vi Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2 Programming with GNU Readline . . . . . . . . . . . 22
2.1 Basic Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2 Custom Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.2.1 Readline Typedefs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.2.2 Writing a New Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.3 Readline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4 Readline Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.4.1 Naming a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.4.2 Selecting a Keymap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.4.3 Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.4.4 Associating Function Names and Bindings . . . . . . . . . . . . . . . . 32
2.4.5 Allowing Undoing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.4.6 Redisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4.7 Modifying Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.4.8 Character Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.4.9 Terminal Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.4.10 Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.4.11 Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.4.12 Alternate Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.4.13 A Readline Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
ii
2.5 Readline Signal Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.6 Custom Completers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.6.1 How Completing Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.6.2 Completion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.6.3 Completion Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.6.4 A Short Completion Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Appendix A GNU Free Documentation License
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Function and Variable Index . . . . . . . . . . . . . . . . . . . . . 67
Chapter 1: Command Line Editing 1
1 Command Line Editing
This chapter describes the basic features of the gnu command line editing interface.
1.1 Introduction to Line Editing
The following paragraphs describe the notation used to represent keystrokes.
The text C-k is read as ‘Control-K’ and describes the character produced when the k
key is pressed while the Control key is depressed.
The text M-k is read as ‘Meta-K’ and describes the character produced when the Meta
key (if you have one) is depressed, and the k key is pressed. The Meta key is labeled ALT
on many keyboards. On keyboards with two keys labeled ALT (usually to either side of the
space bar), the ALT on the left side is generally set to work as a Meta key. The ALT key on
the right may also be configured to work as a Meta key or may be configured as some other
modifier, such as a Compose key for typing accented characters.
If you do not have a Meta or ALT key, or another key working as a Meta key, the identical
keystroke can be generated by typing ESC first, and then typing k. Either process is known
as metafying the k key.
The text M-C-k is read as ‘Meta-Control-k’ and describes the character produced by
metafying C-k.
In addition, several keys have their own names. Specifically, DEL, ESC, LFD, SPC, RET,
and TAB all stand for themselves when seen in this text, or in an init file (see Section 1.3
[Readline Init File], page 4). 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.
1.2 Readline Interaction
Often during an interactive session you type in a long line of text, only to notice that the
first word on the line is misspelled. The Readline library gives you a set of commands for
manipulating the text as you type it in, allowing you to just fix your typo, and not forcing
you to retype the majority of the line. Using these editing commands, you move the cursor
to the place that needs correction, and delete or insert the text of the corrections. Then,
when you are satisfied with the line, you simply press RET. You do not have to be at the end
of the line to press RET; the entire line is accepted regardless of the location of the cursor
within the line.
1.2.1 Readline Bare Essentials
In order to enter characters into the line, simply type them. The typed character appears
where the cursor was, and then the cursor moves one space to the right. If you mistype a
character, you can use your erase character to back up and delete the mistyped character.
Sometimes you may mistype a character, and not notice the error until you have typed
several other characters. In that case, you can type C-b to move the cursor to the left, and
then correct your mistake. Afterwards, you can move the cursor to the right with C-f.
When you add text in the middle of a line, you will notice that characters to the right
of the cursor are ‘pushed over’ to make room for the text that you have inserted. Likewise,
when you delete text behind the cursor, characters to the right of the cursor are ‘pulled