documentation/readline.txt

   1
   2
   3
   4 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
   5
   6
   7
   8 NAME
   9      readline - get a line from a user with editing
  10
  11 SYNOPSIS
  12      #include <readline.h>
  13      #include <history.h>
  14
  15      typedef int Function ();
  16
  17      char *readline (prompt)
  18      char *prompt;
  19
  20      int rl_add_defun (name, function, key)
  21      char *name;
  22      Function *function;
  23      int key;
  24
  25      int rl_bind_key (key, function)
  26      int key;
  27      Function *function;
  28
  29      int rl_unbind_key (key)
  30      int key;
  31
  32      int rl_bind_key_in_map (key, function, keymap)
  33      int key;
  34      Function *function;
  35      Keymap keymap;
  36
  37      int rl_unbind_key_in_map (key, keymap)
  38      int key;
  39      Keymap keymap;
  40
  41      int rl_macro_bind (keyseq, macro, keymap)
  42      char *keyseq, *macro;
  43      Keymap keymap;
  44
  45      int rl_variable_bind (variable, value)
  46      char *variable, *value;
  47
  48      int rl_parse_and_bind (line)
  49      char *line;
  50
  51      int rl_translate_keyseq (keyseq, array, len)
  52      char *keyseq, *array;
  53      int *len;
  54
  55      Function *rl_named_function (command)
  56      char *command;
  57
  58      Function *rl_function_of_keyseq (keyseq, keymap, type)
  59      char *keyseq;
  60
  61
  62
  63 GNU                 Last change: 1994 July 26                   1
  64
  65
  66
  67
  68
  69
  70 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
  71
  72
  73
  74      Keymap keymap;
  75      int *type;
  76
  77      char **rl_invoking_keyseqs (function)
  78      Function *function;
  79
  80      char **rl_invoking_keyseqs_in_map (function, keymap)
  81      Function *function;
  82      Keymap keymap;
  83
  84      void rl_function_dumper (readable)
  85      int readable;
  86
  87      char **rl_funmap_names ()
  88
  89 COPYRIGHT
  90      Readline is Copyright (C) 1989, 1991 by  the  Free  Software
  91      Foundation, Inc.
  92
  93 DESCRIPTION
  94      readline will read a line from the terminal and  return  it,
  95      using  prompt  as a prompt.  If prompt is null, no prompt is
  96      issued.  The line returned is allocated with  _\bm_\ba_\bl_\bl_\bo_\bc(3),  so
  97      the  caller  must  free it when finished.  The line returned
  98      has the final newline removed, so only the text of the  line
  99      remains.
 100
 101      readline offers  editing  capabilities  while  the  user  is
 102      entering  the  line.   By default, the line editing commands
 103      are similar to those of  emacs.   A  vi-style  line  editing
 104      interface is also available.
 105
 106      In  the  following  descriptions,  keymap  can  be  one   of
 107      _\be_\bm_\ba_\bc_\bs__\bk_\be_\by_\bm_\ba_\bp,      _\be_\bm_\ba_\bc_\bs__\bm_\be_\bt_\ba__\bk_\be_\by_\bm_\ba_\bp,     _\be_\bm_\ba_\bc_\bs__\bc_\bt_\bl_\bx__\bk_\be_\by_\bm_\ba_\bp,
 108      _\bv_\bi__\bi_\bn_\bs_\be_\br_\bt_\bi_\bo_\bn__\bk_\be_\by_\bm_\ba_\bp, _\bo_\br _\bv_\bi__\bm_\bo_\bv_\be_\bm_\be_\bn_\bt__\bk_\be_\by_\bm_\ba_\bp.
 109
 110      rl_add_defun makes name appear as a bindable  readline  com-
 111      mand,  and  makes  function be the function called when that
 112      command is invoked.  If key is not -1, it is bound to  func-
 113      tion in the current keymap.
 114
 115      rl_bind_key causes key to invoke function.  The  binding  is
 116      made in the current keymap.
 117
 118      rl_unbind_key removes the binding for  key  in  the  current
 119      keymap.
 120
 121      rl_bind_key_in_map makes the  key  entry  in  keymap  invoke
 122      function.
 123
 124      rl_unbind_key_in_map removes the binding for key  in  keymap
 125      keymap.
 126
 127
 128
 129 GNU                 Last change: 1994 July 26                   2
 130
 131
 132
 133
 134
 135
 136 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 137
 138
 139
 140      rl_macro_bind makes keyseq insert  the  string  macro.   The
 141      binding is performed in keymap.
 142
 143      rl_variable_bind sets the value  of  the  readline  variable
 144      variable to value.
 145
 146      rl_parse_and_bind takes as an argument a line  of  the  same
 147      form  as  the readline startup file (see INITIALIZATION FILE
 148      below) and executes the commands therein.
 149
 150      rl_translate_keyseq converts keyseq into a new string, stor-
 151      ing  the  result in array.  This translates control and meta
 152      prefixes and the readline character  escape  sequences  (see
 153      Key  Bindings below).  The length of the translated sequence
 154      is returned in *len.
 155
 156      rl_named_function returns the function that is executed when
 157      the readline command command is invoked.
 158
 159      rl_function_of_keyseq returns the function that is  executed
 160      when  keyseq is read and keymap is the current keymap.  type
 161      is set to indicate whether the return value corresponds to a
 162      function, macro, or auxiliary keymap.
 163
 164      rl_invoking_keyseqs returns all of the key sequences in  the
 165      current keymap that invoke function.
 166
 167      rl_invoking_keyseqs_in_map returns all of the key  sequences
 168      in keymap that invoke function.
 169
 170      rl_function_dumper prints all of the readline functions  and
 171      their  bindings  to the readline output stream.  If readable
 172      is non-zero, the output is formattted so that it can be read
 173      back in to restore the bindings.
 174
 175      rl_funmap_names returns an array of all known readline bind-
 176      able function names.  The array is sorted.
 177
 178 RETURN VALUE
 179      readline returns the text of the line read.   A  blank  line
 180      returns the empty string.  If EOF is encountered while read-
 181      ing a line, and the line is empty, NULL is returned.  If  an
 182      EOF  is  read with a non-empty line, it is treated as a new-
 183      line.
 184
 185      Unless otherwise stated, the other  functions  return  0  on
 186      success and non-zero on failure.
 187
 188 NOTATION
 189      An emacs-style notation is used to denote keystrokes.   Con-
 190      trol  keys  are denoted by C-_\bk_\be_\by, e.g., C-n means Control-N.
 191      Similarly, _\bm_\be_\bt_\ba keys are denoted  by  M-_\bk_\be_\by,  so  M-x  means
 192
 193
 194
 195 GNU                 Last change: 1994 July 26                   3
 196
 197
 198
 199
 200
 201
 202 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 203
 204
 205
 206      Meta-X.   (On keyboards without a _\bm_\be_\bt_\ba key, M-_\bx means ESC _\bx,
 207      i.e., press the Escape key then the _\bx key.  This  makes  ESC
 208      the _\bm_\be_\bt_\ba _\bp_\br_\be_\bf_\bi_\bx.  The combination M-C-_\bx means ESC-Control-_\bx,
 209      or press the Escape key then  hold  the  Control  key  while
 210      pressing the _\bx key.)
 211
 212      Readline commands may be given numeric _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs, which nor-
 213      mally  act as a repeat count.  Sometimes, however, it is the
 214      sign of the argument that is significant.  Passing  a  nega-
 215      tive  argument  to a command that acts in the forward direc-
 216      tion (e.g., kill-line) causes that command to act in a back-
 217      ward  direction.   Commands  whose  behavior  with arguments
 218      deviates from this are noted.
 219
 220      When a command  is  described  as  _\bk_\bi_\bl_\bl_\bi_\bn_\bg  text,  the  text
 221      deleted  is  saved  for possible future retrieval (_\by_\ba_\bn_\bk_\bi_\bn_\bg).
 222      The killed text is saved in a _\bk_\bi_\bl_\bl-_\br_\bi_\bn_\bg.  Consecutive  kills
 223      cause the text to be accumulated into one unit, which can be
 224      yanked all at once. Commands which do not kill text separate
 225      the chunks of text on the kill-ring.
 226
 227 INITIALIZATION FILE
 228      Readline is customized by putting commands in an initializa-
 229      tion file.  The name of this file is taken from the value of
 230      the INPUTRC  variable.   If  that  variable  is  unset,  the
 231      default  is ~/._\bi_\bn_\bp_\bu_\bt_\br_\bc.  When a program which uses the read-
 232      line library starts up, the init file is read, and  the  key
 233      bindings  and variables are set.  There are only a few basic
 234      constructs allowed in the readline init file.   Blank  lines
 235      are  ignored.  Lines beginning with a # are comments.  Lines
 236      beginning with a $ indicate conditional  constructs.   Other
 237      lines  denote key bindings and variable settings.  Each pro-
 238      gram using this library may add its own commands  and  bind-
 239      ings.
 240
 241      For example, placing
 242
 243           M-Control-u: universal-argument
 244      or
 245           C-Meta-u: universal-argument
 246      into the ~/._\bi_\bn_\bp_\bu_\bt_\br_\bc would make M-C-u  execute  the  readline
 247      command _\bu_\bn_\bi_\bv_\be_\br_\bs_\ba_\bl-_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt.
 248
 249      The following symbolic character names are recognized  while
 250      processing  key  bindings:  _\bR_\bU_\bB_\bO_\bU_\bT,  _\bD_\bE_\bL, _\bE_\bS_\bC, _\bL_\bF_\bD, _\bN_\bE_\bW_\bL_\bI_\bN_\bE,
 251      _\bR_\bE_\bT, _\bR_\bE_\bT_\bU_\bR_\bN, _\bS_\bP_\bC, _\bS_\bP_\bA_\bC_\bE, and _\bT_\bA_\bB.  In  addition  to  command
 252      names,  readline allows keys to be bound to a string that is
 253      inserted when the key is pressed (a _\bm_\ba_\bc_\br_\bo).
 254
 255   Key Bindings
 256      The syntax for controlling key bindings  in  the  ~/._\bi_\bn_\bp_\bu_\bt_\br_\bc
 257      file  is  simple.   All  that is required is the name of the
 258
 259
 260
 261 GNU                 Last change: 1994 July 26                   4
 262
 263
 264
 265
 266
 267
 268 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 269
 270
 271
 272      command or the text of a macro and a key sequence  to  which
 273      it  should be bound. The name may be specified in one of two
 274      ways: as a symbolic key name, possibly with  _\bM_\be_\bt_\ba-  or  _\bC_\bo_\bn_\b-
 275      _\bt_\br_\bo_\bl-  prefixes,  or as a key sequence.  When using the form
 276      keyname:_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn-_\bn_\ba_\bm_\be or _\bm_\ba_\bc_\br_\bo, _\bk_\be_\by_\bn_\ba_\bm_\be is the name of a key
 277      spelled out in English.  For example:
 278
 279           Control-u: universal-argument
 280           Meta-Rubout: backward-kill-word
 281           Control-o: ">&output"
 282
 283      In  the  above  example,  _\bC-_\bu  is  bound  to  the   function
 284      universal-argument,   _\bM-_\bD_\bE_\bL   is   bound   to  the  function
 285      backward-kill-word, and  _\bC-_\bo  is  bound  to  run  the  macro
 286      expressed  on  the  right  hand side (that is, to insert the
 287      text >&_\bo_\bu_\bt_\bp_\bu_\bt into the line).
 288
 289      In the second form, "keyseq":_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn-_\bn_\ba_\bm_\be or _\bm_\ba_\bc_\br_\bo,  keyseq
 290      differs  from  keyname  above  in  that  strings denoting an
 291      entire key sequence may be specified by placing the sequence
 292      within  double quotes.  Some GNU Emacs style key escapes can
 293      be used, as in the following example.
 294
 295           "\C-u": universal-argument
 296           "\C-x\C-r": re-read-init-file
 297           "\e[11~": "Function Key 1"
 298
 299      In  this  example,  _\bC-_\bu  is  again  bound  to  the  function
 300      universal-argument.   _\bC-_\bx  _\bC-_\br  is  bound  to  the  function
 301      re-read-init-file, and _\bE_\bS_\bC [ _\b1 _\b1 ~ is bound  to  insert  the
 302      text Function Key 1.  The full set of escape sequences is
 303
 304           \C-  control prefix
 305
 306           \M-  meta prefix
 307
 308           \e   an escape character
 309
 310           \\   backslash
 311
 312           " \" literal "
 313
 314           \'   literal '
 315
 316      When entering the text of a macro, single or  double  quotes
 317      should  be  used  to  indicate a macro definition.  Unquoted
 318      text is assumed to be a function name.  Backslash will quote
 319      any character in the macro text, including " and '.
 320
 321      Bash  allows  the  current  readline  key  bindings  to   be
 322      displayed  or  modified  with the bind builtin command.  The
 323      editing mode may be switched during interactive use by using
 324
 325
 326
 327 GNU                 Last change: 1994 July 26                   5
 328
 329
 330
 331
 332
 333
 334 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 335
 336
 337
 338      the  -o  option  to the set builtin command.  Other programs
 339      using this library provide similar mechanisms.  The  _\bi_\bn_\bp_\bu_\bt_\br_\bc
 340      file may be edited and re-read if a program does not provide
 341      any other means to incorporate new bindings.
 342
 343   Variables
 344      Readline has variables that can be used to further customize
 345      its  behavior.   A  variable  may be set in the _\bi_\bn_\bp_\bu_\bt_\br_\bc file
 346      with a statement of the form
 347
 348           set _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be-_\bn_\ba_\bm_\be _\bv_\ba_\bl_\bu_\be
 349
 350      Except where noted, readline variables can take  the  values
 351      On or Off.  The variables and their default values are:
 352
 353      horizontal-scroll-mode (Off)
 354           When set to On, makes readline use a  single  line  for
 355           display,  scrolling  the input horizontally on a single
 356           screen line when it  becomes  longer  than  the  screen
 357           width rather than wrapping to a new line.
 358      editing-mode (emacs)
 359           Controls whether readline begins  with  a  set  of  key
 360           bindings  similar  to _\be_\bm_\ba_\bc_\bs or _\bv_\bi.  editing-mode can be
 361           set to either emacs or vi.
 362      mark-modified-lines (Off)
 363           If set to On, history lines that have been modified are
 364           displayed with a preceding asterisk (*).
 365      bell-style (audible)
 366           Controls what happens when readline wants to  ring  the
 367           terminal  bell.   If  set to none, readline never rings
 368           the bell.  If set to visible, readline uses  a  visible
 369           bell  if one is available.  If set to audible, readline
 370           attempts to ring the terminal's bell.
 371      comment-begin (``#'')
 372           The string  that  is  inserted  in  vi  mode  when  the
 373           vi-comment command is executed.
 374      meta-flag (Off)
 375           If set to On,  readline  will  enable  eight-bit  input
 376           (that is, it will not strip the high bit from the char-
 377           acters it  reads),  regardless  of  what  the  terminal
 378           claims it can support.
 379      convert-meta (On)
 380           If set to On, readline will convert characters with the
 381           eighth  bit  set  to an ASCII key sequence by stripping
 382           the eighth bit and prepending an escape  character  (in
 383           effect, using escape as the _\bm_\be_\bt_\ba _\bp_\br_\be_\bf_\bi_\bx).
 384      output-meta (Off)
 385           If set to On, readline will display characters with the
 386           eighth  bit set directly rather than as a meta-prefixed
 387           escape sequence.
 388      completion-query-items (100)
 389           This determines when the user is queried about  viewing
 390
 391
 392
 393 GNU                 Last change: 1994 July 26                   6
 394
 395
 396
 397
 398
 399
 400 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 401
 402
 403
 404           the  number  of  possible  completions generated by the
 405           possible-completions command.  It may  be  set  to  any
 406           integer  value  greater  than or equal to zero.  If the
 407           number of possible completions is greater than or equal
 408           to  the  value  of  this  variable,  the  user is asked
 409           whether or not he wishes to view them;  otherwise  they
 410           are simply listed on the terminal.
 411      keymap (emacs)
 412           Set the current readline keymap.  The set of legal key-
 413           map  names is _\be_\bm_\ba_\bc_\bs, _\be_\bm_\ba_\bc_\bs-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd, _\be_\bm_\ba_\bc_\bs-_\bm_\be_\bt_\ba, _\be_\bm_\ba_\bc_\bs-
 414           _\bc_\bt_\bl_\bx, _\bv_\bi, _\bv_\bi-_\bm_\bo_\bv_\be, _\bv_\bi-_\bc_\bo_\bm_\bm_\ba_\bn_\bd, and  _\bv_\bi-_\bi_\bn_\bs_\be_\br_\bt.   _\bv_\bi  is
 415           equivalent   to  _\bv_\bi-_\bc_\bo_\bm_\bm_\ba_\bn_\bd;  _\be_\bm_\ba_\bc_\bs  is  equivalent  to
 416           _\be_\bm_\ba_\bc_\bs-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd.  The default value is _\be_\bm_\ba_\bc_\bs; the  value
 417           of editing-mode also affects the default keymap.
 418      show-all-if-ambiguous (Off)
 419           This alters the  default  behavior  of  the  completion
 420           functions.   If  set  to on, words which have more than
 421           one possible completion cause the matches to be  listed
 422           immediately instead of ringing the bell.
 423      expand-tilde (Off)
 424           If set to on, tilde expansion is performed  when  read-
 425           line attempts word completion.
 426
 427   Conditional Constructs
 428      Readline implements a facility similar in spirit to the con-
 429      ditional  compilation  features  of the C preprocessor which
 430      allows key bindings and variable settings to be performed as
 431      the  result  of  tests.   There  are three parser directives
 432      used.
 433
 434      $if  The $if construct allows bindings to be made  based  on
 435           the  editing  mode,  the  terminal  being  used, or the
 436           application using  readline.   The  text  of  the  test
 437           extends  to  the  end  of  the  line; no characters are
 438           required to isolate it.
 439
 440           mode The mode= form of the $if  directive  is  used  to
 441                test  whether  readline  is  in  emacs or vi mode.
 442                This may be used in conjunction with the set  key-
 443                map  command, for instance, to set bindings in the
 444                _\be_\bm_\ba_\bc_\bs-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd  and  _\be_\bm_\ba_\bc_\bs-_\bc_\bt_\bl_\bx  keymaps  only  if
 445                readline is starting out in emacs mode.
 446
 447           term The term= form may be used  to  include  terminal-
 448                specific  key  bindings,  perhaps  to bind the key
 449                sequences output by the terminal's function  keys.
 450                The  word  on  the  right  side of the = is tested
 451                against the full name of the terminal and the por-
 452                tion  of  the  terminal  name  before the first -.
 453                This allows _\bs_\bu_\bn to match both _\bs_\bu_\bn and _\bs_\bu_\bn-_\bc_\bm_\bd, for
 454                instance.
 455
 456
 457
 458
 459 GNU                 Last change: 1994 July 26                   7
 460
 461
 462
 463
 464
 465
 466 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 467
 468
 469
 470           application
 471                The  application  construct  is  used  to  include
 472                application-specific settings.  Each program using
 473                the readline library sets  the  _\ba_\bp_\bp_\bl_\bi_\bc_\ba_\bt_\bi_\bo_\bn  _\bn_\ba_\bm_\be,
 474                and an initialization file can test for a particu-
 475                lar  value.   This  could  be  used  to  bind  key
 476                sequences  to functions useful for a specific pro-
 477                gram.  For instance, the following command adds  a
 478                key  sequence  that quotes the current or previous
 479                word in Bash:
 480                $if bash
 481                # Quote the current or previous word
 482                "\C-xq": "\eb\"\ef\""
 483                $endif
 484
 485      $endif
 486           This command, as you saw in the previous example,  ter-
 487           minates an $if command.
 488
 489      $else
 490           Commands in this branch of the $if directive  are  exe-
 491           cuted if the test fails.
 492
 493 EDITING COMMANDS
 494      The following is a list of the names of the commands and the
 495      default key sequences to which they are bound.
 496
 497   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
 508           composed   of   alphanumeric  characters  (letters  and
 509           digits).
 510      backward-word (M-b)
 511           Move back to the start of this, or the previous,  word.
 512           Words  are composed of alphanumeric characters (letters
 513           and digits).
 514      clear-screen (C-l)
 515           Clear the screen leaving the current line at the top of
 516           the screen.  With an argument, refresh the current line
 517           without clearing the screen.
 518      redraw-current-line
 519           Refresh the current line.  By default, this is unbound.
 520
 521
 522
 523
 524
 525 GNU                 Last change: 1994 July 26                   8
 526
 527
 528
 529
 530
 531
 532 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 533
 534
 535
 536   Commands for Manipulating the History
 537      accept-line (Newline, Return)
 538           Accept the line regardless of where the cursor is.   If
 539           this  line is non-empty, add it to the history list. If
 540           the line is a modified history line, then  restore  the
 541           history line to its original state.
 542      previous-history (C-p)
 543           Fetch the previous command from the history list,  mov-
 544           ing back in the list.
 545      next-history (C-n)
 546           Fetch the next command from the  history  list,  moving
 547           forward in the list.
 548      beginning-of-history (M-<)
 549           Move to the first line in the history.
 550      end-of-history (M->)
 551           Move to the end of the input history,  i.e.,  the  line
 552           currently being entered.
 553      reverse-search-history (C-r)
 554           Search backward starting at the current line and moving
 555           `up'  through  the  history  as  necessary.  This is an
 556           incremental search.
 557      forward-search-history (C-s)
 558           Search forward starting at the current line and  moving
 559           `down'  through  the  history as necessary.  This is an
 560           incremental search.
 561      non-incremental-reverse-search-history (M-p)
 562           Search backward through the  history  starting  at  the
 563           current  line  using  a  non-incremental  search  for a
 564           string supplied by the user.
 565      non-incremental-forward-search-history (M-n)
 566           Search   forward   through   the   history   using    a
 567           non-incremental  search  for  a  string supplied by the
 568           user.
 569      history-search-forward
 570           Search forward through the history for  the  string  of
 571           characters  between  the  start of the current line and
 572           the current point.  This is a  non-incremental  search.
 573           By default, this command is unbound.
 574      history-search-backward
 575           Search backward through the history for the  string  of
 576           characters  between  the  start of the current line and
 577           the current point.  This is a  non-incremental  search.
 578           By default, this command is unbound.
 579      yank-nth-arg (M-C-y)
 580           Insert the first argument to the previous command (usu-
 581           ally  the  second  word  on the previous line) at point
 582           (the current cursor position).   With  an  argument  _\bn,
 583           insert  the  _\bnth  word  from  the previous command (the
 584           words in the previous command begin with  word  0).   A
 585           negative  argument inserts the _\bnth word from the end of
 586           the previous command.
 587      yank-last-arg (M-., M-_)
 588
 589
 590
 591 GNU                 Last change: 1994 July 26                   9
 592
 593
 594
 595
 596
 597
 598 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 599
 600
 601
 602           Insert the last argument to the previous  command  (the
 603           last  word  on  the  previous line).  With an argument,
 604           behave exactly like yank-nth-arg.
 605
 606   Commands for Changing Text
 607      delete-char (C-d)
 608           Delete the character under the cursor.  If point is  at
 609           the  beginning  of the line, there are no characters in
 610           the line, and the last character  typed  was  not  C-d,
 611           then return EOF.
 612      backward-delete-char (Rubout)
 613           Delete the character behind the cursor.  When  given  a
 614           numeric   argument,   save  the  deleted  text  on  the
 615           kill-ring.
 616      quoted-insert (C-q, C-v)
 617           Add the next character that you type to the line verba-
 618           tim.   This  is  how to insert characters like C-q, for
 619           example.
 620      tab-insert (M-TAB)
 621           Insert a tab character.
 622      self-insert (a, b, A, 1, !, ...)
 623           Insert the character typed.
 624      transpose-chars (C-t)
 625           Drag the character before point forward over the  char-
 626           acter at point.  Point moves forward as well.  If point
 627           is at the end of the line, then transpose the two char-
 628           acters before point.  Negative arguments don't work.
 629      transpose-words (M-t)
 630           Drag the word behind the cursor past the word in  front
 631           of the cursor moving the cursor over that word as well.
 632      upcase-word (M-u)
 633           Uppercase the current  (or  following)  word.   With  a
 634           negative  argument,  do  the  previous word, but do not
 635           move point.
 636      downcase-word (M-l)
 637           Lowercase the current  (or  following)  word.   With  a
 638           negative  argument,  do  the  previous word, but do not
 639           move point.
 640      capitalize-word (M-c)
 641           Capitalize the current (or  following)  word.   With  a
 642           negative  argument,  do  the  previous word, but do not
 643           move point.
 644
 645   Killing and Yanking
 646      kill-line (C-k)
 647           Kill the text from the current cursor position  to  the
 648           end of the line.
 649      backward-kill-line (C-x Rubout)
 650           Kill backward to the beginning of the line.
 651      unix-line-discard (C-u)
 652           Kill backward from point to the beginning of the line.
 653      kill-whole-line
 654
 655
 656
 657 GNU                 Last change: 1994 July 26                  10
 658
 659
 660
 661
 662
 663
 664 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 665
 666
 667
 668           Kill all characters on  the  current  line,  no  matter
 669           where the cursor is.  By default, this is unbound.
 670      kill-word (M-d)
 671           Kill from the cursor to the end of the current word, or
 672           if  between  words,  to the end of the next word.  Word
 673           boundaries are the same as those used by forward-word.
 674      backward-kill-word (M-Rubout)
 675           Kill the word behind the cursor.  Word  boundaries  are
 676           the same as those used by backward-word.
 677      unix-word-rubout (C-w)
 678           Kill the word behind the cursor, using white space as a
 679           word  boundary.  The word boundaries are different from
 680           backward-kill-word.
 681      delete-horizontal-space
 682           Delete all spaces and tabs around point.   By  default,
 683           this is unbound.
 684      yank (C-y)
 685           Yank the top of the kill ring into the  buffer  at  the
 686           cursor.
 687      yank-pop (M-y)
 688           Rotate the kill-ring, and yank the new top.  Only works
 689           following yank or yank-pop.
 690
 691   Numeric Arguments
 692      digit-argument (M-0, M-1, ..., M--)
 693           Add this digit to the argument already accumulating, or
 694           start a new argument.  M-- starts a negative argument.
 695      universal-argument
 696           Each time this is executed, the argument count is  mul-
 697           tiplied  by four.  The argument count is initially one,
 698           so executing this function the  first  time  makes  the
 699           argument  count four.  By default, this is not bound to
 700           a key.
 701
 702   Completing
 703      complete (TAB)
 704           Attempt to perform completion on the text before point.
 705           The   actual   completion   performed  is  application-
 706           specific.   Bash,  for  instance,  attempts  completion
 707           treating  the  text  as  a variable (if the text begins
 708           with $), username (if the text begins with ~), hostname
 709           (if  the  text  begins  with  @), or command (including
 710           aliases and functions) in turn.  If none of these  pro-
 711           duces  a match, filename completion is attempted.  Gdb,
 712           on the other hand, allows completion of  program  func-
 713           tions and variables, and only attempts filename comple-
 714           tion under certain circumstances.
 715      possible-completions (M-?)
 716           List the possible completions of the text before point.
 717      insert-completions
 718           Insert all completions of the text  before  point  that
 719           would  have been generated by possible-completions.  By
 720
 721
 722
 723 GNU                 Last change: 1994 July 26                  11
 724
 725
 726
 727
 728
 729
 730 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 731
 732
 733
 734           default, this is not bound to a key.
 735
 736   Keyboard Macros
 737      start-kbd-macro (C-x ()
 738           Begin saving the characters typed into the current key-
 739           board macro.
 740      end-kbd-macro (C-x ))
 741           Stop saving the characters typed into the current  key-
 742           board macro and save the definition.
 743      call-last-kbd-macro (C-x e)
 744           Re-execute the last keyboard macro defined,  by  making
 745           the  characters  in the macro appear as if typed at the
 746           keyboard.
 747
 748   Miscellaneous
 749      re-read-init-file (C-x C-r)
 750           Read in the contents of your init file, and incorporate
 751           any bindings or variable assignments found there.
 752      abort (C-g)
 753           Abort  the  current  editing  command  and   ring   the
 754           terminal's bell (subject to the setting of bell-style).
 755      do-uppercase-version (M-a, M-b, ...)
 756           Run the command that  is  bound  to  the  corresponding
 757           uppercase character.
 758      prefix-meta (ESC)
 759           Metafy the next character typed.  ESC f  is  equivalent
 760           to Meta-f.
 761      undo (C-_, C-x C-u)
 762           Incremental undo, separately remembered for each line.
 763      revert-line (M-r)
 764           Undo all changes made to this line.  This is like  typ-
 765           ing the undo command enough times to return the line to
 766           its initial state.
 767      tilde-expand (M-~)
 768           Perform tilde expansion on the current word.
 769      dump-functions
 770           Print all of the functions and their  key  bindings  to
 771           the  readline  output stream.  If a numeric argument is
 772           supplied, the output is formatted in such a way that it
 773           can be made part of an _\bi_\bn_\bp_\bu_\bt_\br_\bc file.
 774      emacs-editing-mode (C-e)
 775           When in vi editing mode, this causes a switch to  emacs
 776           editing mode.
 777      vi-editing-mode (M-C-j)
 778           When in emacs editing mode, this causes a switch to  vi
 779           editing mode.
 780
 781 DEFAULT KEY BINDINGS
 782      The following is a list of the default emacs  and  vi  bind-
 783      ings.   Characters  with  the  8th bit set are written as M-
 784      <character>, and are referred  to  as  _\bm_\be_\bt_\ba_\bf_\bi_\be_\bd  characters.
 785      The  printable ASCII characters not mentioned in the list of
 786
 787
 788
 789 GNU                 Last change: 1994 July 26                  12
 790
 791
 792
 793
 794
 795
 796 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 797
 798
 799
 800      emacs standard bindings are bound to the  _\bs_\be_\bl_\bf-_\bi_\bn_\bs_\be_\br_\bt  func-
 801      tion,  which just inserts the given character into the input
 802      line.  In vi insertion mode, all characters not specifically
 803      mentioned  are bound to _\bs_\be_\bl_\bf-_\bi_\bn_\bs_\be_\br_\bt.  Characters assigned to
 804      signal generation by _\bs_\bt_\bt_\by(1) or the terminal driver, such as
 805      C-Z  or  C-C,  retain  that  function.  Upper and lower case
 806      _\bm_\be_\bt_\ba_\bf_\bi_\be_\bd characters are bound to the same  function  in  the
 807      emacs  mode  meta  keymap.   The  remaining  characters  are
 808      unbound, which causes readline to ring the bell (subject  to
 809      the setting of the bell-style variable).
 810
 811   Emacs Mode
 812            Emacs Standard bindings
 813
 814            "C-A"                    ->  beginning-of-line
 815            "C-B"                    ->  backward-char
 816            "C-D"                    ->  delete-char
 817            "C-E"                    ->  end-of-line
 818            "C-F"                    ->  forward-char
 819            "C-G"                    ->  abort
 820            "C-H"                    ->  backward-delete-char
 821            "C-I"                    ->  complete
 822            "C-J"                    ->  accept-line
 823            "C-K"                    ->  kill-line
 824            "C-L"                    ->  clear-screen
 825            "C-M"                    ->  accept-line
 826            "C-N"                    ->  next-history
 827            "C-P"                    ->  previous-history
 828            "C-Q"                    ->  quoted-insert
 829            "C-R"                    ->  reverse-search-history
 830            "C-S"                    ->  forward-search-history
 831            "C-T"                    ->  transpose-chars
 832            "C-U"                    ->  unix-line-discard
 833            "C-V"                    ->  quoted-insert
 834            "C-W"                    ->  unix-word-rubout
 835            "C-Y"                    ->  yank
 836            "C-_"                    ->  undo
 837            " " to "/"               ->  self-insert
 838            "0"  to "9"              ->  self-insert
 839            ":"  to "~"              ->  self-insert
 840            "C-?"                    ->  backward-delete-char
 841
 842            Emacs Meta bindings
 843
 844            "M-C-H"                  ->  backward-kill-word
 845            "M-C-I"                  ->  tab-insert
 846            "M-C-J"                  ->  vi-editing-mode
 847            "M-C-M"                  ->  vi-editing-mode
 848            "M-C-R"                  ->  revert-line
 849            "M-C-Y"                  ->  yank-nth-arg
 850            "M-C-["                  ->  complete
 851            "M-&"                    ->  tilde-expand
 852
 853
 854
 855 GNU                 Last change: 1994 July 26                  13
 856
 857
 858
 859
 860
 861
 862 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 863
 864
 865
 866            "M--"                    ->  digit-argument
 867            "M-0"                    ->  digit-argument
 868            "M-1"                    ->  digit-argument
 869            "M-2"                    ->  digit-argument
 870            "M-3"                    ->  digit-argument
 871            "M-4"                    ->  digit-argument
 872            "M-5"                    ->  digit-argument
 873            "M-6"                    ->  digit-argument
 874            "M-7"                    ->  digit-argument
 875            "M-8"                    ->  digit-argument
 876            "M-9"                    ->  digit-argument
 877            "M-<"                    ->  beginning-of-history
 878            "M->"                    ->  end-of-history
 879            "M-?"                    ->  possible-completions
 880            "M-B"                    ->  backward-word
 881            "M-C"                    ->  capitalize-word
 882            "M-D"                    ->  kill-word
 883            "M-F"                    ->  forward-word
 884            "M-L"                    ->  downcase-word
 885            "M-N"                    ->  non-incremental-forward-search-history
 886            "M-O"                    ->  arrow-key-prefix
 887            "M-P"                    ->  non-incremental-reverse-search-history
 888            "M-R"                    ->  revert-line
 889            "M-T"                    ->  transpose-words
 890            "M-U"                    ->  upcase-word
 891            "M-Y"                    ->  yank-pop
 892            "M-C-Y"                  ->  yank-nth-arg
 893            "M-C-?"                  ->  backward-delete-word
 894
 895            Emacs Control-X bindings
 896
 897            "C-XC-G"                 ->  abort
 898            "C-XC-R"                 ->  re-read-init-file
 899            "C-XC-U"                 ->  undo
 900            "C-X("                   ->  start-kbd-macro
 901            "C-X)"                   ->  end-kbd-macro
 902            "C-Xe"                   ->  call-last-kbd-macro
 903            "C-XC-?"                 ->  backward-kill-line
 904
 905
 906   VI Mode bindings
 907            VI Insert Mode functions
 908
 909            "C-D"                    ->  vi-eof-maybe
 910            "C-H"                    ->  backward-delete-char
 911            "C-I"                    ->  complete
 912            "C-J"                    ->  accept-line
 913            "C-K"                    ->  kill-line
 914            "C-L"                    ->  clear-screen
 915            "C-M"                    ->  accept-line
 916            "C-N"                    ->  next-history
 917            "C-P"                    ->  previous-history
 918
 919
 920
 921 GNU                 Last change: 1994 July 26                  14
 922
 923
 924
 925
 926
 927
 928 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 929
 930
 931
 932            "C-Q"                    ->  quoted-insert
 933            "C-R"                    ->  reverse-search-history
 934            "C-S"                    ->  forward-search-history
 935            "C-T"                    ->  transpose-chars
 936            "C-U"                    ->  unix-line-discard
 937            "C-V"                    ->  quoted-insert
 938            "C-W"                    ->  unix-word-rubout
 939            "C-Y"                    ->  yank
 940            "C-["                    ->  vi-movement-mode
 941            " " to "~"               ->  self-insert
 942            "C-?"                    ->  backward-delete-char
 943
 944            VI Command Mode functions
 945
 946            "C-D"                    ->  vi-eof-maybe
 947            "C-E"                    ->  emacs-editing-mode
 948            "C-G"                    ->  abort
 949            "C-H"                    ->  backward-char
 950            "C-J"                    ->  accept-line
 951            "C-K"                    ->  kill-line
 952            "C-L"                    ->  clear-screen
 953            "C-M"                    ->  accept-line
 954            "C-N"                    ->  next-history
 955            "C-P"                    ->  previous-history
 956            "C-Q"                    ->  quoted-insert
 957            "C-R"                    ->  reverse-search-history
 958            "C-S"                    ->  forward-search-history
 959            "C-T"                    ->  transpose-chars
 960            "C-U"                    ->  unix-line-discard
 961            "C-V"                    ->  quoted-insert
 962            "C-W"                    ->  unix-word-rubout
 963            "C-Y"                    ->  yank
 964            "C-["                    ->  abort
 965            " "                      ->  forward-char
 966            "#"                      ->  vi-comment
 967            "$"                      ->  end-of-line
 968            "%"                      ->  vi-match
 969            "&"                      ->  vi-tilde-expand
 970            "*"                      ->  vi-complete
 971            "+"                      ->  down-history
 972            ","                      ->  vi-char-search
 973            "-"                      ->  previous-history
 974            "."                      ->  vi-redo
 975            "/"                      ->  vi-search
 976            "0"                      ->  beginning-of-line
 977            "1" to "9"               ->  vi-arg-digit
 978            ";"                      ->  vi-char-search
 979            "="                      ->  vi-complete
 980            "?"                      ->  vi-search
 981            "@"                      ->  is undefined
 982            "A"                      ->  vi-append-eol
 983            "B"                      ->  vi-prev-word
 984
 985
 986
 987 GNU                 Last change: 1994 July 26                  15
 988
 989
 990
 991
 992
 993
 994 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
 995
 996
 997
 998            "C"                      ->  vi-change-to
 999            "D"                      ->  vi-delete-to
1000            "E"                      ->  vi-end-word
1001            "F"                      ->  vi-char-search
1002            "I"                      ->  vi-insert-beg
1003            "N"                      ->  vi-search-again
1004            "P"                      ->  vi-put
1005            "R"                      ->  vi-replace
1006            "S"                      ->  vi-subst
1007            "T"                      ->  vi-char-search
1008            "U"                      ->  revert-line
1009            "W"                      ->  vi-next-word
1010            "X"                      ->  backward-delete-char
1011            "Y"                      ->  vi-yank-to
1012            "\"                      ->  vi-complete
1013            "^"                      ->  vi-first-print
1014            "_"                      ->  vi-yank-arg
1015            "a"                      ->  vi-append-mode
1016            "b"                      ->  vi-prev-word
1017            "c"                      ->  vi-change-to
1018            "d"                      ->  vi-delete-to
1019            "e"                      ->  vi-end-word
1020            "f"                      ->  vi-char-search
1021            "h"                      ->  backward-char
1022            "i"                      ->  vi-insertion-mode
1023            "j"                      ->  next-history
1024            "k"                      ->  prev-history
1025            "l"                      ->  forward-char
1026            "n"                      ->  vi-search-again
1027            "r"                      ->  vi-change-char
1028            "s"                      ->  vi-subst
1029            "t"                      ->  vi-char-search
1030            "u"                      ->  undo
1031            "w"                      ->  vi-next-word
1032            "x"                      ->  vi-delete
1033            "y"                      ->  vi-yank-to
1034            "|"                      ->  vi-column
1035            "~"                      ->  vi-change-case
1036
1037 SEE ALSO
1038      _\bT_\bh_\be _\bG_\bn_\bu _\bR_\be_\ba_\bd_\bl_\bi_\bn_\be _\bL_\bi_\bb_\br_\ba_\br_\by, Brian Fox and Chet Ramey
1039      _\bT_\bh_\be _\bG_\bn_\bu _\bH_\bi_\bs_\bt_\bo_\br_\by _\bL_\bi_\bb_\br_\ba_\br_\by, Brian Fox and Chet Ramey
1040      _\bb_\ba_\bs_\bh(1)
1041
1042 FILES
1043      ~/._\bi_\bn_\bp_\bu_\bt_\br_\bc
1044           Individual readline initialization file
1045
1046 AUTHORS
1047           Brian Fox, Free Software Foundation (primary author)
1048           bfox@ai.MIT.Edu
1049
1050
1051
1052
1053 GNU                 Last change: 1994 July 26                  16
1054
1055
1056
1057
1058
1059
1060 READLINE(3)            C LIBRARY FUNCTIONS            READLINE(3)
1061
1062
1063
1064           Chet Ramey, Case Western Reserve University
1065           chet@ins.CWRU.Edu
1066
1067 BUG REPORTS
1068      If you find a bug in readline, you should  report  it.   But
1069      first,  you  should  make  sure that it really is a bug, and
1070      that it appears  in  the  latest  version  of  the  readline
1071      library that you have.
1072
1073      Once you have determined that a bug actually exists, mail  a
1074      bug report to _\bb_\ba_\bs_\bh-_\bm_\ba_\bi_\bn_\bt_\ba_\bi_\bn_\be_\br_\bs@_\bp_\br_\be_\bp._\ba_\bi._\bM_\bI_\bT._\bE_\bd_\bu.  If you have
1075      a fix, you are welcome to mail that  as  well!   Suggestions
1076      and  `philosophical'  bug  reports  may  be  mailed  to _\bb_\bu_\bg-
1077      _\bb_\ba_\bs_\bh@_\bp_\br_\be_\bp._\ba_\bi._\bM_\bI_\bT._\bE_\bd_\bu  or  posted  to  the  Usenet  newsgroup
1078      gnu.bash.bug.
1079
1080      Comments and bug reports concerning this manual page  should
1081      be directed to _\bc_\bh_\be_\bt@_\bi_\bn_\bs._\bC_\bW_\bR_\bU._\bE_\bd_\bu.
1082
1083 BUGS
1084      It's too big and too slow.
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119 GNU                 Last change: 1994 July 26                  17
1120
1121
1122