1READLINE(3) Library Functions Manual READLINE(3)
2
6 readline - get a line from a user with editing
7
9 #include <stdio.h>
10 #include <readline/readline.h>
11 #include <readline/history.h>
12 char *
14 readline (const char *prompt);
15
17 Readline is Copyright (C) 1989-2014 Free Software Foundation, Inc.
18
20 readline will read a line from the terminal and return it, using prompt
21 as a prompt. If prompt is NULL or the empty string, no prompt is
22 issued. The line returned is allocated with malloc(3); the caller must
23 free it when finished. The line returned has the final newline
24 removed, so only the text of the line remains.
25 readline offers editing capabilities while the user is entering the
27 line. By default, the line editing commands are similar to those of
28 emacs. A vi-style line editing interface is also available.
29 This manual page describes only the most basic use of readline. Much
31 more functionality is available; see The GNU Readline Library and The
32 GNU History Library for additional information.
33
35 readline returns the text of the line read. A blank line returns the
36 empty string. If EOF is encountered while reading a line, and the line
37 is empty, NULL is returned. If an EOF is read with a non-empty line,
38 it is treated as a newline.
39
41 An Emacs-style notation is used to denote keystrokes. Control keys are
42 denoted by C-key, e.g., C-n means Control-N. Similarly, meta keys are
43 denoted by M-key, so M-x means Meta-X. (On keyboards without a meta
44 key, M-x means ESC x, i.e., press the Escape key then the x key. This
45 makes ESC the meta prefix. The combination M-C-x means ESC-Control-x,
46 or press the Escape key then hold the Control key while pressing the x
47 key.)
48 Readline commands may be given numeric arguments, which normally act as
50 a repeat count. Sometimes, however, it is the sign of the argument
51 that is significant. Passing a negative argument to a command that
52 acts in the forward direction (e.g., kill-line) causes that command to
53 act in a backward direction. Commands whose behavior with arguments
54 deviates from this are noted below.
55 When a command is described as killing text, the text deleted is saved
57 for possible future retrieval (yanking). The killed text is saved in a
58 kill ring. Consecutive kills cause the text to be accumulated into one
59 unit, which can be yanked all at once. Commands which do not kill text
60 separate the chunks of text on the kill ring.
61
63 Readline is customized by putting commands in an initialization file
64 (the inputrc file). The name of this file is taken from the value of
65 the INPUTRC environment variable. If that variable is unset, the
66 default is ~/.inputrc. If that file does not exist or cannot be read,
67 the ultimate default is /etc/inputrc. When a program which uses the
68 readline library starts up, the init file is read, and the key bindings
69 and variables are set. There are only a few basic constructs allowed
70 in the readline init file. Blank lines are ignored. Lines beginning
71 with a # are comments. Lines beginning with a $ indicate conditional
72 constructs. Other lines denote key bindings and variable settings.
73 Each program using this library may add its own commands and bindings.
74 For example, placing
76 M-Control-u: universal-argument
78 or
79 C-Meta-u: universal-argument
80 into the inputrc would make M-C-u execute the readline command univer‐
82 sal-argument.
83 The following symbolic character names are recognized while processing
85 key bindings: DEL, ESC, ESCAPE, LFD, NEWLINE, RET, RETURN, RUBOUT,
86 SPACE, SPC, and TAB.
87 In addition to command names, readline allows keys to be bound to a
89 string that is inserted when the key is pressed (a macro).
90 Key Bindings
92 The syntax for controlling key bindings in the inputrc file is simple.
93 All that is required is the name of the command or the text of a macro
94 and a key sequence to which it should be bound. The name may be speci‐
95 fied in one of two ways: as a symbolic key name, possibly with Meta- or
96 Control- prefixes, or as a key sequence. The name and key sequence are
97 separated by a colon. There can be no whitespace between the name and
98 the colon.
99 When using the form keyname:function-name or macro, keyname is the name
101 of a key spelled out in English. For example:
102 Control-u: universal-argument
104 Meta-Rubout: backward-kill-word
105 Control-o: "> output"
106 In the above example, C-u is bound to the function universal-argument,
108 M-DEL is bound to the function backward-kill-word, and C-o is bound to
109 run the macro expressed on the right hand side (that is, to insert the
110 text ``> output'' into the line).
111 In the second form, "keyseq":function-name or macro, keyseq differs
113 from keyname above in that strings denoting an entire key sequence may
114 be specified by placing the sequence within double quotes. Some GNU
115 Emacs style key escapes can be used, as in the following example, but
116 the symbolic character names are not recognized.
117 "\C-u": universal-argument
119 "\C-x\C-r": re-read-init-file
120 "\e[11~": "Function Key 1"
121 In this example, C-u is again bound to the function universal-argument.
123 C-x C-r is bound to the function re-read-init-file, and ESC [ 1 1 ~ is
124 bound to insert the text ``Function Key 1''.
125 The full set of GNU Emacs style escape sequences available when speci‐
127 fying key sequences is
128 \C- control prefix
129 \M- meta prefix
130 \e an escape character
131 \\ backslash
132 \" literal ", a double quote
133 \' literal ', a single quote
134 In addition to the GNU Emacs style escape sequences, a second set of
136 backslash escapes is available:
137 \a alert (bell)
138 \b backspace
139 \d delete
140 \f form feed
141 \n newline
142 \r carriage return
143 \t horizontal tab
144 \v vertical tab
145 \nnn the eight-bit character whose value is the octal value
146 nnn (one to three digits)
147 \xHH the eight-bit character whose value is the hexadecimal
148 value HH (one or two hex digits)
149 When entering the text of a macro, single or double quotes should be
151 used to indicate a macro definition. Unquoted text is assumed to be a
152 function name. In the macro body, the backslash escapes described
153 above are expanded. Backslash will quote any other character in the
154 macro text, including " and '.
155 Bash allows the current readline key bindings to be displayed or modi‐
157 fied with the bind builtin command. The editing mode may be switched
158 during interactive use by using the -o option to the set builtin com‐
159 mand. Other programs using this library provide similar mechanisms.
160 The inputrc file may be edited and re-read if a program does not pro‐
161 vide any other means to incorporate new bindings.
162 Variables
164 Readline has variables that can be used to further customize its behav‐
165 ior. A variable may be set in the inputrc file with a statement of the
166 form
167 set variable-name value
169 Except where noted, readline variables can take the values On or Off
171 (without regard to case). Unrecognized variable names are ignored.
172 When a variable value is read, empty or null values, "on" (case-insen‐
173 sitive), and "1" are equivalent to On. All other values are equivalent
174 to Off. The variables and their default values are:
175 bell-style (audible)
177 Controls what happens when readline wants to ring the terminal
178 bell. If set to none, readline never rings the bell. If set to
179 visible, readline uses a visible bell if one is available. If
180 set to audible, readline attempts to ring the terminal's bell.
181 bind-tty-special-chars (On)
182 If set to On (the default), readline attempts to bind the con‐
183 trol characters treated specially by the kernel's terminal
184 driver to their readline equivalents.
185 blink-matching-paren (Off)
186 If set to On, readline attempts to briefly move the cursor to an
187 opening parenthesis when a closing parenthesis is inserted.
188 colored-completion-prefix (Off)
189 If set to On, when listing completions, readline displays the
190 common prefix of the set of possible completions using a differ‐
191 ent color. The color definitions are taken from the value of
192 the LS_COLORS environment variable.
193 colored-stats (Off)
194 If set to On, readline displays possible completions using dif‐
195 ferent colors to indicate their file type. The color defini‐
196 tions are taken from the value of the LS_COLORS environment
197 variable.
198 comment-begin (``#'')
199 The string that is inserted in vi mode when the insert-comment
200 command is executed. This command is bound to M-# in emacs mode
201 and to # in vi command mode.
202 completion-display-width (-1)
203 The number of screen columns used to display possible matches
204 when performing completion. The value is ignored if it is less
205 than 0 or greater than the terminal screen width. A value of 0
206 will cause matches to be displayed one per line. The default
207 value is -1.
208 completion-ignore-case (Off)
209 If set to On, readline performs filename matching and completion
210 in a case-insensitive fashion.
211 completion-map-case (Off)
212 If set to On, and completion-ignore-case is enabled, readline
213 treats hyphens (-) and underscores (_) as equivalent when per‐
214 forming case-insensitive filename matching and completion.
215 completion-prefix-display-length (0)
216 The length in characters of the common prefix of a list of pos‐
217 sible completions that is displayed without modification. When
218 set to a value greater than zero, common prefixes longer than
219 this value are replaced with an ellipsis when displaying possi‐
220 ble completions.
221 completion-query-items (100)
222 This determines when the user is queried about viewing the num‐
223 ber of possible completions generated by the possible-comple‐
224 tions command. It may be set to any integer value greater than
225 or equal to zero. If the number of possible completions is
226 greater than or equal to the value of this variable, the user is
227 asked whether or not he wishes to view them; otherwise they are
228 simply listed on the terminal. A negative value causes readline
229 to never ask.
230 convert-meta (On)
231 If set to On, readline will convert characters with the eighth
232 bit set to an ASCII key sequence by stripping the eighth bit and
233 prefixing it with an escape character (in effect, using escape
234 as the meta prefix). The default is On, but readline will set
235 it to Off if the locale contains eight-bit characters.
236 disable-completion (Off)
237 If set to On, readline will inhibit word completion. Completion
238 characters will be inserted into the line as if they had been
239 mapped to self-insert.
240 echo-control-characters (On)
241 When set to On, on operating systems that indicate they support
242 it, readline echoes a character corresponding to a signal gener‐
243 ated from the keyboard.
244 editing-mode (emacs)
245 Controls whether readline begins with a set of key bindings sim‐
246 ilar to Emacs or vi. editing-mode can be set to either emacs or
247 vi.
248 emacs-mode-string (@)
249 If the show-mode-in-prompt variable is enabled, this string is
250 displayed immediately before the last line of the primary prompt
251 when emacs editing mode is active. The value is expanded like a
252 key binding, so the standard set of meta- and control prefixes
253 and backslash escape sequences is available. Use the \1 and \2
254 escapes to begin and end sequences of non-printing characters,
255 which can be used to embed a terminal control sequence into the
256 mode string.
257 enable-bracketed-paste (Off)
258 When set to On, readline will configure the terminal in a way
259 that will enable it to insert each paste into the editing buffer
260 as a single string of characters, instead of treating each char‐
261 acter as if it had been read from the keyboard. This can pre‐
262 vent pasted characters from being interpreted as editing com‐
263 mands.
264 enable-keypad (Off)
265 When set to On, readline will try to enable the application key‐
266 pad when it is called. Some systems need this to enable the
267 arrow keys.
268 enable-meta-key (On)
269 When set to On, readline will try to enable any meta modifier
270 key the terminal claims to support when it is called. On many
271 terminals, the meta key is used to send eight-bit characters.
272 expand-tilde (Off)
273 If set to On, tilde expansion is performed when readline
274 attempts word completion.
275 history-preserve-point (Off)
276 If set to On, the history code attempts to place point at the
277 same location on each history line retrieved with previous-his‐
278 tory or next-history.
279 history-size (unset)
280 Set the maximum number of history entries saved in the history
281 list. If set to zero, any existing history entries are deleted
282 and no new entries are saved. If set to a value less than zero,
283 the number of history entries is not limited. By default, the
284 number of history entries is not limited. If an attempt is made
285 to set history-size to a non-numeric value, the maximum number
286 of history entries will be set to 500.
287 horizontal-scroll-mode (Off)
288 When set to On, makes readline use a single line for display,
289 scrolling the input horizontally on a single screen line when it
290 becomes longer than the screen width rather than wrapping to a
291 new line.
292 input-meta (Off)
293 If set to On, readline will enable eight-bit input (that is, it
294 will not clear the eighth bit in the characters it reads),
295 regardless of what the terminal claims it can support. The name
296 meta-flag is a synonym for this variable. The default is Off,
297 but readline will set it to On if the locale contains eight-bit
298 characters.
299 isearch-terminators (``C-[ C-J'')
300 The string of characters that should terminate an incremental
301 search without subsequently executing the character as a com‐
302 mand. If this variable has not been given a value, the charac‐
303 ters ESC and C-J will terminate an incremental search.
304 keymap (emacs)
305 Set the current readline keymap. The set of legal keymap names
306 is emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
307 vi-command, and vi-insert. vi is equivalent to vi-command;
308 emacs is equivalent to emacs-standard. The default value is
309 emacs. The value of editing-mode also affects the default
310 keymap.
311 keyseq-timeout (500)
312 Specifies the duration readline will wait for a character when
313 reading an ambiguous key sequence (one that can form a complete
314 key sequence using the input read so far, or can take additional
315 input to complete a longer key sequence). If no input is
316 received within the timeout, readline will use the shorter but
317 complete key sequence. The value is specified in milliseconds,
318 so a value of 1000 means that readline will wait one second for
319 additional input. If this variable is set to a value less than
320 or equal to zero, or to a non-numeric value, readline will wait
321 until another key is pressed to decide which key sequence to
322 complete.
323 mark-directories (On)
324 If set to On, completed directory names have a slash appended.
325 mark-modified-lines (Off)
326 If set to On, history lines that have been modified are dis‐
327 played with a preceding asterisk (*).
328 mark-symlinked-directories (Off)
329 If set to On, completed names which are symbolic links to direc‐
330 tories have a slash appended (subject to the value of
331 mark-directories).
332 match-hidden-files (On)
333 This variable, when set to On, causes readline to match files
334 whose names begin with a `.' (hidden files) when performing
335 filename completion. If set to Off, the leading `.' must be
336 supplied by the user in the filename to be completed.
337 menu-complete-display-prefix (Off)
338 If set to On, menu completion displays the common prefix of the
339 list of possible completions (which may be empty) before cycling
340 through the list.
341 output-meta (Off)
342 If set to On, readline will display characters with the eighth
343 bit set directly rather than as a meta-prefixed escape sequence.
344 The default is Off, but readline will set it to On if the locale
345 contains eight-bit characters.
346 page-completions (On)
347 If set to On, readline uses an internal more-like pager to dis‐
348 play a screenful of possible completions at a time.
349 print-completions-horizontally (Off)
350 If set to On, readline will display completions with matches
351 sorted horizontally in alphabetical order, rather than down the
352 screen.
353 revert-all-at-newline (Off)
354 If set to On, readline will undo all changes to history lines
355 before returning when accept-line is executed. By default, his‐
356 tory lines may be modified and retain individual undo lists
357 across calls to readline.
358 show-all-if-ambiguous (Off)
359 This alters the default behavior of the completion functions.
360 If set to On, words which have more than one possible completion
361 cause the matches to be listed immediately instead of ringing
362 the bell.
363 show-all-if-unmodified (Off)
364 This alters the default behavior of the completion functions in
365 a fashion similar to show-all-if-ambiguous. If set to On, words
366 which have more than one possible completion without any possi‐
367 ble partial completion (the possible completions don't share a
368 common prefix) cause the matches to be listed immediately
369 instead of ringing the bell.
370 show-mode-in-prompt (Off)
371 If set to On, add a string to the beginning of the prompt indi‐
372 cating the editing mode: emacs, vi command, or vi insertion.
373 The mode strings are user-settable (e.g., emacs-mode-string).
374 skip-completed-text (Off)
375 If set to On, this alters the default completion behavior when
376 inserting a single match into the line. It's only active when
377 performing completion in the middle of a word. If enabled,
378 readline does not insert characters from the completion that
379 match characters after point in the word being completed, so
380 portions of the word following the cursor are not duplicated.
381 vi-cmd-mode-string ((cmd))
382 If the show-mode-in-prompt variable is enabled, this string is
383 displayed immediately before the last line of the primary prompt
384 when vi editing mode is active and in command mode. The value
385 is expanded like a key binding, so the standard set of meta- and
386 control prefixes and backslash escape sequences is available.
387 Use the \1 and \2 escapes to begin and end sequences of non-
388 printing characters, which can be used to embed a terminal con‐
389 trol sequence into the mode string.
390 vi-ins-mode-string ((ins))
391 If the show-mode-in-prompt variable is enabled, this string is
392 displayed immediately before the last line of the primary prompt
393 when vi editing mode is active and in insertion mode. The value
394 is expanded like a key binding, so the standard set of meta- and
395 control prefixes and backslash escape sequences is available.
396 Use the \1 and \2 escapes to begin and end sequences of non-
397 printing characters, which can be used to embed a terminal con‐
398 trol sequence into the mode string.
399 visible-stats (Off)
400 If set to On, a character denoting a file's type as reported by
401 stat(2) is appended to the filename when listing possible com‐
402 pletions.
403 Conditional Constructs
405 Readline implements a facility similar in spirit to the conditional
406 compilation features of the C preprocessor which allows key bindings
407 and variable settings to be performed as the result of tests. There
408 are four parser directives used.
409 $if The $if construct allows bindings to be made based on the edit‐
411 ing mode, the terminal being used, or the application using
412 readline. The text of the test, after any comparison operator,
413 extends to the end of the line; unless otherwise noted, no char‐
414 acters are required to isolate it.
415 mode The mode= form of the $if directive is used to test
417 whether readline is in emacs or vi mode. This may be
418 used in conjunction with the set keymap command, for
419 instance, to set bindings in the emacs-standard and
420 emacs-ctlx keymaps only if readline is starting out in
421 emacs mode.
422 term The term= form may be used to include terminal-specific
424 key bindings, perhaps to bind the key sequences output by
425 the terminal's function keys. The word on the right side
426 of the = is tested against the full name of the terminal
427 and the portion of the terminal name before the first -.
428 This allows sun to match both sun and sun-cmd, for
429 instance.
430 version
432 The version test may be used to perform comparisons
433 against specific readline versions. The version expands
434 to the current readline version. The set of comparison
435 operators includes =, (and ==), !=, <=, >=, <, and >.
436 The version number supplied on the right side of the
437 operator consists of a major version number, an optional
438 decimal point, and an optional minor version (e.g., 7.1).
439 If the minor version is omitted, it is assumed to be 0.
440 The operator may be separated from the string version and
441 from the version number argument by whitespace.
442 application
444 The application construct is used to include application-
445 specific settings. Each program using the readline
446 library sets the application name, and an initialization
447 file can test for a particular value. This could be used
448 to bind key sequences to functions useful for a specific
449 program. For instance, the following command adds a key
450 sequence that quotes the current or previous word in
451 bash:
452 $if Bash
454 # Quote the current or previous word
455 "\C-xq": "\eb\"\ef\""
456 $endif
457 variable
459 The variable construct provides simple equality tests for
460 readline variables and values. The permitted comparison
461 operators are =, ==, and !=. The variable name must be
462 separated from the comparison operator by whitespace; the
463 operator may be separated from the value on the right
464 hand side by whitespace. Both string and boolean vari‐
465 ables may be tested. Boolean variables must be tested
466 against the values on and off.
467 $endif This command, as seen in the previous example, terminates an $if
469 command.
470 $else Commands in this branch of the $if directive are executed if the
472 test fails.
473 $include
475 This directive takes a single filename as an argument and reads
476 commands and bindings from that file. For example, the follow‐
477 ing directive would read /etc/inputrc:
478 $include /etc/inputrc
480
482 Readline provides commands for searching through the command history
483 for lines containing a specified string. There are two search modes:
484 incremental and non-incremental.
485 Incremental searches begin before the user has finished typing the
487 search string. As each character of the search string is typed, read‐
488 line displays the next entry from the history matching the string typed
489 so far. An incremental search requires only as many characters as
490 needed to find the desired history entry. To search backward in the
491 history for a particular string, type C-r. Typing C-s searches forward
492 through the history. The characters present in the value of the
493 isearch-terminators variable are used to terminate an incremental
494 search. If that variable has not been assigned a value the Escape and
495 C-J characters will terminate an incremental search. C-G will abort an
496 incremental search and restore the original line. When the search is
497 terminated, the history entry containing the search string becomes the
498 current line.
499 To find other matching entries in the history list, type C-s or C-r as
501 appropriate. This will search backward or forward in the history for
502 the next line matching the search string typed so far. Any other key
503 sequence bound to a readline command will terminate the search and exe‐
504 cute that command. For instance, a newline will terminate the search
505 and accept the line, thereby executing the command from the history
506 list. A movement command will terminate the search, make the last line
507 found the current line, and begin editing.
508 Non-incremental searches read the entire search string before starting
510 to search for matching history lines. The search string may be typed
511 by the user or be part of the contents of the current line.
512
514 The following is a list of the names of the commands and the default
515 key sequences to which they are bound. Command names without an accom‐
516 panying key sequence are unbound by default.
517 In the following descriptions, point refers to the current cursor posi‐
519 tion, and mark refers to a cursor position saved by the set-mark com‐
520 mand. The text between the point and mark is referred to as the
521 region.
522 Commands for Moving
524 beginning-of-line (C-a)
525 Move to the start of the current line.
526 end-of-line (C-e)
527 Move to the end of the line.
528 forward-char (C-f)
529 Move forward a character.
530 backward-char (C-b)
531 Move back a character.
532 forward-word (M-f)
533 Move forward to the end of the next word. Words are composed of
534 alphanumeric characters (letters and digits).
535 backward-word (M-b)
536 Move back to the start of the current or previous word. Words
537 are composed of alphanumeric characters (letters and digits).
538 previous-screen-line
539 Attempt to move point to the same physical screen column on the
540 previous physical screen line. This will not have the desired
541 effect if the current Readline line does not take up more than
542 one physical line or if point is not greater than the length of
543 the prompt plus the screen width.
544 next-screen-line
545 Attempt to move point to the same physical screen column on the
546 next physical screen line. This will not have the desired effect
547 if the current Readline line does not take up more than one
548 physical line or if the length of the current Readline line is
549 not greater than the length of the prompt plus the screen width.
550 clear-screen (C-l)
551 Clear the screen leaving the current line at the top of the
552 screen. With an argument, refresh the current line without
553 clearing the screen.
554 redraw-current-line
555 Refresh the current line.
556 Commands for Manipulating the History
558 accept-line (Newline, Return)
559 Accept the line regardless of where the cursor is. If this line
560 is non-empty, it may be added to the history list for future
561 recall with add_history(). If the line is a modified history
562 line, the history line is restored to its original state.
563 previous-history (C-p)
564 Fetch the previous command from the history list, moving back in
565 the list.
566 next-history (C-n)
567 Fetch the next command from the history list, moving forward in
568 the list.
569 beginning-of-history (M-<)
570 Move to the first line in the history.
571 end-of-history (M->)
572 Move to the end of the input history, i.e., the line currently
573 being entered.
574 reverse-search-history (C-r)
575 Search backward starting at the current line and moving `up'
576 through the history as necessary. This is an incremental
577 search.
578 forward-search-history (C-s)
579 Search forward starting at the current line and moving `down'
580 through the history as necessary. This is an incremental
581 search.
582 non-incremental-reverse-search-history (M-p)
583 Search backward through the history starting at the current line
584 using a non-incremental search for a string supplied by the
585 user.
586 non-incremental-forward-search-history (M-n)
587 Search forward through the history using a non-incremental
588 search for a string supplied by the user.
589 history-search-backward
590 Search backward through the history for the string of characters
591 between the start of the current line and the current cursor
592 position (the point). The search string must match at the
593 beginning of a history line. This is a non-incremental search.
594 history-search-forward
595 Search forward through the history for the string of characters
596 between the start of the current line and the point. The search
597 string must match at the beginning of a history line. This is a
598 non-incremental search.
599 history-substring-search-backward
600 Search backward through the history for the string of characters
601 between the start of the current line and the current cursor
602 position (the point). The search string may match anywhere in a
603 history line. This is a non-incremental search.
604 history-substring-search-forward
605 Search forward through the history for the string of characters
606 between the start of the current line and the point. The search
607 string may match anywhere in a history line. This is a non-
608 incremental search.
609 yank-nth-arg (M-C-y)
610 Insert the first argument to the previous command (usually the
611 second word on the previous line) at point. With an argument n,
612 insert the nth word from the previous command (the words in the
613 previous command begin with word 0). A negative argument
614 inserts the nth word from the end of the previous command. Once
615 the argument n is computed, the argument is extracted as if the
616 "!n" history expansion had been specified.
617 yank-last-arg (M-., M-_)
618 Insert the last argument to the previous command (the last word
619 of the previous history entry). With a numeric argument, behave
620 exactly like yank-nth-arg. Successive calls to yank-last-arg
621 move back through the history list, inserting the last word (or
622 the word specified by the argument to the first call) of each
623 line in turn. Any numeric argument supplied to these successive
624 calls determines the direction to move through the history. A
625 negative argument switches the direction through the history
626 (back or forward). The history expansion facilities are used to
627 extract the last argument, as if the "!$" history expansion had
628 been specified.
629 Commands for Changing Text
631 end-of-file (usually C-d)
632 The character indicating end-of-file as set, for example, by
633 ``stty''. If this character is read when there are no charac‐
634 ters on the line, and point is at the beginning of the line,
635 Readline interprets it as the end of input and returns EOF.
636 delete-char (C-d)
637 Delete the character at point. If this function is bound to the
638 same character as the tty EOF character, as C-d commonly is, see
639 above for the effects.
640 backward-delete-char (Rubout)
641 Delete the character behind the cursor. When given a numeric
642 argument, save the deleted text on the kill ring.
643 forward-backward-delete-char
644 Delete the character under the cursor, unless the cursor is at
645 the end of the line, in which case the character behind the cur‐
646 sor is deleted.
647 quoted-insert (C-q, C-v)
648 Add the next character that you type to the line verbatim. This
649 is how to insert characters like C-q, for example.
650 tab-insert (M-TAB)
651 Insert a tab character.
652 self-insert (a, b, A, 1, !, ...)
653 Insert the character typed.
654 transpose-chars (C-t)
655 Drag the character before point forward over the character at
656 point, moving point forward as well. If point is at the end of
657 the line, then this transposes the two characters before point.
658 Negative arguments have no effect.
659 transpose-words (M-t)
660 Drag the word before point past the word after point, moving
661 point over that word as well. If point is at the end of the
662 line, this transposes the last two words on the line.
663 upcase-word (M-u)
664 Uppercase the current (or following) word. With a negative
665 argument, uppercase the previous word, but do not move point.
666 downcase-word (M-l)
667 Lowercase the current (or following) word. With a negative
668 argument, lowercase the previous word, but do not move point.
669 capitalize-word (M-c)
670 Capitalize the current (or following) word. With a negative
671 argument, capitalize the previous word, but do not move point.
672 overwrite-mode
673 Toggle overwrite mode. With an explicit positive numeric argu‐
674 ment, switches to overwrite mode. With an explicit non-positive
675 numeric argument, switches to insert mode. This command affects
676 only emacs mode; vi mode does overwrite differently. Each call
677 to readline() starts in insert mode. In overwrite mode, charac‐
678 ters bound to self-insert replace the text at point rather than
679 pushing the text to the right. Characters bound to back‐
680 ward-delete-char replace the character before point with a
681 space. By default, this command is unbound.
682 Killing and Yanking
684 kill-line (C-k)
685 Kill the text from point to the end of the line.
686 backward-kill-line (C-x Rubout)
687 Kill backward to the beginning of the line.
688 unix-line-discard (C-u)
689 Kill backward from point to the beginning of the line. The
690 killed text is saved on the kill-ring.
691 kill-whole-line
692 Kill all characters on the current line, no matter where point
693 is.
694 kill-word (M-d)
695 Kill from point the end of the current word, or if between
696 words, to the end of the next word. Word boundaries are the
697 same as those used by forward-word.
698 backward-kill-word (M-Rubout)
699 Kill the word behind point. Word boundaries are the same as
700 those used by backward-word.
701 unix-word-rubout (C-w)
702 Kill the word behind point, using white space as a word bound‐
703 ary. The killed text is saved on the kill-ring.
704 unix-filename-rubout
705 Kill the word behind point, using white space and the slash
706 character as the word boundaries. The killed text is saved on
707 the kill-ring.
708 delete-horizontal-space (M-\)
709 Delete all spaces and tabs around point.
710 kill-region
711 Kill the text between the point and mark (saved cursor posi‐
712 tion). This text is referred to as the region.
713 copy-region-as-kill
714 Copy the text in the region to the kill buffer.
715 copy-backward-word
716 Copy the word before point to the kill buffer. The word bound‐
717 aries are the same as backward-word.
718 copy-forward-word
719 Copy the word following point to the kill buffer. The word
720 boundaries are the same as forward-word.
721 yank (C-y)
722 Yank the top of the kill ring into the buffer at point.
723 yank-pop (M-y)
724 Rotate the kill ring, and yank the new top. Only works follow‐
725 ing yank or yank-pop.
726 Numeric Arguments
728 digit-argument (M-0, M-1, ..., M--)
729 Add this digit to the argument already accumulating, or start a
730 new argument. M-- starts a negative argument.
731 universal-argument
732 This is another way to specify an argument. If this command is
733 followed by one or more digits, optionally with a leading minus
734 sign, those digits define the argument. If the command is fol‐
735 lowed by digits, executing universal-argument again ends the
736 numeric argument, but is otherwise ignored. As a special case,
737 if this command is immediately followed by a character that is
738 neither a digit or minus sign, the argument count for the next
739 command is multiplied by four. The argument count is initially
740 one, so executing this function the first time makes the argu‐
741 ment count four, a second time makes the argument count sixteen,
742 and so on.
743 Completing
745 complete (TAB)
746 Attempt to perform completion on the text before point. The
747 actual completion performed is application-specific. Bash, for
748 instance, attempts completion treating the text as a variable
749 (if the text begins with $), username (if the text begins with
750 ~), hostname (if the text begins with @), or command (including
751 aliases and functions) in turn. If none of these produces a
752 match, filename completion is attempted. Gdb, on the other
753 hand, allows completion of program functions and variables, and
754 only attempts filename completion under certain circumstances.
755 possible-completions (M-?)
756 List the possible completions of the text before point. When
757 displaying completions, readline sets the number of columns used
758 for display to the value of completion-display-width, the value
759 of the environment variable COLUMNS, or the screen width, in
760 that order.
761 insert-completions (M-*)
762 Insert all completions of the text before point that would have
763 been generated by possible-completions.
764 menu-complete
765 Similar to complete, but replaces the word to be completed with
766 a single match from the list of possible completions. Repeated
767 execution of menu-complete steps through the list of possible
768 completions, inserting each match in turn. At the end of the
769 list of completions, the bell is rung (subject to the setting of
770 bell-style) and the original text is restored. An argument of n
771 moves n positions forward in the list of matches; a negative
772 argument may be used to move backward through the list. This
773 command is intended to be bound to TAB, but is unbound by
774 default.
775 menu-complete-backward
776 Identical to menu-complete, but moves backward through the list
777 of possible completions, as if menu-complete had been given a
778 negative argument. This command is unbound by default.
779 delete-char-or-list
780 Deletes the character under the cursor if not at the beginning
781 or end of the line (like delete-char). If at the end of the
782 line, behaves identically to possible-completions.
783 Keyboard Macros
785 start-kbd-macro (C-x ()
786 Begin saving the characters typed into the current keyboard
787 macro.
788 end-kbd-macro (C-x ))
789 Stop saving the characters typed into the current keyboard macro
790 and store the definition.
791 call-last-kbd-macro (C-x e)
792 Re-execute the last keyboard macro defined, by making the char‐
793 acters in the macro appear as if typed at the keyboard.
794 print-last-kbd-macro ()
795 Print the last keyboard macro defined in a format suitable for
796 the inputrc file.
797 Miscellaneous
799 re-read-init-file (C-x C-r)
800 Read in the contents of the inputrc file, and incorporate any
801 bindings or variable assignments found there.
802 abort (C-g)
803 Abort the current editing command and ring the terminal's bell
804 (subject to the setting of bell-style).
805 do-lowercase-version (M-A, M-B, M-x, ...)
806 If the metafied character x is uppercase, run the command that
807 is bound to the corresponding metafied lowercase character. The
808 behavior is undefined if x is already lowercase.
809 prefix-meta (ESC)
810 Metafy the next character typed. ESC f is equivalent to Meta-f.
811 undo (C-_, C-x C-u)
812 Incremental undo, separately remembered for each line.
813 revert-line (M-r)
814 Undo all changes made to this line. This is like executing the
815 undo command enough times to return the line to its initial
816 state.
817 tilde-expand (M-&)
818 Perform tilde expansion on the current word.
819 set-mark (C-@, M-<space>)
820 Set the mark to the point. If a numeric argument is supplied,
821 the mark is set to that position.
822 exchange-point-and-mark (C-x C-x)
823 Swap the point with the mark. The current cursor position is
824 set to the saved position, and the old cursor position is saved
825 as the mark.
826 character-search (C-])
827 A character is read and point is moved to the next occurrence of
828 that character. A negative count searches for previous occur‐
829 rences.
830 character-search-backward (M-C-])
831 A character is read and point is moved to the previous occur‐
832 rence of that character. A negative count searches for subse‐
833 quent occurrences.
834 skip-csi-sequence
835 Read enough characters to consume a multi-key sequence such as
836 those defined for keys like Home and End. Such sequences begin
837 with a Control Sequence Indicator (CSI), usually ESC-[. If this
838 sequence is bound to "\[", keys producing such sequences will
839 have no effect unless explicitly bound to a readline command,
840 instead of inserting stray characters into the editing buffer.
841 This is unbound by default, but usually bound to ESC-[.
842 insert-comment (M-#)
843 Without a numeric argument, the value of the readline com‐
844 ment-begin variable is inserted at the beginning of the current
845 line. If a numeric argument is supplied, this command acts as a
846 toggle: if the characters at the beginning of the line do not
847 match the value of comment-begin, the value is inserted, other‐
848 wise the characters in comment-begin are deleted from the begin‐
849 ning of the line. In either case, the line is accepted as if a
850 newline had been typed. The default value of comment-begin
851 makes the current line a shell comment. If a numeric argument
852 causes the comment character to be removed, the line will be
853 executed by the shell.
854 dump-functions
855 Print all of the functions and their key bindings to the read‐
856 line output stream. If a numeric argument is supplied, the out‐
857 put is formatted in such a way that it can be made part of an
858 inputrc file.
859 dump-variables
860 Print all of the settable variables and their values to the
861 readline output stream. If a numeric argument is supplied, the
862 output is formatted in such a way that it can be made part of an
863 inputrc file.
864 dump-macros
865 Print all of the readline key sequences bound to macros and the
866 strings they output. If a numeric argument is supplied, the
867 output is formatted in such a way that it can be made part of an
868 inputrc file.
869 emacs-editing-mode (C-e)
870 When in vi command mode, this causes a switch to emacs editing
871 mode.
872 vi-editing-mode (M-C-j)
873 When in emacs editing mode, this causes a switch to vi editing
874 mode.
875
877 The following is a list of the default emacs and vi bindings. Charac‐
878 ters with the eighth bit set are written as M-<character>, and are
879 referred to as metafied characters. The printable ASCII characters not
880 mentioned in the list of emacs standard bindings are bound to the
881 self-insert function, which just inserts the given character into the
882 input line. In vi insertion mode, all characters not specifically men‐
883 tioned are bound to self-insert. Characters assigned to signal genera‐
884 tion by stty(1) or the terminal driver, such as C-Z or C-C, retain that
885 function. Upper and lower case metafied characters are bound to the
886 same function in the emacs mode meta keymap. The remaining characters
887 are unbound, which causes readline to ring the bell (subject to the
888 setting of the bell-style variable).
889 Emacs Mode
891 Emacs Standard bindings
892 "C-@" set-mark
894 "C-A" beginning-of-line
895 "C-B" backward-char
896 "C-D" delete-char
897 "C-E" end-of-line
898 "C-F" forward-char
899 "C-G" abort
900 "C-H" backward-delete-char
901 "C-I" complete
902 "C-J" accept-line
903 "C-K" kill-line
904 "C-L" clear-screen
905 "C-M" accept-line
906 "C-N" next-history
907 "C-P" previous-history
908 "C-Q" quoted-insert
909 "C-R" reverse-search-history
910 "C-S" forward-search-history
911 "C-T" transpose-chars
912 "C-U" unix-line-discard
913 "C-V" quoted-insert
914 "C-W" unix-word-rubout
915 "C-Y" yank
916 "C-]" character-search
917 "C-_" undo
918 " " to "/" self-insert
919 "0" to "9" self-insert
920 ":" to "~" self-insert
921 "C-?" backward-delete-char
922 Emacs Meta bindings
924 "M-C-G" abort
926 "M-C-H" backward-kill-word
927 "M-C-I" tab-insert
928 "M-C-J" vi-editing-mode
929 "M-C-M" vi-editing-mode
930 "M-C-R" revert-line
931 "M-C-Y" yank-nth-arg
932 "M-C-[" complete
933 "M-C-]" character-search-backward
934 "M-space" set-mark
935 "M-#" insert-comment
936 "M-&" tilde-expand
937 "M-*" insert-completions
938 "M--" digit-argument
939 "M-." yank-last-arg
940 "M-0" digit-argument
941 "M-1" digit-argument
942 "M-2" digit-argument
943 "M-3" digit-argument
944 "M-4" digit-argument
945 "M-5" digit-argument
946 "M-6" digit-argument
947 "M-7" digit-argument
948 "M-8" digit-argument
949 "M-9" digit-argument
950 "M-<" beginning-of-history
951 "M-=" possible-completions
952 "M->" end-of-history
953 "M-?" possible-completions
954 "M-B" backward-word
955 "M-C" capitalize-word
956 "M-D" kill-word
957 "M-F" forward-word
958 "M-L" downcase-word
959 "M-N" non-incremental-forward-search-history
960 "M-P" non-incremental-reverse-search-history
961 "M-R" revert-line
962 "M-T" transpose-words
963 "M-U" upcase-word
964 "M-Y" yank-pop
965 "M-\" delete-horizontal-space
966 "M-~" tilde-expand
967 "M-C-?" backward-kill-word
968 "M-_" yank-last-arg
969 Emacs Control-X bindings
971 "C-XC-G" abort
973 "C-XC-R" re-read-init-file
974 "C-XC-U" undo
975 "C-XC-X" exchange-point-and-mark
976 "C-X(" start-kbd-macro
977 "C-X)" end-kbd-macro
978 "C-XE" call-last-kbd-macro
979 "C-XC-?" backward-kill-line
980 VI Mode bindings
983 VI Insert Mode functions
984 "C-D" vi-eof-maybe
986 "C-H" backward-delete-char
987 "C-I" complete
988 "C-J" accept-line
989 "C-M" accept-line
990 "C-R" reverse-search-history
991 "C-S" forward-search-history
992 "C-T" transpose-chars
993 "C-U" unix-line-discard
994 "C-V" quoted-insert
995 "C-W" unix-word-rubout
996 "C-Y" yank
997 "C-[" vi-movement-mode
998 "C-_" undo
999 " " to "~" self-insert
1000 "C-?" backward-delete-char
1001 VI Command Mode functions
1003 "C-D" vi-eof-maybe
1005 "C-E" emacs-editing-mode
1006 "C-G" abort
1007 "C-H" backward-char
1008 "C-J" accept-line
1009 "C-K" kill-line
1010 "C-L" clear-screen
1011 "C-M" accept-line
1012 "C-N" next-history
1013 "C-P" previous-history
1014 "C-Q" quoted-insert
1015 "C-R" reverse-search-history
1016 "C-S" forward-search-history
1017 "C-T" transpose-chars
1018 "C-U" unix-line-discard
1019 "C-V" quoted-insert
1020 "C-W" unix-word-rubout
1021 "C-Y" yank
1022 "C-_" vi-undo
1023 " " forward-char
1024 "#" insert-comment
1025 "$" end-of-line
1026 "%" vi-match
1027 "&" vi-tilde-expand
1028 "*" vi-complete
1029 "+" next-history
1030 "," vi-char-search
1031 "-" previous-history
1032 "." vi-redo
1033 "/" vi-search
1034 "0" beginning-of-line
1035 "1" to "9" vi-arg-digit
1036 ";" vi-char-search
1037 "=" vi-complete
1038 "?" vi-search
1039 "A" vi-append-eol
1040 "B" vi-prev-word
1041 "C" vi-change-to
1042 "D" vi-delete-to
1043 "E" vi-end-word
1044 "F" vi-char-search
1045 "G" vi-fetch-history
1046 "I" vi-insert-beg
1047 "N" vi-search-again
1048 "P" vi-put
1049 "R" vi-replace
1050 "S" vi-subst
1051 "T" vi-char-search
1052 "U" revert-line
1053 "W" vi-next-word
1054 "X" backward-delete-char
1055 "Y" vi-yank-to
1056 "\" vi-complete
1057 "^" vi-first-print
1058 "_" vi-yank-arg
1059 "`" vi-goto-mark
1060 "a" vi-append-mode
1061 "b" vi-prev-word
1062 "c" vi-change-to
1063 "d" vi-delete-to
1064 "e" vi-end-word
1065 "f" vi-char-search
1066 "h" backward-char
1067 "i" vi-insertion-mode
1068 "j" next-history
1069 "k" prev-history
1070 "l" forward-char
1071 "m" vi-set-mark
1072 "n" vi-search-again
1073 "p" vi-put
1074 "r" vi-change-char
1075 "s" vi-subst
1076 "t" vi-char-search
1077 "u" vi-undo
1078 "w" vi-next-word
1079 "x" vi-delete
1080 "y" vi-yank-to
1081 "|" vi-column
1082 "~" vi-change-case
1083
1085 The Gnu Readline Library, Brian Fox and Chet Ramey
1086 The Gnu History Library, Brian Fox and Chet Ramey
1087 bash(1)
1088
1090 ~/.inputrc
1091 Individual readline initialization file
1092
1094 Brian Fox, Free Software Foundation
1095 bfox@gnu.org
1096 Chet Ramey, Case Western Reserve University
1098 chet.ramey@case.edu
1099
1101 If you find a bug in readline, you should report it. But first, you
1102 should make sure that it really is a bug, and that it appears in the
1103 latest version of the readline library that you have.
1104 Once you have determined that a bug actually exists, mail a bug report
1106 to bug-readline@gnu.org. If you have a fix, you are welcome to mail
1107 that as well! Suggestions and `philosophical' bug reports may be
1108 mailed to bug-readline@gnu.org or posted to the Usenet newsgroup
1109 gnu.bash.bug.
1110 Comments and bug reports concerning this manual page should be directed
1112 to chet.ramey@case.edu.
1113
1115 It's too big and too slow.
1116GNU Readline 7.0 2017 December 28 READLINE(3)