GNU Readline Library
Edition 8.2, for Readline Library Version 8.2.
September 2022
Chet Ramey, Case Western Reserve University
Brian Fox, Free Software Foundation
This manual describes the GNU Readline Library (version 8.2, 19 September 2022), a library
which aids in the consistency of user interface across discrete programs which provide a
command line interface.
Copyright
c
1988–2022 Free Software Foundation, Inc.
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, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
in the section entitled “GNU Free Documentation License”.
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.3 Sample Init File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.4 Bindable Readline Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.1 Commands For Moving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.2 Commands For Manipulating The History . . . . . . . . . . . . . . . . 18
1.4.3 Commands For Changing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.4.4 Killing And Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.4.5 Specifying Numeric Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.4.6 Letting Readline Type For You . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.4.7 Keyboard Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.4.8 Some Miscellaneous Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.5 Readline vi Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2 Programming with GNU Readline . . . . . . . . . . . 26
2.1 Basic Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2 Custom Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.2.1 Readline Typedefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.2 Writing a New Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.3 Readline Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.4 Readline Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4.1 Naming a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4.2 Selecting a Keymap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.4.3 Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.4.4 Associating Function Names and Bindings . . . . . . . . . . . . . . . . 38
2.4.5 Allowing Undoing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.4.6 Redisplay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.4.7 Modifying Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.4.8 Character Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.4.9 Terminal Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.4.10 Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.4.11 Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.4.12 Alternate Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.4.13 A Readline Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
ii
2.4.14 Alternate Interface Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.5 Readline Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.6 Custom Completers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.6.1 How Completing Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.6.2 Completion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2.6.3 Completion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.6.4 A Short Completion Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Appendix A GNU Free Documentation License . . 70
Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Function and Variable Index . . . . . . . . . . . . . . . . . . . . . . 79
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
