1READLINE(3)                Library Functions Manual                READLINE(3)
2
3
4

NAME

6       readline - get a line from a user with editing
7

SYNOPSIS

9       #include <stdio.h>
10       #include <readline/readline.h>
11       #include <readline/history.h>
12
13       char *
14       readline (const char *prompt);
15
17       Readline is Copyright (C) 1989-2020 Free Software Foundation,  Inc.
18

DESCRIPTION

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  is‐
22       sued.   The  line returned is allocated with malloc(3); the caller must
23       free it when finished.  The line returned has  the  final  newline  re‐
24       moved, so only the text of the line remains.
25
26       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
30       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

RETURN VALUE

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

NOTATION

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
49       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
56       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

INITIALIZATION FILE

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 de‐
66       fault 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
75       For example, placing
76
77              M-Control-u: universal-argument
78       or
79              C-Meta-u: universal-argument
80
81       into  the inputrc would make M-C-u execute the readline command univer‐
82       sal-argument.
83
84       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
88       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
91   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
100       When using the form keyname:function-name or macro, keyname is the name
101       of a key spelled out in English.  For example:
102
103              Control-u: universal-argument
104              Meta-Rubout: backward-kill-word
105              Control-o: "> output"
106
107       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
112       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
118              "\C-u": universal-argument
119              "\C-x\C-r": re-read-init-file
120              "\e[11~": "Function Key 1"
121
122       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
126       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
135       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
150       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
156       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
163   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
168              set variable-name value
169
170       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
176       active-region-start-color
177              A string variable that controls the text  color  and  background
178              when  displaying the text in the active region (see the descrip‐
179              tion of enable-active-region below).  This string must not  take
180              up any physical character positions on the display, so it should
181              consist only of terminal escape sequences.  It is output to  the
182              terminal  before displaying the text in the active region.  This
183              variable is reset to the default  value  whenever  the  terminal
184              type  changes.   The  default  value is the string that puts the
185              terminal in standout mode, as obtained from the terminal's  ter‐
186              minfo description.  A sample value might be "\e[01;33m".
187       active-region-end-color
188              A  string  variable  that  "undoes"  the  effects  of active-re‐
189              gion-start-color and restores "normal" terminal display  appear‐
190              ance  after  displaying  text in the active region.  This string
191              must not take up any physical character positions  on  the  dis‐
192              play,  so  it  should consist only of terminal escape sequences.
193              It is output to the terminal after displaying the  text  in  the
194              active  region.   This  variable  is  reset to the default value
195              whenever the terminal type changes.  The default  value  is  the
196              string  that  restores  the  terminal from standout mode, as ob‐
197              tained from the terminal's terminfo description.  A sample value
198              might be "\e[0m".
199       bell-style (audible)
200              Controls  what  happens when readline wants to ring the terminal
201              bell.  If set to none, readline never rings the bell.  If set to
202              visible,  readline  uses a visible bell if one is available.  If
203              set to audible, readline attempts to ring the terminal's bell.
204       bind-tty-special-chars (On)
205              If set to On (the default), readline attempts to bind  the  con‐
206              trol  characters    treated  specially  by the kernel's terminal
207              driver to their readline equivalents.
208       blink-matching-paren (Off)
209              If set to On, readline attempts to briefly move the cursor to an
210              opening parenthesis when a closing parenthesis is inserted.
211       colored-completion-prefix (Off)
212              If  set  to  On, when listing completions, readline displays the
213              common prefix of the set of possible completions using a differ‐
214              ent  color.   The  color definitions are taken from the value of
215              the LS_COLORS environment variable.  If there is a color defini‐
216              tion  in $LS_COLORS for the custom suffix "readline-colored-com‐
217              pletion-prefix", readline uses this color for the common  prefix
218              instead of its default.
219       colored-stats (Off)
220              If  set to On, readline displays possible completions using dif‐
221              ferent colors to indicate their file type.   The  color  defini‐
222              tions  are  taken  from  the  value of the LS_COLORS environment
223              variable.
224       comment-begin (``#'')
225              The string that is inserted in vi mode when  the  insert-comment
226              command is executed.  This command is bound to M-# in emacs mode
227              and to # in vi command mode.
228       completion-display-width (-1)
229              The number of screen columns used to  display  possible  matches
230              when  performing completion.  The value is ignored if it is less
231              than 0 or greater than the terminal screen width.  A value of  0
232              will  cause  matches  to be displayed one per line.  The default
233              value is -1.
234       completion-ignore-case (Off)
235              If set to On, readline performs filename matching and completion
236              in a case-insensitive fashion.
237       completion-map-case (Off)
238              If  set  to  On, and completion-ignore-case is enabled, readline
239              treats hyphens (-) and underscores (_) as equivalent  when  per‐
240              forming case-insensitive filename matching and completion.
241       completion-prefix-display-length (0)
242              The  length in characters of the common prefix of a list of pos‐
243              sible completions that is displayed without modification.   When
244              set  to  a  value greater than zero, common prefixes longer than
245              this value are replaced with an ellipsis when displaying  possi‐
246              ble completions.
247       completion-query-items (100)
248              This  determines when the user is queried about viewing the num‐
249              ber of possible completions generated  by  the  possible-comple‐
250              tions  command.  It may be set to any integer value greater than
251              or equal to zero.  If the  number  of  possible  completions  is
252              greater  than  or  equal to the value of this variable, readline
253              will ask whether or not the user wishes to view them;  otherwise
254              they are simply listed on the terminal.  A negative value causes
255              readline to never ask.
256       convert-meta (On)
257              If set to On, readline will convert characters with  the  eighth
258              bit set to an ASCII key sequence by stripping the eighth bit and
259              prefixing it with an escape character (in effect,  using  escape
260              as  the  meta prefix).  The default is On, but readline will set
261              it to Off if the locale  contains  eight-bit  characters.   This
262              variable  is  dependent on the LC_CTYPE locale category, and may
263              change if the locale is changed.
264       disable-completion (Off)
265              If set to On, readline will inhibit word completion.  Completion
266              characters  will  be  inserted into the line as if they had been
267              mapped to self-insert.
268       echo-control-characters (On)
269              When set to On, on operating systems that indicate they  support
270              it, readline echoes a character corresponding to a signal gener‐
271              ated from the keyboard.
272       editing-mode (emacs)
273              Controls whether readline begins with a set of key bindings sim‐
274              ilar to Emacs or vi.  editing-mode can be set to either emacs or
275              vi.
276       emacs-mode-string (@)
277              If the show-mode-in-prompt variable is enabled, this  string  is
278              displayed immediately before the last line of the primary prompt
279              when emacs editing mode is active.  The value is expanded like a
280              key  binding,  so the standard set of meta- and control prefixes
281              and backslash escape sequences is available.  Use the \1 and  \2
282              escapes  to  begin and end sequences of non-printing characters,
283              which can be used to embed a terminal control sequence into  the
284              mode string.
285       enable-active-region (On)
286              The  point  is the current cursor position, and mark refers to a
287              saved cursor position.  The text between the point and  mark  is
288              referred  to  as  the  region.  When this variable is set to On,
289              readline allows certain commands to designate the region as  ac‐
290              tive.   When  the region is active, readline highlights the text
291              in the region using the value of the  active-region-start-color,
292              which  defaults to the string that enables the terminal's stand‐
293              out mode.  The active region shows the text inserted  by  brack‐
294              eted-paste  and  any matching text found by incremental and non-
295              incremental history searches.
296       enable-bracketed-paste (On)
297              When set to On, readline configures the terminal to insert  each
298              paste  into the editing buffer as a single string of characters,
299              instead of treating each character as if it had been  read  from
300              the keyboard.  This prevents readline from executing any editing
301              commands bound to key sequences appearing in the pasted text.
302       enable-keypad (Off)
303              When set to On, readline will try to enable the application key‐
304              pad when it is called.  Some systems need this to enable the ar‐
305              row keys.
306       enable-meta-key (On)
307              When set to On, readline will try to enable  any  meta  modifier
308              key  the  terminal claims to support when it is called.  On many
309              terminals, the meta key is used to send eight-bit characters.
310       expand-tilde (Off)
311              If set to On, tilde expansion is  performed  when  readline  at‐
312              tempts word completion.
313       history-preserve-point (Off)
314              If  set  to  On, the history code attempts to place point at the
315              same location on each history line retrieved with  previous-his‐
316              tory or next-history.
317       history-size (unset)
318              Set  the  maximum number of history entries saved in the history
319              list.  If set to zero, any existing history entries are  deleted
320              and no new entries are saved.  If set to a value less than zero,
321              the number of history entries is not limited.  By  default,  the
322              number of history entries is not limited.  If an attempt is made
323              to set history-size to a non-numeric value, the  maximum  number
324              of history entries will be set to 500.
325       horizontal-scroll-mode (Off)
326              When  set  to  On, makes readline use a single line for display,
327              scrolling the input horizontally on a single screen line when it
328              becomes  longer  than the screen width rather than wrapping to a
329              new line.  This setting is automatically enabled  for  terminals
330              of height 1.
331       input-meta (Off)
332              If  set to On, readline will enable eight-bit input (that is, it
333              will not clear the eighth bit in the characters it  reads),  re‐
334              gardless  of  what the terminal claims it can support.  The name
335              meta-flag is a synonym for this variable.  The default  is  Off,
336              but  readline will set it to On if the locale contains eight-bit
337              characters.  This variable is dependent on the  LC_CTYPE  locale
338              category, and may change if the locale is changed.
339       isearch-terminators (``C-[ C-J'')
340              The  string  of  characters that should terminate an incremental
341              search without subsequently executing the character  as  a  com‐
342              mand.   If this variable has not been given a value, the charac‐
343              ters ESC and C-J will terminate an incremental search.
344       keymap (emacs)
345              Set the current readline keymap.  The set of legal keymap  names
346              is  emacs,  emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
347              vi-command, and vi-insert.   vi  is  equivalent  to  vi-command;
348              emacs  is  equivalent  to  emacs-standard.  The default value is
349              emacs.  The value  of  editing-mode  also  affects  the  default
350              keymap.
351       keyseq-timeout (500)
352              Specifies  the  duration readline will wait for a character when
353              reading an ambiguous key sequence (one that can form a  complete
354              key sequence using the input read so far, or can take additional
355              input to complete a longer key sequence).  If no  input  is  re‐
356              ceived  within  the  timeout,  readline will use the shorter but
357              complete key sequence.  The value is specified in  milliseconds,
358              so  a value of 1000 means that readline will wait one second for
359              additional input.  If this variable is set to a value less  than
360              or  equal to zero, or to a non-numeric value, readline will wait
361              until another key is pressed to decide  which  key  sequence  to
362              complete.
363       mark-directories (On)
364              If set to On, completed directory names have a slash appended.
365       mark-modified-lines (Off)
366              If  set  to  On,  history lines that have been modified are dis‐
367              played with a preceding asterisk (*).
368       mark-symlinked-directories (Off)
369              If set to On, completed names which are symbolic links to direc‐
370              tories  have  a slash appended (subject to the value of mark-di‐
371              rectories).
372       match-hidden-files (On)
373              This variable, when set to On, causes readline  to  match  files
374              whose  names  begin  with  a  `.' (hidden files) when performing
375              filename completion.  If set to Off, the  leading  `.'  must  be
376              supplied by the user in the filename to be completed.
377       menu-complete-display-prefix (Off)
378              If  set to On, menu completion displays the common prefix of the
379              list of possible completions (which may be empty) before cycling
380              through the list.
381       output-meta (Off)
382              If  set  to On, readline will display characters with the eighth
383              bit set directly rather than as a meta-prefixed escape sequence.
384              The default is Off, but readline will set it to On if the locale
385              contains eight-bit characters.  This variable  is  dependent  on
386              the  LC_CTYPE  locale  category, and may change if the locale is
387              changed.
388       page-completions (On)
389              If set to On, readline uses an internal more-like pager to  dis‐
390              play a screenful of possible completions at a time.
391       print-completions-horizontally (Off)
392              If  set  to  On,  readline will display completions with matches
393              sorted horizontally in alphabetical order, rather than down  the
394              screen.
395       revert-all-at-newline (Off)
396              If  set  to  On, readline will undo all changes to history lines
397              before returning when accept-line is executed.  By default, his‐
398              tory  lines  may  be  modified  and retain individual undo lists
399              across calls to readline.
400       show-all-if-ambiguous (Off)
401              This alters the default behavior of  the  completion  functions.
402              If set to On, words which have more than one possible completion
403              cause the matches to be listed immediately  instead  of  ringing
404              the bell.
405       show-all-if-unmodified (Off)
406              This  alters the default behavior of the completion functions in
407              a fashion similar to show-all-if-ambiguous.  If set to On, words
408              which  have more than one possible completion without any possi‐
409              ble partial completion (the possible completions don't  share  a
410              common  prefix)  cause  the matches to be listed immediately in‐
411              stead of ringing the bell.
412       show-mode-in-prompt (Off)
413              If set to On, add a string to the beginning of the prompt  indi‐
414              cating  the  editing  mode:  emacs, vi command, or vi insertion.
415              The mode strings are user-settable (e.g., emacs-mode-string).
416       skip-completed-text (Off)
417              If set to On, this alters the default completion  behavior  when
418              inserting  a  single match into the line.  It's only active when
419              performing completion in the middle  of  a  word.   If  enabled,
420              readline  does  not  insert  characters from the completion that
421              match characters after point in the  word  being  completed,  so
422              portions of the word following the cursor are not duplicated.
423       vi-cmd-mode-string ((cmd))
424              If  the  show-mode-in-prompt variable is enabled, this string is
425              displayed immediately before the last line of the primary prompt
426              when  vi  editing mode is active and in command mode.  The value
427              is expanded like a key binding, so the standard set of meta- and
428              control  prefixes  and  backslash escape sequences is available.
429              Use the \1 and \2 escapes to begin and  end  sequences  of  non-
430              printing  characters, which can be used to embed a terminal con‐
431              trol sequence into the mode string.
432       vi-ins-mode-string ((ins))
433              If the show-mode-in-prompt variable is enabled, this  string  is
434              displayed immediately before the last line of the primary prompt
435              when vi editing mode is active and in insertion mode.  The value
436              is expanded like a key binding, so the standard set of meta- and
437              control prefixes and backslash escape  sequences  is  available.
438              Use  the  \1  and  \2 escapes to begin and end sequences of non-
439              printing characters, which can be used to embed a terminal  con‐
440              trol sequence into the mode string.
441       visible-stats (Off)
442              If  set to On, a character denoting a file's type as reported by
443              stat(2) is appended to the filename when listing  possible  com‐
444              pletions.
445
446   Conditional Constructs
447       Readline  implements  a  facility  similar in spirit to the conditional
448       compilation features of the C preprocessor which  allows  key  bindings
449       and  variable  settings  to be performed as the result of tests.  There
450       are four parser directives used.
451
452       $if    The $if construct allows bindings to be made based on the  edit‐
453              ing  mode,  the  terminal  being  used, or the application using
454              readline.  The text of the test, after any comparison  operator,
455              extends to the end of the line; unless otherwise noted, no char‐
456              acters are required to isolate it.
457
458              mode   The mode= form of the  $if  directive  is  used  to  test
459                     whether  readline  is  in  emacs or vi mode.  This may be
460                     used in conjunction with the set keymap command, for  in‐
461                     stance,  to set bindings in the emacs-standard and emacs-
462                     ctlx keymaps only if readline is starting  out  in  emacs
463                     mode.
464
465              term   The  term=  form may be used to include terminal-specific
466                     key bindings, perhaps to bind the key sequences output by
467                     the terminal's function keys.  The word on the right side
468                     of the = is tested against the full name of the  terminal
469                     and  the portion of the terminal name before the first -.
470                     This allows sun to match both sun and  sun-cmd,  for  in‐
471                     stance.
472
473              version
474                     The  version  test  may  be  used  to perform comparisons
475                     against specific readline versions.  The version  expands
476                     to  the  current readline version.  The set of comparison
477                     operators includes =, (and ==), !=, <=,  >=,  <,  and  >.
478                     The  version number supplied on the right side of the op‐
479                     erator consists of a major version  number,  an  optional
480                     decimal point, and an optional minor version (e.g., 7.1).
481                     If the minor version is omitted, it is assumed to  be  0.
482                     The operator may be separated from the string version and
483                     from the version number argument by whitespace.
484
485              application
486                     The application construct is used to include application-
487                     specific  settings.   Each program using the readline li‐
488                     brary sets the application name,  and  an  initialization
489                     file can test for a particular value.  This could be used
490                     to bind key sequences to functions useful for a  specific
491                     program.   For instance, the following command adds a key
492                     sequence that quotes the  current  or  previous  word  in
493                     bash:
494
495                     $if Bash
496                     # Quote the current or previous word
497                     "\C-xq": "\eb\"\ef\""
498                     $endif
499
500              variable
501                     The variable construct provides simple equality tests for
502                     readline variables and values.  The permitted  comparison
503                     operators  are  =, ==, and !=.  The variable name must be
504                     separated from the comparison operator by whitespace; the
505                     operator  may  be  separated  from the value on the right
506                     hand side by whitespace.  Both string and  boolean  vari‐
507                     ables  may  be  tested.  Boolean variables must be tested
508                     against the values on and off.
509
510       $endif This command, as seen in the previous example, terminates an $if
511              command.
512
513       $else  Commands in this branch of the $if directive are executed if the
514              test fails.
515
516       $include
517              This directive takes a single filename as an argument and  reads
518              commands  and bindings from that file.  For example, the follow‐
519              ing directive would read /etc/inputrc:
520
521              $include  /etc/inputrc
522

SEARCHING

524       Readline provides commands for searching through  the  command  history
525       for  lines  containing a specified string.  There are two search modes:
526       incremental and non-incremental.
527
528       Incremental searches begin before the  user  has  finished  typing  the
529       search  string.  As each character of the search string is typed, read‐
530       line displays the next entry from the history matching the string typed
531       so  far.   An  incremental  search  requires only as many characters as
532       needed to find the desired history entry.  To search  backward  in  the
533       history for a particular string, type C-r.  Typing C-s searches forward
534       through the history.  The  characters  present  in  the  value  of  the
535       isearch-terminators  variable  are  used  to  terminate  an incremental
536       search.  If that variable has not been assigned a value the Escape  and
537       C-J characters will terminate an incremental search.  C-G will abort an
538       incremental search and restore the original line.  When the  search  is
539       terminated,  the history entry containing the search string becomes the
540       current line.
541
542       To find other matching entries in the history list, type C-s or C-r  as
543       appropriate.   This  will search backward or forward in the history for
544       the next line matching the search string typed so far.  Any  other  key
545       sequence bound to a readline command will terminate the search and exe‐
546       cute that command.  For instance, a newline will terminate  the  search
547       and  accept  the  line,  thereby executing the command from the history
548       list.  A movement command will terminate the search, make the last line
549       found the current line, and begin editing.
550
551       Non-incremental  searches read the entire search string before starting
552       to search for matching history lines.  The search string may  be  typed
553       by the user or be part of the contents of the current line.
554

EDITING COMMANDS

556       The  following  is  a list of the names of the commands and the default
557       key sequences to which they are bound.  Command names without an accom‐
558       panying key sequence are unbound by default.
559
560       In the following descriptions, point refers to the current cursor posi‐
561       tion, and mark refers to a cursor position saved by the  set-mark  com‐
562       mand.   The  text  between the point and mark is referred to as the re‐
563       gion.
564
565   Commands for Moving
566       beginning-of-line (C-a)
567              Move to the start of the current line.
568       end-of-line (C-e)
569              Move to the end of the line.
570       forward-char (C-f)
571              Move forward a character.
572       backward-char (C-b)
573              Move back a character.
574       forward-word (M-f)
575              Move forward to the end of the next word.  Words are composed of
576              alphanumeric characters (letters and digits).
577       backward-word (M-b)
578              Move  back  to the start of the current or previous word.  Words
579              are composed of alphanumeric characters (letters and digits).
580       previous-screen-line
581              Attempt to move point to the same physical screen column on  the
582              previous  physical  screen  line. This will not have the desired
583              effect if the current readline line does not take up  more  than
584              one  physical line or if point is not greater than the length of
585              the prompt plus the screen width.
586       next-screen-line
587              Attempt to move point to the same physical screen column on  the
588              next physical screen line. This will not have the desired effect
589              if the current readline line does not  take  up  more  than  one
590              physical  line  or if the length of the current readline line is
591              not greater than the length of the prompt plus the screen width.
592       clear-display (M-C-l)
593              Clear the screen and, if  possible,  the  terminal's  scrollback
594              buffer,  then  redraw the current line, leaving the current line
595              at the top of the screen.
596       clear-screen (C-l)
597              Clear the screen, then redraw the current line, leaving the cur‐
598              rent  line  at the top of the screen.  With an argument, refresh
599              the current line without clearing the screen.
600       redraw-current-line
601              Refresh the current line.
602
603   Commands for Manipulating the History
604       accept-line (Newline, Return)
605              Accept the line regardless of where the cursor is.  If this line
606              is non-empty, it may be added to the history list for future re‐
607              call with add_history().  If the  line  is  a  modified  history
608              line, the history line is restored to its original state.
609       previous-history (C-p)
610              Fetch the previous command from the history list, moving back in
611              the list.
612       next-history (C-n)
613              Fetch the next command from the history list, moving forward  in
614              the list.
615       beginning-of-history (M-<)
616              Move to the first line in the history.
617       end-of-history (M->)
618              Move  to  the end of the input history, i.e., the line currently
619              being entered.
620       operate-and-get-next (C-o)
621              Accept the current line for return to the calling application as
622              if  a newline had been entered, and fetch the next line relative
623              to the current line from the history for editing.  A numeric ar‐
624              gument,  if supplied, specifies the history entry to use instead
625              of the current line.
626       fetch-history
627              With a numeric argument, fetch that entry from the history  list
628              and make it the current line.  Without an argument, move back to
629              the first entry in the history list.
630       reverse-search-history (C-r)
631              Search backward starting at the current  line  and  moving  `up'
632              through  the  history  as  necessary.   This  is  an incremental
633              search.
634       forward-search-history (C-s)
635              Search forward starting at the current line  and  moving  `down'
636              through  the  history  as  necessary.   This  is  an incremental
637              search.
638       non-incremental-reverse-search-history (M-p)
639              Search backward through the history starting at the current line
640              using  a  non-incremental  search  for  a string supplied by the
641              user.
642       non-incremental-forward-search-history (M-n)
643              Search forward  through  the  history  using  a  non-incremental
644              search for a string supplied by the user.
645       history-search-backward
646              Search backward through the history for the string of characters
647              between the start of the current line and the current cursor po‐
648              sition  (the point).  The search string must match at the begin‐
649              ning of a history line.  This is a non-incremental search.
650       history-search-forward
651              Search forward through the history for the string of  characters
652              between the start of the current line and the point.  The search
653              string must match at the beginning of a history line.  This is a
654              non-incremental search.
655       history-substring-search-backward
656              Search backward through the history for the string of characters
657              between the start of the current line and the current cursor po‐
658              sition  (the  point).  The search string may match anywhere in a
659              history line.  This is a non-incremental search.
660       history-substring-search-forward
661              Search forward through the history for the string of  characters
662              between the start of the current line and the point.  The search
663              string may match anywhere in a history line.  This is a  non-in‐
664              cremental search.
665       yank-nth-arg (M-C-y)
666              Insert  the  first argument to the previous command (usually the
667              second word on the previous line) at point.  With an argument n,
668              insert  the nth word from the previous command (the words in the
669              previous command begin with word 0).  A  negative  argument  in‐
670              serts  the  nth word from the end of the previous command.  Once
671              the argument n is computed, the argument is extracted as if  the
672              "!n" history expansion had been specified.
673       yank-last-arg (M-., M-_)
674              Insert  the last argument to the previous command (the last word
675              of the previous history entry).  With a numeric argument, behave
676              exactly  like  yank-nth-arg.   Successive calls to yank-last-arg
677              move back through the history list, inserting the last word  (or
678              the  word  specified  by the argument to the first call) of each
679              line in turn.  Any numeric argument supplied to these successive
680              calls  determines  the direction to move through the history.  A
681              negative argument switches the  direction  through  the  history
682              (back or forward).  The history expansion facilities are used to
683              extract the last argument, as if the "!$" history expansion  had
684              been specified.
685
686   Commands for Changing Text
687       end-of-file (usually C-d)
688              The  character  indicating  end-of-file  as set, for example, by
689              ``stty''.  If this character is read when there are  no  charac‐
690              ters  on  the  line,  and point is at the beginning of the line,
691              readline interprets it as the end of input and returns EOF.
692       delete-char (C-d)
693              Delete the character at point.  If this function is bound to the
694              same character as the tty EOF character, as C-d commonly is, see
695              above for the effects.
696       backward-delete-char (Rubout)
697              Delete the character behind the cursor.  When  given  a  numeric
698              argument, save the deleted text on the kill ring.
699       forward-backward-delete-char
700              Delete  the  character under the cursor, unless the cursor is at
701              the end of the line, in which case the character behind the cur‐
702              sor is deleted.
703       quoted-insert (C-q, C-v)
704              Add the next character that you type to the line verbatim.  This
705              is how to insert characters like C-q, for example.
706       tab-insert (M-TAB)
707              Insert a tab character.
708       self-insert (a, b, A, 1, !, ...)
709              Insert the character typed.
710       transpose-chars (C-t)
711              Drag the character before point forward over  the  character  at
712              point,  moving point forward as well.  If point is at the end of
713              the line, then this transposes the two characters before  point.
714              Negative arguments have no effect.
715       transpose-words (M-t)
716              Drag  the  word  before  point past the word after point, moving
717              point over that word as well.  If point is at  the  end  of  the
718              line, this transposes the last two words on the line.
719       upcase-word (M-u)
720              Uppercase  the current (or following) word.  With a negative ar‐
721              gument, uppercase the previous word, but do not move point.
722       downcase-word (M-l)
723              Lowercase the current (or following) word.  With a negative  ar‐
724              gument, lowercase the previous word, but do not move point.
725       capitalize-word (M-c)
726              Capitalize the current (or following) word.  With a negative ar‐
727              gument, capitalize the previous word, but do not move point.
728       overwrite-mode
729              Toggle overwrite mode.  With an explicit positive numeric  argu‐
730              ment, switches to overwrite mode.  With an explicit non-positive
731              numeric argument, switches to insert mode.  This command affects
732              only  emacs mode; vi mode does overwrite differently.  Each call
733              to readline() starts in insert mode.  In overwrite mode, charac‐
734              ters  bound to self-insert replace the text at point rather than
735              pushing the text  to  the  right.   Characters  bound  to  back‐
736              ward-delete-char  replace  the  character  before  point  with a
737              space.  By default, this command is unbound.
738
739   Killing and Yanking
740       kill-line (C-k)
741              Kill the text from point to the end of the line.
742       backward-kill-line (C-x Rubout)
743              Kill backward to the beginning of the line.
744       unix-line-discard (C-u)
745              Kill backward from point to the  beginning  of  the  line.   The
746              killed text is saved on the kill-ring.
747       kill-whole-line
748              Kill  all  characters on the current line, no matter where point
749              is.
750       kill-word (M-d)
751              Kill from point the end of  the  current  word,  or  if  between
752              words,  to  the  end  of the next word.  Word boundaries are the
753              same as those used by forward-word.
754       backward-kill-word (M-Rubout)
755              Kill the word behind point.  Word boundaries  are  the  same  as
756              those used by backward-word.
757       unix-word-rubout (C-w)
758              Kill  the  word behind point, using white space as a word bound‐
759              ary.  The killed text is saved on the kill-ring.
760       unix-filename-rubout
761              Kill the word behind point, using  white  space  and  the  slash
762              character  as  the word boundaries.  The killed text is saved on
763              the kill-ring.
764       delete-horizontal-space (M-\)
765              Delete all spaces and tabs around point.
766       kill-region
767              Kill the text between the point and  mark  (saved  cursor  posi‐
768              tion).  This text is referred to as the region.
769       copy-region-as-kill
770              Copy the text in the region to the kill buffer.
771       copy-backward-word
772              Copy  the word before point to the kill buffer.  The word bound‐
773              aries are the same as backward-word.
774       copy-forward-word
775              Copy the word following point to  the  kill  buffer.   The  word
776              boundaries are the same as forward-word.
777       yank (C-y)
778              Yank the top of the kill ring into the buffer at point.
779       yank-pop (M-y)
780              Rotate  the kill ring, and yank the new top.  Only works follow‐
781              ing yank or yank-pop.
782
783   Numeric Arguments
784       digit-argument (M-0, M-1, ..., M--)
785              Add this digit to the argument already accumulating, or start  a
786              new argument.  M-- starts a negative argument.
787       universal-argument
788              This  is another way to specify an argument.  If this command is
789              followed by one or more digits, optionally with a leading  minus
790              sign,  those digits define the argument.  If the command is fol‐
791              lowed by digits, executing universal-argument again ends the nu‐
792              meric argument, but is otherwise ignored.  As a special case, if
793              this command is immediately followed by a character that is nei‐
794              ther a digit or minus sign, the argument count for the next com‐
795              mand is multiplied by four.  The  argument  count  is  initially
796              one,  so  executing this function the first time makes the argu‐
797              ment count four, a second time makes the argument count sixteen,
798              and so on.
799
800   Completing
801       complete (TAB)
802              Attempt to perform completion on the text before point.  The ac‐
803              tual completion performed is  application-specific.   Bash,  for
804              instance,  attempts  completion  treating the text as a variable
805              (if the text begins with $), username (if the text  begins  with
806              ~),  hostname (if the text begins with @), or command (including
807              aliases and functions) in turn.  If none  of  these  produces  a
808              match,  filename  completion  is  attempted.   Gdb, on the other
809              hand, allows completion of program functions and variables,  and
810              only attempts filename completion under certain circumstances.
811       possible-completions (M-?)
812              List  the  possible  completions of the text before point.  When
813              displaying completions, readline sets the number of columns used
814              for  display to the value of completion-display-width, the value
815              of the environment variable COLUMNS, or  the  screen  width,  in
816              that order.
817       insert-completions (M-*)
818              Insert  all completions of the text before point that would have
819              been generated by possible-completions.
820       menu-complete
821              Similar to complete, but replaces the word to be completed  with
822              a  single match from the list of possible completions.  Repeated
823              execution of menu-complete steps through the  list  of  possible
824              completions,  inserting  each  match in turn.  At the end of the
825              list of completions, the bell is rung (subject to the setting of
826              bell-style) and the original text is restored.  An argument of n
827              moves n positions forward in the list of matches; a negative ar‐
828              gument may be used to move backward through the list.  This com‐
829              mand is intended to be bound to TAB, but is unbound by default.
830       menu-complete-backward
831              Identical to menu-complete, but moves backward through the  list
832              of  possible  completions,  as if menu-complete had been given a
833              negative argument.  This command is unbound by default.
834       delete-char-or-list
835              Deletes the character under the cursor if not at  the  beginning
836              or  end  of  the  line (like delete-char).  If at the end of the
837              line, behaves identically to possible-completions.
838
839   Keyboard Macros
840       start-kbd-macro (C-x ()
841              Begin saving the characters  typed  into  the  current  keyboard
842              macro.
843       end-kbd-macro (C-x ))
844              Stop saving the characters typed into the current keyboard macro
845              and store the definition.
846       call-last-kbd-macro (C-x e)
847              Re-execute the last keyboard macro defined, by making the  char‐
848              acters in the macro appear as if typed at the keyboard.
849       print-last-kbd-macro ()
850              Print  the  last keyboard macro defined in a format suitable for
851              the inputrc file.
852
853   Miscellaneous
854       re-read-init-file (C-x C-r)
855              Read in the contents of the inputrc file,  and  incorporate  any
856              bindings or variable assignments found there.
857       abort (C-g)
858              Abort  the  current editing command and ring the terminal's bell
859              (subject to the setting of bell-style).
860       do-lowercase-version (M-A, M-B, M-x, ...)
861              If the metafied character x is uppercase, run the  command  that
862              is bound to the corresponding metafied lowercase character.  The
863              behavior is undefined if x is already lowercase.
864       prefix-meta (ESC)
865              Metafy the next character typed.  ESC f is equivalent to Meta-f.
866       undo (C-_, C-x C-u)
867              Incremental undo, separately remembered for each line.
868       revert-line (M-r)
869              Undo all changes made to this line.  This is like executing  the
870              undo  command  enough  times  to  return the line to its initial
871              state.
872       tilde-expand (M-&)
873              Perform tilde expansion on the current word.
874       set-mark (C-@, M-<space>)
875              Set the mark to the point.  If a numeric argument  is  supplied,
876              the mark is set to that position.
877       exchange-point-and-mark (C-x C-x)
878              Swap  the  point  with the mark.  The current cursor position is
879              set to the saved position, and the old cursor position is  saved
880              as the mark.
881       character-search (C-])
882              A character is read and point is moved to the next occurrence of
883              that character.  A negative argument searches for  previous  oc‐
884              currences.
885       character-search-backward (M-C-])
886              A  character  is  read and point is moved to the previous occur‐
887              rence of that character.  A negative argument searches for  sub‐
888              sequent occurrences.
889       skip-csi-sequence
890              Read  enough  characters to consume a multi-key sequence such as
891              those defined for keys like Home and End.  Such sequences  begin
892              with a Control Sequence Indicator (CSI), usually ESC-[.  If this
893              sequence is bound to "\[", keys producing  such  sequences  will
894              have  no  effect  unless explicitly bound to a readline command,
895              instead of inserting stray characters into the  editing  buffer.
896              This is unbound by default, but usually bound to ESC-[.
897       insert-comment (M-#)
898              Without  a  numeric  argument,  the  value  of the readline com‐
899              ment-begin variable is inserted at the beginning of the  current
900              line.  If a numeric argument is supplied, this command acts as a
901              toggle: if the characters at the beginning of the  line  do  not
902              match  the value of comment-begin, the value is inserted, other‐
903              wise the characters in comment-begin are deleted from the begin‐
904              ning  of the line.  In either case, the line is accepted as if a
905              newline had been typed.   The  default  value  of  comment-begin
906              makes  the  current line a shell comment.  If a numeric argument
907              causes the comment character to be removed, the line will be ex‐
908              ecuted by the shell.
909       dump-functions
910              Print  all  of the functions and their key bindings to the read‐
911              line output stream.  If a numeric argument is supplied, the out‐
912              put  is  formatted  in such a way that it can be made part of an
913              inputrc file.
914       dump-variables
915              Print all of the settable variables  and  their  values  to  the
916              readline  output stream.  If a numeric argument is supplied, the
917              output is formatted in such a way that it can be made part of an
918              inputrc file.
919       dump-macros
920              Print  all of the readline key sequences bound to macros and the
921              strings they output.  If a numeric  argument  is  supplied,  the
922              output is formatted in such a way that it can be made part of an
923              inputrc file.
924       emacs-editing-mode (C-e)
925              When in vi command mode, this causes a switch to  emacs  editing
926              mode.
927       vi-editing-mode (M-C-j)
928              When  in  emacs editing mode, this causes a switch to vi editing
929              mode.
930

DEFAULT KEY BINDINGS

932       The following is a list of the default emacs and vi bindings.   Charac‐
933       ters  with the eighth bit set are written as M-<character>, and are re‐
934       ferred to as metafied characters.  The printable ASCII  characters  not
935       mentioned  in  the  list  of  emacs  standard bindings are bound to the
936       self-insert function, which just inserts the given character  into  the
937       input line.  In vi insertion mode, all characters not specifically men‐
938       tioned are bound to self-insert.  Characters assigned to signal genera‐
939       tion by stty(1) or the terminal driver, such as C-Z or C-C, retain that
940       function.  Upper and lower case metafied characters are  bound  to  the
941       same  function in the emacs mode meta keymap.  The remaining characters
942       are unbound, which causes readline to ring the  bell  (subject  to  the
943       setting of the bell-style variable).
944
945   Emacs Mode
946             Emacs Standard bindings
947
948             "C-@"  set-mark
949             "C-A"  beginning-of-line
950             "C-B"  backward-char
951             "C-D"  delete-char
952             "C-E"  end-of-line
953             "C-F"  forward-char
954             "C-G"  abort
955             "C-H"  backward-delete-char
956             "C-I"  complete
957             "C-J"  accept-line
958             "C-K"  kill-line
959             "C-L"  clear-screen
960             "C-M"  accept-line
961             "C-N"  next-history
962             "C-P"  previous-history
963             "C-Q"  quoted-insert
964             "C-R"  reverse-search-history
965             "C-S"  forward-search-history
966             "C-T"  transpose-chars
967             "C-U"  unix-line-discard
968             "C-V"  quoted-insert
969             "C-W"  unix-word-rubout
970             "C-Y"  yank
971             "C-]"  character-search
972             "C-_"  undo
973             " " to "/"  self-insert
974             "0"  to "9"  self-insert
975             ":"  to "~"  self-insert
976             "C-?"  backward-delete-char
977
978             Emacs Meta bindings
979
980             "M-C-G"  abort
981             "M-C-H"  backward-kill-word
982             "M-C-I"  tab-insert
983             "M-C-J"  vi-editing-mode
984             "M-C-L"  clear-display
985             "M-C-M"  vi-editing-mode
986             "M-C-R"  revert-line
987             "M-C-Y"  yank-nth-arg
988             "M-C-["  complete
989             "M-C-]"  character-search-backward
990             "M-space"  set-mark
991             "M-#"  insert-comment
992             "M-&"  tilde-expand
993             "M-*"  insert-completions
994             "M--"  digit-argument
995             "M-."  yank-last-arg
996             "M-0"  digit-argument
997             "M-1"  digit-argument
998             "M-2"  digit-argument
999             "M-3"  digit-argument
1000             "M-4"  digit-argument
1001             "M-5"  digit-argument
1002             "M-6"  digit-argument
1003             "M-7"  digit-argument
1004             "M-8"  digit-argument
1005             "M-9"  digit-argument
1006             "M-<"  beginning-of-history
1007             "M-="  possible-completions
1008             "M->"  end-of-history
1009             "M-?"  possible-completions
1010             "M-B"  backward-word
1011             "M-C"  capitalize-word
1012             "M-D"  kill-word
1013             "M-F"  forward-word
1014             "M-L"  downcase-word
1015             "M-N"  non-incremental-forward-search-history
1016             "M-P"  non-incremental-reverse-search-history
1017             "M-R"  revert-line
1018             "M-T"  transpose-words
1019             "M-U"  upcase-word
1020             "M-Y"  yank-pop
1021             "M-\"  delete-horizontal-space
1022             "M-~"  tilde-expand
1023             "M-C-?"  backward-kill-word
1024             "M-_"  yank-last-arg
1025
1026             Emacs Control-X bindings
1027
1028             "C-XC-G"  abort
1029             "C-XC-R"  re-read-init-file
1030             "C-XC-U"  undo
1031             "C-XC-X"  exchange-point-and-mark
1032             "C-X("  start-kbd-macro
1033             "C-X)"  end-kbd-macro
1034             "C-XE"  call-last-kbd-macro
1035             "C-XC-?"  backward-kill-line
1036
1037
1038   VI Mode bindings
1039             VI Insert Mode functions
1040
1041             "C-D"  vi-eof-maybe
1042             "C-H"  backward-delete-char
1043             "C-I"  complete
1044             "C-J"  accept-line
1045             "C-M"  accept-line
1046             "C-R"  reverse-search-history
1047             "C-S"  forward-search-history
1048             "C-T"  transpose-chars
1049             "C-U"  unix-line-discard
1050             "C-V"  quoted-insert
1051             "C-W"  unix-word-rubout
1052             "C-Y"  yank
1053             "C-["  vi-movement-mode
1054             "C-_"  undo
1055             " " to "~"  self-insert
1056             "C-?"  backward-delete-char
1057
1058             VI Command Mode functions
1059
1060             "C-D"  vi-eof-maybe
1061             "C-E"  emacs-editing-mode
1062             "C-G"  abort
1063             "C-H"  backward-char
1064             "C-J"  accept-line
1065             "C-K"  kill-line
1066             "C-L"  clear-screen
1067             "C-M"  accept-line
1068             "C-N"  next-history
1069             "C-P"  previous-history
1070             "C-Q"  quoted-insert
1071             "C-R"  reverse-search-history
1072             "C-S"  forward-search-history
1073             "C-T"  transpose-chars
1074             "C-U"  unix-line-discard
1075             "C-V"  quoted-insert
1076             "C-W"  unix-word-rubout
1077             "C-Y"  yank
1078             "C-_"  vi-undo
1079             " "  forward-char
1080             "#"  insert-comment
1081             "$"  end-of-line
1082             "%"  vi-match
1083             "&"  vi-tilde-expand
1084             "*"  vi-complete
1085             "+"  next-history
1086             ","  vi-char-search
1087             "-"  previous-history
1088             "."  vi-redo
1089             "/"  vi-search
1090             "0"  beginning-of-line
1091             "1" to "9"  vi-arg-digit
1092             ";"  vi-char-search
1093             "="  vi-complete
1094             "?"  vi-search
1095             "A"  vi-append-eol
1096             "B"  vi-prev-word
1097             "C"  vi-change-to
1098             "D"  vi-delete-to
1099             "E"  vi-end-word
1100             "F"  vi-char-search
1101             "G"  vi-fetch-history
1102             "I"  vi-insert-beg
1103             "N"  vi-search-again
1104             "P"  vi-put
1105             "R"  vi-replace
1106             "S"  vi-subst
1107             "T"  vi-char-search
1108             "U"  revert-line
1109             "W"  vi-next-word
1110             "X"  backward-delete-char
1111             "Y"  vi-yank-to
1112             "\"  vi-complete
1113             "^"  vi-first-print
1114             "_"  vi-yank-arg
1115             "`"  vi-goto-mark
1116             "a"  vi-append-mode
1117             "b"  vi-prev-word
1118             "c"  vi-change-to
1119             "d"  vi-delete-to
1120             "e"  vi-end-word
1121             "f"  vi-char-search
1122             "h"  backward-char
1123             "i"  vi-insertion-mode
1124             "j"  next-history
1125             "k"  prev-history
1126             "l"  forward-char
1127             "m"  vi-set-mark
1128             "n"  vi-search-again
1129             "p"  vi-put
1130             "r"  vi-change-char
1131             "s"  vi-subst
1132             "t"  vi-char-search
1133             "u"  vi-undo
1134             "w"  vi-next-word
1135             "x"  vi-delete
1136             "y"  vi-yank-to
1137             "|"  vi-column
1138             "~"  vi-change-case
1139

SEE ALSO

1141       The Gnu Readline Library, Brian Fox and Chet Ramey
1142       The Gnu History Library, Brian Fox and Chet Ramey
1143       bash(1)
1144

FILES

1146       ~/.inputrc
1147              Individual readline initialization file
1148

AUTHORS

1150       Brian Fox, Free Software Foundation
1151       bfox@gnu.org
1152
1153       Chet Ramey, Case Western Reserve University
1154       chet.ramey@case.edu
1155

BUG REPORTS

1157       If  you  find  a bug in readline, you should report it.  But first, you
1158       should make sure that it really is a bug, and that it  appears  in  the
1159       latest version of the readline library that you have.
1160
1161       Once  you have determined that a bug actually exists, mail a bug report
1162       to bug-readline@gnu.org.  If you have a fix, you are  welcome  to  mail
1163       that  as  well!   Suggestions  and  `philosophical'  bug reports may be
1164       mailed to  bug-readline@gnu.org  or  posted  to  the  Usenet  newsgroup
1165       gnu.bash.bug.
1166
1167       Comments and bug reports concerning this manual page should be directed
1168       to chet.ramey@case.edu.
1169

BUGS

1171       It's too big and too slow.
1172
1173
1174
1175GNU Readline 8.2               2022 September 19                   READLINE(3)
Impressum