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 enable-bracketed-paste (Off)
249 When set to On, readline will configure the terminal in a way
250 that will enable it to insert each paste into the editing buffer
251 as a single string of characters, instead of treating each char‐
252 acter as if it had been read from the keyboard. This can pre‐
253 vent pasted characters from being interpreted as editing com‐
254 mands.
255 enable-keypad (Off)
256 When set to On, readline will try to enable the application key‐
257 pad when it is called. Some systems need this to enable the
258 arrow keys.
259 enable-meta-key (On)
260 When set to On, readline will try to enable any meta modifier
261 key the terminal claims to support when it is called. On many
262 terminals, the meta key is used to send eight-bit characters.
263 expand-tilde (Off)
264 If set to On, tilde expansion is performed when readline
265 attempts word completion.
266 history-preserve-point (Off)
267 If set to On, the history code attempts to place point at the
268 same location on each history line retrieved with previous-his‐
269 tory or next-history.
270 history-size (unset)
271 Set the maximum number of history entries saved in the history
272 list. If set to zero, any existing history entries are deleted
273 and no new entries are saved. If set to a value less than zero,
274 the number of history entries is not limited. By default, the
275 number of history entries is not limited. If an attempt is made
276 to set history-size to a non-numeric value, the maximum number
277 of history entries will be set to 500.
278 horizontal-scroll-mode (Off)
279 When set to On, makes readline use a single line for display,
280 scrolling the input horizontally on a single screen line when it
281 becomes longer than the screen width rather than wrapping to a
282 new line.
283 input-meta (Off)
284 If set to On, readline will enable eight-bit input (that is, it
285 will not clear the eighth bit in the characters it reads),
286 regardless of what the terminal claims it can support. The name
287 meta-flag is a synonym for this variable. The default is Off,
288 but readline will set it to On if the locale contains eight-bit
289 characters.
290 isearch-terminators (``C-[ C-J'')
291 The string of characters that should terminate an incremental
292 search without subsequently executing the character as a com‐
293 mand. If this variable has not been given a value, the charac‐
294 ters ESC and C-J will terminate an incremental search.
295 keymap (emacs)
296 Set the current readline keymap. The set of legal keymap names
297 is emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
298 vi-command, and vi-insert. vi is equivalent to vi-command;
299 emacs is equivalent to emacs-standard. The default value is
300 emacs. The value of editing-mode also affects the default
301 keymap.
302 emacs-mode-string (@)
303 This string is displayed immediately before the last line of the
304 primary prompt when emacs editing mode is active. The value is
305 expanded like a key binding, so the standard set of meta- and
306 control prefixes and backslash escape sequences is available.
307 Use the \1 and \2 escapes to begin and end sequences of non-
308 printing characters, which can be used to embed a terminal con‐
309 trol sequence into the mode string.
310 keyseq-timeout (500)
311 Specifies the duration readline will wait for a character when
312 reading an ambiguous key sequence (one that can form a complete
313 key sequence using the input read so far, or can take additional
314 input to complete a longer key sequence). If no input is
315 received within the timeout, readline will use the shorter but
316 complete key sequence. The value is specified in milliseconds,
317 so a value of 1000 means that readline will wait one second for
318 additional input. If this variable is set to a value less than
319 or equal to zero, or to a non-numeric value, readline will wait
320 until another key is pressed to decide which key sequence to
321 complete.
322 mark-directories (On)
323 If set to On, completed directory names have a slash appended.
324 mark-modified-lines (Off)
325 If set to On, history lines that have been modified are dis‐
326 played with a preceding asterisk (*).
327 mark-symlinked-directories (Off)
328 If set to On, completed names which are symbolic links to direc‐
329 tories have a slash appended (subject to the value of
330 mark-directories).
331 match-hidden-files (On)
332 This variable, when set to On, causes readline to match files
333 whose names begin with a `.' (hidden files) when performing
334 filename completion. If set to Off, the leading `.' must be
335 supplied by the user in the filename to be completed.
336 menu-complete-display-prefix (Off)
337 If set to On, menu completion displays the common prefix of the
338 list of possible completions (which may be empty) before cycling
339 through the list.
340 output-meta (Off)
341 If set to On, readline will display characters with the eighth
342 bit set directly rather than as a meta-prefixed escape sequence.
343 The default is Off, but readline will set it to On if the locale
344 contains eight-bit characters.
345 page-completions (On)
346 If set to On, readline uses an internal more-like pager to dis‐
347 play a screenful of possible completions at a time.
348 print-completions-horizontally (Off)
349 If set to On, readline will display completions with matches
350 sorted horizontally in alphabetical order, rather than down the
351 screen.
352 revert-all-at-newline (Off)
353 If set to On, readline will undo all changes to history lines
354 before returning when accept-line is executed. By default, his‐
355 tory lines may be modified and retain individual undo lists
356 across calls to readline.
357 show-all-if-ambiguous (Off)
358 This alters the default behavior of the completion functions.
359 If set to On, words which have more than one possible completion
360 cause the matches to be listed immediately instead of ringing
361 the bell.
362 show-all-if-unmodified (Off)
363 This alters the default behavior of the completion functions in
364 a fashion similar to show-all-if-ambiguous. If set to On, words
365 which have more than one possible completion without any possi‐
366 ble partial completion (the possible completions don't share a
367 common prefix) cause the matches to be listed immediately
368 instead of ringing the bell.
369 show-mode-in-prompt (Off)
370 If set to On, add a character to the beginning of the prompt
371 indicating the editing mode: emacs, vi command, or vi insertion.
372 The mode strings are user-settable.
373 skip-completed-text (Off)
374 If set to On, this alters the default completion behavior when
375 inserting a single match into the line. It's only active when
376 performing completion in the middle of a word. If enabled,
377 readline does not insert characters from the completion that
378 match characters after point in the word being completed, so
379 portions of the word following the cursor are not duplicated.
380 vi-cmd-mode-string ((cmd))
381 This string is displayed immediately before the last line of the
382 primary prompt when vi editing mode is active and in command
383 mode. The value is expanded like a key binding, so the standard
384 set of meta- and control prefixes and backslash escape sequences
385 is available. Use the \1 and \2 escapes to begin and end
386 sequences of non-printing characters, which can be used to embed
387 a terminal control sequence into the mode string.
388 vi-ins-mode-string ((ins))
389 This string is displayed immediately before the last line of the
390 primary prompt when vi editing mode is active and in insertion
391 mode. The value is expanded like a key binding, so the standard
392 set of meta- and control prefixes and backslash escape sequences
393 is available. Use the \1 and \2 escapes to begin and end
394 sequences of non-printing characters, which can be used to embed
395 a terminal control sequence into the mode string.
396 visible-stats (Off)
397 If set to On, a character denoting a file's type as reported by
398 stat(2) is appended to the filename when listing possible com‐
399 pletions.
400 Conditional Constructs
402 Readline implements a facility similar in spirit to the conditional
403 compilation features of the C preprocessor which allows key bindings
404 and variable settings to be performed as the result of tests. There
405 are four parser directives used.
406 $if The $if construct allows bindings to be made based on the edit‐
408 ing mode, the terminal being used, or the application using
409 readline. The text of the test extends to the end of the line;
410 no characters are required to isolate it.
411 mode The mode= form of the $if directive is used to test
413 whether readline is in emacs or vi mode. This may be
414 used in conjunction with the set keymap command, for
415 instance, to set bindings in the emacs-standard and
416 emacs-ctlx keymaps only if readline is starting out in
417 emacs mode.
418 term The term= form may be used to include terminal-specific
420 key bindings, perhaps to bind the key sequences output by
421 the terminal's function keys. The word on the right side
422 of the = is tested against the full name of the terminal
423 and the portion of the terminal name before the first -.
424 This allows sun to match both sun and sun-cmd, for
425 instance.
426 application
428 The application construct is used to include application-
429 specific settings. Each program using the readline
430 library sets the application name, and an initialization
431 file can test for a particular value. This could be used
432 to bind key sequences to functions useful for a specific
433 program. For instance, the following command adds a key
434 sequence that quotes the current or previous word in
435 bash:
436 $if Bash
438 # Quote the current or previous word
439 "\C-xq": "\eb\"\ef\""
440 $endif
441 $endif This command, as seen in the previous example, terminates an $if
443 command.
444 $else Commands in this branch of the $if directive are executed if the
446 test fails.
447 $include
449 This directive takes a single filename as an argument and reads
450 commands and bindings from that file. For example, the follow‐
451 ing directive would read /etc/inputrc:
452 $include /etc/inputrc
454
456 Readline provides commands for searching through the command history
457 for lines containing a specified string. There are two search modes:
458 incremental and non-incremental.
459 Incremental searches begin before the user has finished typing the
461 search string. As each character of the search string is typed, read‐
462 line displays the next entry from the history matching the string typed
463 so far. An incremental search requires only as many characters as
464 needed to find the desired history entry. To search backward in the
465 history for a particular string, type C-r. Typing C-s searches forward
466 through the history. The characters present in the value of the
467 isearch-terminators variable are used to terminate an incremental
468 search. If that variable has not been assigned a value the Escape and
469 C-J characters will terminate an incremental search. C-G will abort an
470 incremental search and restore the original line. When the search is
471 terminated, the history entry containing the search string becomes the
472 current line.
473 To find other matching entries in the history list, type C-s or C-r as
475 appropriate. This will search backward or forward in the history for
476 the next line matching the search string typed so far. Any other key
477 sequence bound to a readline command will terminate the search and exe‐
478 cute that command. For instance, a newline will terminate the search
479 and accept the line, thereby executing the command from the history
480 list. A movement command will terminate the search, make the last line
481 found the current line, and begin editing.
482 Non-incremental searches read the entire search string before starting
484 to search for matching history lines. The search string may be typed
485 by the user or be part of the contents of the current line.
486
488 The following is a list of the names of the commands and the default
489 key sequences to which they are bound. Command names without an accom‐
490 panying key sequence are unbound by default.
491 In the following descriptions, point refers to the current cursor posi‐
493 tion, and mark refers to a cursor position saved by the set-mark com‐
494 mand. The text between the point and mark is referred to as the
495 region.
496 Commands for Moving
498 beginning-of-line (C-a)
499 Move to the start of the current line.
500 end-of-line (C-e)
501 Move to the end of the line.
502 forward-char (C-f)
503 Move forward a character.
504 backward-char (C-b)
505 Move back a character.
506 forward-word (M-f)
507 Move forward to the end of the next word. Words are composed of
508 alphanumeric characters (letters and digits).
509 backward-word (M-b)
510 Move back to the start of the current or previous word. Words
511 are composed of alphanumeric characters (letters and digits).
512 clear-screen (C-l)
513 Clear the screen leaving the current line at the top of the
514 screen. With an argument, refresh the current line without
515 clearing the screen.
516 redraw-current-line
517 Refresh the current line.
518 Commands for Manipulating the History
520 accept-line (Newline, Return)
521 Accept the line regardless of where the cursor is. If this line
522 is non-empty, it may be added to the history list for future
523 recall with add_history(). If the line is a modified history
524 line, the history line is restored to its original state.
525 previous-history (C-p)
526 Fetch the previous command from the history list, moving back in
527 the list.
528 next-history (C-n)
529 Fetch the next command from the history list, moving forward in
530 the list.
531 beginning-of-history (M-<)
532 Move to the first line in the history.
533 end-of-history (M->)
534 Move to the end of the input history, i.e., the line currently
535 being entered.
536 reverse-search-history (C-r)
537 Search backward starting at the current line and moving `up'
538 through the history as necessary. This is an incremental
539 search.
540 forward-search-history (C-s)
541 Search forward starting at the current line and moving `down'
542 through the history as necessary. This is an incremental
543 search.
544 non-incremental-reverse-search-history (M-p)
545 Search backward through the history starting at the current line
546 using a non-incremental search for a string supplied by the
547 user.
548 non-incremental-forward-search-history (M-n)
549 Search forward through the history using a non-incremental
550 search for a string supplied by the user.
551 history-search-backward
552 Search backward through the history for the string of characters
553 between the start of the current line and the current cursor
554 position (the point). The search string must match at the
555 beginning of a history line. This is a non-incremental search.
556 history-search-forward
557 Search forward through the history for the string of characters
558 between the start of the current line and the point. The search
559 string must match at the beginning of a history line. This is a
560 non-incremental search.
561 history-substring-search-backward
562 Search backward through the history for the string of characters
563 between the start of the current line and the current cursor
564 position (the point). The search string may match anywhere in a
565 history line. This is a non-incremental search.
566 history-substring-search-forward
567 Search forward through the history for the string of characters
568 between the start of the current line and the point. The search
569 string may match anywhere in a history line. This is a non-
570 incremental search.
571 yank-nth-arg (M-C-y)
572 Insert the first argument to the previous command (usually the
573 second word on the previous line) at point. With an argument n,
574 insert the nth word from the previous command (the words in the
575 previous command begin with word 0). A negative argument
576 inserts the nth word from the end of the previous command. Once
577 the argument n is computed, the argument is extracted as if the
578 "!n" history expansion had been specified.
579 yank-last-arg (M-., M-_)
580 Insert the last argument to the previous command (the last word
581 of the previous history entry). With a numeric argument, behave
582 exactly like yank-nth-arg. Successive calls to yank-last-arg
583 move back through the history list, inserting the last word (or
584 the word specified by the argument to the first call) of each
585 line in turn. Any numeric argument supplied to these successive
586 calls determines the direction to move through the history. A
587 negative argument switches the direction through the history
588 (back or forward). The history expansion facilities are used to
589 extract the last argument, as if the "!$" history expansion had
590 been specified.
591 Commands for Changing Text
593 end-of-file (usually C-d)
594 The character indicating end-of-file as set, for example, by
595 ``stty''. If this character is read when there are no charac‐
596 ters on the line, and point is at the beginning of the line,
597 Readline interprets it as the end of input and returns EOF.
598 delete-char (C-d)
599 Delete the character at point. If this function is bound to the
600 same character as the tty EOF character, as C-d commonly is, see
601 above for the effects.
602 backward-delete-char (Rubout)
603 Delete the character behind the cursor. When given a numeric
604 argument, save the deleted text on the kill ring.
605 forward-backward-delete-char
606 Delete the character under the cursor, unless the cursor is at
607 the end of the line, in which case the character behind the cur‐
608 sor is deleted.
609 quoted-insert (C-q, C-v)
610 Add the next character that you type to the line verbatim. This
611 is how to insert characters like C-q, for example.
612 tab-insert (M-TAB)
613 Insert a tab character.
614 self-insert (a, b, A, 1, !, ...)
615 Insert the character typed.
616 transpose-chars (C-t)
617 Drag the character before point forward over the character at
618 point, moving point forward as well. If point is at the end of
619 the line, then this transposes the two characters before point.
620 Negative arguments have no effect.
621 transpose-words (M-t)
622 Drag the word before point past the word after point, moving
623 point over that word as well. If point is at the end of the
624 line, this transposes the last two words on the line.
625 upcase-word (M-u)
626 Uppercase the current (or following) word. With a negative
627 argument, uppercase the previous word, but do not move point.
628 downcase-word (M-l)
629 Lowercase the current (or following) word. With a negative
630 argument, lowercase the previous word, but do not move point.
631 capitalize-word (M-c)
632 Capitalize the current (or following) word. With a negative
633 argument, capitalize the previous word, but do not move point.
634 overwrite-mode
635 Toggle overwrite mode. With an explicit positive numeric argu‐
636 ment, switches to overwrite mode. With an explicit non-positive
637 numeric argument, switches to insert mode. This command affects
638 only emacs mode; vi mode does overwrite differently. Each call
639 to readline() starts in insert mode. In overwrite mode, charac‐
640 ters bound to self-insert replace the text at point rather than
641 pushing the text to the right. Characters bound to back‐
642 ward-delete-char replace the character before point with a
643 space. By default, this command is unbound.
644 Killing and Yanking
646 kill-line (C-k)
647 Kill the text from point to the end of the line.
648 backward-kill-line (C-x Rubout)
649 Kill backward to the beginning of the line.
650 unix-line-discard (C-u)
651 Kill backward from point to the beginning of the line. The
652 killed text is saved on the kill-ring.
653 kill-whole-line
654 Kill all characters on the current line, no matter where point
655 is.
656 kill-word (M-d)
657 Kill from point the end of the current word, or if between
658 words, to the end of the next word. Word boundaries are the
659 same as those used by forward-word.
660 backward-kill-word (M-Rubout)
661 Kill the word behind point. Word boundaries are the same as
662 those used by backward-word.
663 unix-word-rubout (C-w)
664 Kill the word behind point, using white space as a word bound‐
665 ary. The killed text is saved on the kill-ring.
666 unix-filename-rubout
667 Kill the word behind point, using white space and the slash
668 character as the word boundaries. The killed text is saved on
669 the kill-ring.
670 delete-horizontal-space (M-\)
671 Delete all spaces and tabs around point.
672 kill-region
673 Kill the text between the point and mark (saved cursor posi‐
674 tion). This text is referred to as the region.
675 copy-region-as-kill
676 Copy the text in the region to the kill buffer.
677 copy-backward-word
678 Copy the word before point to the kill buffer. The word bound‐
679 aries are the same as backward-word.
680 copy-forward-word
681 Copy the word following point to the kill buffer. The word
682 boundaries are the same as forward-word.
683 yank (C-y)
684 Yank the top of the kill ring into the buffer at point.
685 yank-pop (M-y)
686 Rotate the kill ring, and yank the new top. Only works follow‐
687 ing yank or yank-pop.
688 Numeric Arguments
690 digit-argument (M-0, M-1, ..., M--)
691 Add this digit to the argument already accumulating, or start a
692 new argument. M-- starts a negative argument.
693 universal-argument
694 This is another way to specify an argument. If this command is
695 followed by one or more digits, optionally with a leading minus
696 sign, those digits define the argument. If the command is fol‐
697 lowed by digits, executing universal-argument again ends the
698 numeric argument, but is otherwise ignored. As a special case,
699 if this command is immediately followed by a character that is
700 neither a digit or minus sign, the argument count for the next
701 command is multiplied by four. The argument count is initially
702 one, so executing this function the first time makes the argu‐
703 ment count four, a second time makes the argument count sixteen,
704 and so on.
705 Completing
707 complete (TAB)
708 Attempt to perform completion on the text before point. The
709 actual completion performed is application-specific. Bash, for
710 instance, attempts completion treating the text as a variable
711 (if the text begins with $), username (if the text begins with
712 ~), hostname (if the text begins with @), or command (including
713 aliases and functions) in turn. If none of these produces a
714 match, filename completion is attempted. Gdb, on the other
715 hand, allows completion of program functions and variables, and
716 only attempts filename completion under certain circumstances.
717 possible-completions (M-?)
718 List the possible completions of the text before point. When
719 displaying completions, readline sets the number of columns used
720 for display to the value of completion-display-width, the value
721 of the environment variable COLUMNS, or the screen width, in
722 that order.
723 insert-completions (M-*)
724 Insert all completions of the text before point that would have
725 been generated by possible-completions.
726 menu-complete
727 Similar to complete, but replaces the word to be completed with
728 a single match from the list of possible completions. Repeated
729 execution of menu-complete steps through the list of possible
730 completions, inserting each match in turn. At the end of the
731 list of completions, the bell is rung (subject to the setting of
732 bell-style) and the original text is restored. An argument of n
733 moves n positions forward in the list of matches; a negative
734 argument may be used to move backward through the list. This
735 command is intended to be bound to TAB, but is unbound by
736 default.
737 menu-complete-backward
738 Identical to menu-complete, but moves backward through the list
739 of possible completions, as if menu-complete had been given a
740 negative argument. This command is unbound by default.
741 delete-char-or-list
742 Deletes the character under the cursor if not at the beginning
743 or end of the line (like delete-char). If at the end of the
744 line, behaves identically to possible-completions.
745 Keyboard Macros
747 start-kbd-macro (C-x ()
748 Begin saving the characters typed into the current keyboard
749 macro.
750 end-kbd-macro (C-x ))
751 Stop saving the characters typed into the current keyboard macro
752 and store the definition.
753 call-last-kbd-macro (C-x e)
754 Re-execute the last keyboard macro defined, by making the char‐
755 acters in the macro appear as if typed at the keyboard.
756 print-last-kbd-macro () Print the last keyboard macro defined in
757 a format suitable for the inputrc file.
758 Miscellaneous
760 re-read-init-file (C-x C-r)
761 Read in the contents of the inputrc file, and incorporate any
762 bindings or variable assignments found there.
763 abort (C-g)
764 Abort the current editing command and ring the terminal's bell
765 (subject to the setting of bell-style).
766 do-uppercase-version (M-a, M-b, M-x, ...)
767 If the metafied character x is lowercase, run the command that
768 is bound to the corresponding uppercase character.
769 prefix-meta (ESC)
770 Metafy the next character typed. ESC f is equivalent to Meta-f.
771 undo (C-_, C-x C-u)
772 Incremental undo, separately remembered for each line.
773 revert-line (M-r)
774 Undo all changes made to this line. This is like executing the
775 undo command enough times to return the line to its initial
776 state.
777 tilde-expand (M-&)
778 Perform tilde expansion on the current word.
779 set-mark (C-@, M-<space>)
780 Set the mark to the point. If a numeric argument is supplied,
781 the mark is set to that position.
782 exchange-point-and-mark (C-x C-x)
783 Swap the point with the mark. The current cursor position is
784 set to the saved position, and the old cursor position is saved
785 as the mark.
786 character-search (C-])
787 A character is read and point is moved to the next occurrence of
788 that character. A negative count searches for previous occur‐
789 rences.
790 character-search-backward (M-C-])
791 A character is read and point is moved to the previous occur‐
792 rence of that character. A negative count searches for subse‐
793 quent occurrences.
794 skip-csi-sequence
795 Read enough characters to consume a multi-key sequence such as
796 those defined for keys like Home and End. Such sequences begin
797 with a Control Sequence Indicator (CSI), usually ESC-[. If this
798 sequence is bound to "\[", keys producing such sequences will
799 have no effect unless explicitly bound to a readline command,
800 instead of inserting stray characters into the editing buffer.
801 This is unbound by default, but usually bound to ESC-[.
802 insert-comment (M-#)
803 Without a numeric argument, the value of the readline com‐
804 ment-begin variable is inserted at the beginning of the current
805 line. If a numeric argument is supplied, this command acts as a
806 toggle: if the characters at the beginning of the line do not
807 match the value of comment-begin, the value is inserted, other‐
808 wise the characters in comment-begin are deleted from the begin‐
809 ning of the line. In either case, the line is accepted as if a
810 newline had been typed. The default value of comment-begin
811 makes the current line a shell comment. If a numeric argument
812 causes the comment character to be removed, the line will be
813 executed by the shell.
814 dump-functions
815 Print all of the functions and their key bindings to the read‐
816 line output stream. If a numeric argument is supplied, the out‐
817 put is formatted in such a way that it can be made part of an
818 inputrc file.
819 dump-variables
820 Print all of the settable variables and their values to the
821 readline output stream. If a numeric argument is supplied, the
822 output is formatted in such a way that it can be made part of an
823 inputrc file.
824 dump-macros
825 Print all of the readline key sequences bound to macros and the
826 strings they output. If a numeric argument is supplied, the
827 output is formatted in such a way that it can be made part of an
828 inputrc file.
829 emacs-editing-mode (C-e)
830 When in vi command mode, this causes a switch to emacs editing
831 mode.
832 vi-editing-mode (M-C-j)
833 When in emacs editing mode, this causes a switch to vi editing
834 mode.
835
837 The following is a list of the default emacs and vi bindings. Charac‐
838 ters with the eighth bit set are written as M-<character>, and are
839 referred to as metafied characters. The printable ASCII characters not
840 mentioned in the list of emacs standard bindings are bound to the
841 self-insert function, which just inserts the given character into the
842 input line. In vi insertion mode, all characters not specifically men‐
843 tioned are bound to self-insert. Characters assigned to signal genera‐
844 tion by stty(1) or the terminal driver, such as C-Z or C-C, retain that
845 function. Upper and lower case metafied characters are bound to the
846 same function in the emacs mode meta keymap. The remaining characters
847 are unbound, which causes readline to ring the bell (subject to the
848 setting of the bell-style variable).
849 Emacs Mode
851 Emacs Standard bindings
852 "C-@" set-mark
854 "C-A" beginning-of-line
855 "C-B" backward-char
856 "C-D" delete-char
857 "C-E" end-of-line
858 "C-F" forward-char
859 "C-G" abort
860 "C-H" backward-delete-char
861 "C-I" complete
862 "C-J" accept-line
863 "C-K" kill-line
864 "C-L" clear-screen
865 "C-M" accept-line
866 "C-N" next-history
867 "C-P" previous-history
868 "C-Q" quoted-insert
869 "C-R" reverse-search-history
870 "C-S" forward-search-history
871 "C-T" transpose-chars
872 "C-U" unix-line-discard
873 "C-V" quoted-insert
874 "C-W" unix-word-rubout
875 "C-Y" yank
876 "C-]" character-search
877 "C-_" undo
878 " " to "/" self-insert
879 "0" to "9" self-insert
880 ":" to "~" self-insert
881 "C-?" backward-delete-char
882 Emacs Meta bindings
884 "M-C-G" abort
886 "M-C-H" backward-kill-word
887 "M-C-I" tab-insert
888 "M-C-J" vi-editing-mode
889 "M-C-M" vi-editing-mode
890 "M-C-R" revert-line
891 "M-C-Y" yank-nth-arg
892 "M-C-[" complete
893 "M-C-]" character-search-backward
894 "M-space" set-mark
895 "M-#" insert-comment
896 "M-&" tilde-expand
897 "M-*" insert-completions
898 "M--" digit-argument
899 "M-." yank-last-arg
900 "M-0" digit-argument
901 "M-1" digit-argument
902 "M-2" digit-argument
903 "M-3" digit-argument
904 "M-4" digit-argument
905 "M-5" digit-argument
906 "M-6" digit-argument
907 "M-7" digit-argument
908 "M-8" digit-argument
909 "M-9" digit-argument
910 "M-<" beginning-of-history
911 "M-=" possible-completions
912 "M->" end-of-history
913 "M-?" possible-completions
914 "M-B" backward-word
915 "M-C" capitalize-word
916 "M-D" kill-word
917 "M-F" forward-word
918 "M-L" downcase-word
919 "M-N" non-incremental-forward-search-history
920 "M-P" non-incremental-reverse-search-history
921 "M-R" revert-line
922 "M-T" transpose-words
923 "M-U" upcase-word
924 "M-Y" yank-pop
925 "M-\" delete-horizontal-space
926 "M-~" tilde-expand
927 "M-C-?" backward-kill-word
928 "M-_" yank-last-arg
929 Emacs Control-X bindings
931 "C-XC-G" abort
933 "C-XC-R" re-read-init-file
934 "C-XC-U" undo
935 "C-XC-X" exchange-point-and-mark
936 "C-X(" start-kbd-macro
937 "C-X)" end-kbd-macro
938 "C-XE" call-last-kbd-macro
939 "C-XC-?" backward-kill-line
940 VI Mode bindings
943 VI Insert Mode functions
944 "C-D" vi-eof-maybe
946 "C-H" backward-delete-char
947 "C-I" complete
948 "C-J" accept-line
949 "C-M" accept-line
950 "C-R" reverse-search-history
951 "C-S" forward-search-history
952 "C-T" transpose-chars
953 "C-U" unix-line-discard
954 "C-V" quoted-insert
955 "C-W" unix-word-rubout
956 "C-Y" yank
957 "C-[" vi-movement-mode
958 "C-_" undo
959 " " to "~" self-insert
960 "C-?" backward-delete-char
961 VI Command Mode functions
963 "C-D" vi-eof-maybe
965 "C-E" emacs-editing-mode
966 "C-G" abort
967 "C-H" backward-char
968 "C-J" accept-line
969 "C-K" kill-line
970 "C-L" clear-screen
971 "C-M" accept-line
972 "C-N" next-history
973 "C-P" previous-history
974 "C-Q" quoted-insert
975 "C-R" reverse-search-history
976 "C-S" forward-search-history
977 "C-T" transpose-chars
978 "C-U" unix-line-discard
979 "C-V" quoted-insert
980 "C-W" unix-word-rubout
981 "C-Y" yank
982 "C-_" vi-undo
983 " " forward-char
984 "#" insert-comment
985 "$" end-of-line
986 "%" vi-match
987 "&" vi-tilde-expand
988 "*" vi-complete
989 "+" next-history
990 "," vi-char-search
991 "-" previous-history
992 "." vi-redo
993 "/" vi-search
994 "0" beginning-of-line
995 "1" to "9" vi-arg-digit
996 ";" vi-char-search
997 "=" vi-complete
998 "?" vi-search
999 "A" vi-append-eol
1000 "B" vi-prev-word
1001 "C" vi-change-to
1002 "D" vi-delete-to
1003 "E" vi-end-word
1004 "F" vi-char-search
1005 "G" vi-fetch-history
1006 "I" vi-insert-beg
1007 "N" vi-search-again
1008 "P" vi-put
1009 "R" vi-replace
1010 "S" vi-subst
1011 "T" vi-char-search
1012 "U" revert-line
1013 "W" vi-next-word
1014 "X" backward-delete-char
1015 "Y" vi-yank-to
1016 "\" vi-complete
1017 "^" vi-first-print
1018 "_" vi-yank-arg
1019 "`" vi-goto-mark
1020 "a" vi-append-mode
1021 "b" vi-prev-word
1022 "c" vi-change-to
1023 "d" vi-delete-to
1024 "e" vi-end-word
1025 "f" vi-char-search
1026 "h" backward-char
1027 "i" vi-insertion-mode
1028 "j" next-history
1029 "k" prev-history
1030 "l" forward-char
1031 "m" vi-set-mark
1032 "n" vi-search-again
1033 "p" vi-put
1034 "r" vi-change-char
1035 "s" vi-subst
1036 "t" vi-char-search
1037 "u" vi-undo
1038 "w" vi-next-word
1039 "x" vi-delete
1040 "y" vi-yank-to
1041 "|" vi-column
1042 "~" vi-change-case
1043
1045 The Gnu Readline Library, Brian Fox and Chet Ramey
1046 The Gnu History Library, Brian Fox and Chet Ramey
1047 bash(1)
1048
1050 ~/.inputrc
1051 Individual readline initialization file
1052
1054 Brian Fox, Free Software Foundation
1055 bfox@gnu.org
1056 Chet Ramey, Case Western Reserve University
1058 chet.ramey@case.edu
1059
1061 If you find a bug in readline, you should report it. But first, you
1062 should make sure that it really is a bug, and that it appears in the
1063 latest version of the readline library that you have.
1064 Once you have determined that a bug actually exists, mail a bug report
1066 to bug-readline@gnu.org. If you have a fix, you are welcome to mail
1067 that as well! Suggestions and `philosophical' bug reports may be
1068 mailed to bug-readline@gnu.org or posted to the Usenet newsgroup
1069 gnu.bash.bug.
1070 Comments and bug reports concerning this manual page should be directed
1072 to chet.ramey@case.edu.
1073
1075 It's too big and too slow.
1076GNU Readline 7.0 2016 February 28 READLINE(3)