1This is readline.info, produced by makeinfo version 6.7 from rlman.texi. 2 3This manual describes the GNU Readline Library (version 8.1, 29 October 42020), a library which aids in the consistency of user interface across 5discrete programs which provide a command line interface. 6 7 Copyright (C) 1988-2020 Free Software Foundation, Inc. 8 9 Permission is granted to copy, distribute and/or modify this 10 document under the terms of the GNU Free Documentation License, 11 Version 1.3 or any later version published by the Free Software 12 Foundation; with no Invariant Sections, no Front-Cover Texts, and 13 no Back-Cover Texts. A copy of the license is included in the 14 section entitled "GNU Free Documentation License". 15 16INFO-DIR-SECTION Libraries 17START-INFO-DIR-ENTRY 18* Readline: (readline). The GNU readline library API. 19END-INFO-DIR-ENTRY 20 21 22File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir) 23 24GNU Readline Library 25******************** 26 27This document describes the GNU Readline Library, a utility which aids 28in the consistency of user interface across discrete programs which 29provide a command line interface. The Readline home page is 30<http://www.gnu.org/software/readline/>. 31 32* Menu: 33 34* Command Line Editing:: GNU Readline User's Manual. 35* Programming with GNU Readline:: GNU Readline Programmer's Manual. 36* GNU Free Documentation License:: License for copying this manual. 37* Concept Index:: Index of concepts described in this manual. 38* Function and Variable Index:: Index of externally visible functions 39 and variables. 40 41 42File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top 43 441 Command Line Editing 45********************** 46 47This chapter describes the basic features of the GNU command line 48editing interface. 49 50* Menu: 51 52* Introduction and Notation:: Notation used in this text. 53* Readline Interaction:: The minimum set of commands for editing a line. 54* Readline Init File:: Customizing Readline from a user's view. 55* Bindable Readline Commands:: A description of most of the Readline commands 56 available for binding 57* Readline vi Mode:: A short description of how to make Readline 58 behave like the vi editor. 59 60 61File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing 62 631.1 Introduction to Line Editing 64================================ 65 66The following paragraphs describe the notation used to represent 67keystrokes. 68 69 The text 'C-k' is read as 'Control-K' and describes the character 70produced when the <k> key is pressed while the Control key is depressed. 71 72 The text 'M-k' is read as 'Meta-K' and describes the character 73produced when the Meta key (if you have one) is depressed, and the <k> 74key is pressed. The Meta key is labeled <ALT> on many keyboards. On 75keyboards with two keys labeled <ALT> (usually to either side of the 76space bar), the <ALT> on the left side is generally set to work as a 77Meta key. The <ALT> key on the right may also be configured to work as 78a Meta key or may be configured as some other modifier, such as a 79Compose key for typing accented characters. 80 81 If you do not have a Meta or <ALT> key, or another key working as a 82Meta key, the identical keystroke can be generated by typing <ESC> 83_first_, and then typing <k>. Either process is known as "metafying" 84the <k> key. 85 86 The text 'M-C-k' is read as 'Meta-Control-k' and describes the 87character produced by "metafying" 'C-k'. 88 89 In addition, several keys have their own names. Specifically, <DEL>, 90<ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen 91in this text, or in an init file (*note Readline Init File::). If your 92keyboard lacks a <LFD> key, typing <C-j> will produce the desired 93character. The <RET> key may be labeled <Return> or <Enter> on some 94keyboards. 95 96 97File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing 98 991.2 Readline Interaction 100======================== 101 102Often during an interactive session you type in a long line of text, 103only to notice that the first word on the line is misspelled. The 104Readline library gives you a set of commands for manipulating the text 105as you type it in, allowing you to just fix your typo, and not forcing 106you to retype the majority of the line. Using these editing commands, 107you move the cursor to the place that needs correction, and delete or 108insert the text of the corrections. Then, when you are satisfied with 109the line, you simply press <RET>. You do not have to be at the end of 110the line to press <RET>; the entire line is accepted regardless of the 111location of the cursor within the line. 112 113* Menu: 114 115* Readline Bare Essentials:: The least you need to know about Readline. 116* Readline Movement Commands:: Moving about the input line. 117* Readline Killing Commands:: How to delete text, and how to get it back! 118* Readline Arguments:: Giving numeric arguments to commands. 119* Searching:: Searching through previous lines. 120 121 122File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction 123 1241.2.1 Readline Bare Essentials 125------------------------------ 126 127In order to enter characters into the line, simply type them. The typed 128character appears where the cursor was, and then the cursor moves one 129space to the right. If you mistype a character, you can use your erase 130character to back up and delete the mistyped character. 131 132 Sometimes you may mistype a character, and not notice the error until 133you have typed several other characters. In that case, you can type 134'C-b' to move the cursor to the left, and then correct your mistake. 135Afterwards, you can move the cursor to the right with 'C-f'. 136 137 When you add text in the middle of a line, you will notice that 138characters to the right of the cursor are 'pushed over' to make room for 139the text that you have inserted. Likewise, when you delete text behind 140the cursor, characters to the right of the cursor are 'pulled back' to 141fill in the blank space created by the removal of the text. A list of 142the bare essentials for editing the text of an input line follows. 143 144'C-b' 145 Move back one character. 146'C-f' 147 Move forward one character. 148<DEL> or <Backspace> 149 Delete the character to the left of the cursor. 150'C-d' 151 Delete the character underneath the cursor. 152Printing characters 153 Insert the character into the line at the cursor. 154'C-_' or 'C-x C-u' 155 Undo the last editing command. You can undo all the way back to an 156 empty line. 157 158(Depending on your configuration, the <Backspace> key be set to delete 159the character to the left of the cursor and the <DEL> key set to delete 160the character underneath the cursor, like 'C-d', rather than the 161character to the left of the cursor.) 162 163 164File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction 165 1661.2.2 Readline Movement Commands 167-------------------------------- 168 169The above table describes the most basic keystrokes that you need in 170order to do editing of the input line. For your convenience, many other 171commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>. 172Here are some commands for moving more rapidly about the line. 173 174'C-a' 175 Move to the start of the line. 176'C-e' 177 Move to the end of the line. 178'M-f' 179 Move forward a word, where a word is composed of letters and 180 digits. 181'M-b' 182 Move backward a word. 183'C-l' 184 Clear the screen, reprinting the current line at the top. 185 186 Notice how 'C-f' moves forward a character, while 'M-f' moves forward 187a word. It is a loose convention that control keystrokes operate on 188characters while meta keystrokes operate on words. 189 190 191File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction 192 1931.2.3 Readline Killing Commands 194------------------------------- 195 196"Killing" text means to delete the text from the line, but to save it 197away for later use, usually by "yanking" (re-inserting) it back into the 198line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) 199 200 If the description for a command says that it 'kills' text, then you 201can be sure that you can get the text back in a different (or the same) 202place later. 203 204 When you use a kill command, the text is saved in a "kill-ring". Any 205number of consecutive kills save all of the killed text together, so 206that when you yank it back, you get it all. The kill ring is not line 207specific; the text that you killed on a previously typed line is 208available to be yanked back later, when you are typing another line. 209 210 Here is the list of commands for killing text. 211 212'C-k' 213 Kill the text from the current cursor position to the end of the 214 line. 215 216'M-d' 217 Kill from the cursor to the end of the current word, or, if between 218 words, to the end of the next word. Word boundaries are the same 219 as those used by 'M-f'. 220 221'M-<DEL>' 222 Kill from the cursor the start of the current word, or, if between 223 words, to the start of the previous word. Word boundaries are the 224 same as those used by 'M-b'. 225 226'C-w' 227 Kill from the cursor to the previous whitespace. This is different 228 than 'M-<DEL>' because the word boundaries differ. 229 230 Here is how to "yank" the text back into the line. Yanking means to 231copy the most-recently-killed text from the kill buffer. 232 233'C-y' 234 Yank the most recently killed text back into the buffer at the 235 cursor. 236 237'M-y' 238 Rotate the kill-ring, and yank the new top. You can only do this 239 if the prior command is 'C-y' or 'M-y'. 240 241 242File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction 243 2441.2.4 Readline Arguments 245------------------------ 246 247You can pass numeric arguments to Readline commands. Sometimes the 248argument acts as a repeat count, other times it is the sign of the 249argument that is significant. If you pass a negative argument to a 250command which normally acts in a forward direction, that command will 251act in a backward direction. For example, to kill text back to the 252start of the line, you might type 'M-- C-k'. 253 254 The general way to pass numeric arguments to a command is to type 255meta digits before the command. If the first 'digit' typed is a minus 256sign ('-'), then the sign of the argument will be negative. Once you 257have typed one meta digit to get the argument started, you can type the 258remainder of the digits, and then the command. For example, to give the 259'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will 260delete the next ten characters on the input line. 261 262 263File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction 264 2651.2.5 Searching for Commands in the History 266------------------------------------------- 267 268Readline provides commands for searching through the command history for 269lines containing a specified string. There are two search modes: 270"incremental" and "non-incremental". 271 272 Incremental searches begin before the user has finished typing the 273search string. As each character of the search string is typed, 274Readline displays the next entry from the history matching the string 275typed so far. An incremental search requires only as many characters as 276needed to find the desired history entry. To search backward in the 277history for a particular string, type 'C-r'. Typing 'C-s' searches 278forward through the history. The characters present in the value of the 279'isearch-terminators' variable are used to terminate an incremental 280search. If that variable has not been assigned a value, the <ESC> and 281'C-J' characters will terminate an incremental search. 'C-g' will abort 282an incremental search and restore the original line. When the search is 283terminated, the history entry containing the search string becomes the 284current line. 285 286 To find other matching entries in the history list, type 'C-r' or 287'C-s' as appropriate. This will search backward or forward in the 288history for the next entry matching the search string typed so far. Any 289other key sequence bound to a Readline command will terminate the search 290and execute that command. For instance, a <RET> will terminate the 291search and accept the line, thereby executing the command from the 292history list. A movement command will terminate the search, make the 293last line found the current line, and begin editing. 294 295 Readline remembers the last incremental search string. If two 'C-r's 296are typed without any intervening characters defining a new search 297string, any remembered search string is used. 298 299 Non-incremental searches read the entire search string before 300starting to search for matching history lines. The search string may be 301typed by the user or be part of the contents of the current line. 302 303 304File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing 305 3061.3 Readline Init File 307====================== 308 309Although the Readline library comes with a set of Emacs-like keybindings 310installed by default, it is possible to use a different set of 311keybindings. Any user can customize programs that use Readline by 312putting commands in an "inputrc" file, conventionally in his home 313directory. The name of this file is taken from the value of the 314environment variable 'INPUTRC'. If that variable is unset, the default 315is '~/.inputrc'. If that file does not exist or cannot be read, the 316ultimate default is '/etc/inputrc'. 317 318 When a program which uses the Readline library starts up, the init 319file is read, and the key bindings are set. 320 321 In addition, the 'C-x C-r' command re-reads this init file, thus 322incorporating any changes that you might have made to it. 323 324* Menu: 325 326* Readline Init File Syntax:: Syntax for the commands in the inputrc file. 327 328* Conditional Init Constructs:: Conditional key bindings in the inputrc file. 329 330* Sample Init File:: An example inputrc file. 331 332 333File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File 334 3351.3.1 Readline Init File Syntax 336------------------------------- 337 338There are only a few basic constructs allowed in the Readline init file. 339Blank lines are ignored. Lines beginning with a '#' are comments. 340Lines beginning with a '$' indicate conditional constructs (*note 341Conditional Init Constructs::). Other lines denote variable settings 342and key bindings. 343 344Variable Settings 345 You can modify the run-time behavior of Readline by altering the 346 values of variables in Readline using the 'set' command within the 347 init file. The syntax is simple: 348 349 set VARIABLE VALUE 350 351 Here, for example, is how to change from the default Emacs-like key 352 binding to use 'vi' line editing commands: 353 354 set editing-mode vi 355 356 Variable names and values, where appropriate, are recognized 357 without regard to case. Unrecognized variable names are ignored. 358 359 Boolean variables (those that can be set to on or off) are set to 360 on if the value is null or empty, ON (case-insensitive), or 1. Any 361 other value results in the variable being set to off. 362 363 A great deal of run-time behavior is changeable with the following 364 variables. 365 366 'bell-style' 367 Controls what happens when Readline wants to ring the terminal 368 bell. If set to 'none', Readline never rings the bell. If 369 set to 'visible', Readline uses a visible bell if one is 370 available. If set to 'audible' (the default), Readline 371 attempts to ring the terminal's bell. 372 373 'bind-tty-special-chars' 374 If set to 'on' (the default), Readline attempts to bind the 375 control characters treated specially by the kernel's terminal 376 driver to their Readline equivalents. 377 378 'blink-matching-paren' 379 If set to 'on', Readline attempts to briefly move the cursor 380 to an opening parenthesis when a closing parenthesis is 381 inserted. The default is 'off'. 382 383 'colored-completion-prefix' 384 If set to 'on', when listing completions, Readline displays 385 the common prefix of the set of possible completions using a 386 different color. The color definitions are taken from the 387 value of the 'LS_COLORS' environment variable. The default is 388 'off'. 389 390 'colored-stats' 391 If set to 'on', Readline displays possible completions using 392 different colors to indicate their file type. The color 393 definitions are taken from the value of the 'LS_COLORS' 394 environment variable. The default is 'off'. 395 396 'comment-begin' 397 The string to insert at the beginning of the line when the 398 'insert-comment' command is executed. The default value is 399 '"#"'. 400 401 'completion-display-width' 402 The number of screen columns used to display possible matches 403 when performing completion. The value is ignored if it is 404 less than 0 or greater than the terminal screen width. A 405 value of 0 will cause matches to be displayed one per line. 406 The default value is -1. 407 408 'completion-ignore-case' 409 If set to 'on', Readline performs filename matching and 410 completion in a case-insensitive fashion. The default value 411 is 'off'. 412 413 'completion-map-case' 414 If set to 'on', and COMPLETION-IGNORE-CASE is enabled, 415 Readline treats hyphens ('-') and underscores ('_') as 416 equivalent when performing case-insensitive filename matching 417 and completion. The default value is 'off'. 418 419 'completion-prefix-display-length' 420 The length in characters of the common prefix of a list of 421 possible completions that is displayed without modification. 422 When set to a value greater than zero, common prefixes longer 423 than this value are replaced with an ellipsis when displaying 424 possible completions. 425 426 'completion-query-items' 427 The number of possible completions that determines when the 428 user is asked whether the list of possibilities should be 429 displayed. If the number of possible completions is greater 430 than or equal to this value, Readline will ask whether or not 431 the user wishes to view them; otherwise, they are simply 432 listed. This variable must be set to an integer value greater 433 than or equal to 0. A negative value means Readline should 434 never ask. The default limit is '100'. 435 436 'convert-meta' 437 If set to 'on', Readline will convert characters with the 438 eighth bit set to an ASCII key sequence by stripping the 439 eighth bit and prefixing an <ESC> character, converting them 440 to a meta-prefixed key sequence. The default value is 'on', 441 but will be set to 'off' if the locale is one that contains 442 eight-bit characters. 443 444 'disable-completion' 445 If set to 'On', Readline will inhibit word completion. 446 Completion characters will be inserted into the line as if 447 they had been mapped to 'self-insert'. The default is 'off'. 448 449 'echo-control-characters' 450 When set to 'on', on operating systems that indicate they 451 support it, readline echoes a character corresponding to a 452 signal generated from the keyboard. The default is 'on'. 453 454 'editing-mode' 455 The 'editing-mode' variable controls which default set of key 456 bindings is used. By default, Readline starts up in Emacs 457 editing mode, where the keystrokes are most similar to Emacs. 458 This variable can be set to either 'emacs' or 'vi'. 459 460 'emacs-mode-string' 461 If the SHOW-MODE-IN-PROMPT variable is enabled, this string is 462 displayed immediately before the last line of the primary 463 prompt when emacs editing mode is active. The value is 464 expanded like a key binding, so the standard set of meta- and 465 control prefixes and backslash escape sequences is available. 466 Use the '\1' and '\2' escapes to begin and end sequences of 467 non-printing characters, which can be used to embed a terminal 468 control sequence into the mode string. The default is '@'. 469 470 'enable-bracketed-paste' 471 When set to 'On', Readline will configure the terminal in a 472 way that will enable it to insert each paste into the editing 473 buffer as a single string of characters, instead of treating 474 each character as if it had been read from the keyboard. This 475 can prevent pasted characters from being interpreted as 476 editing commands. The default is 'On'. 477 478 'enable-keypad' 479 When set to 'on', Readline will try to enable the application 480 keypad when it is called. Some systems need this to enable 481 the arrow keys. The default is 'off'. 482 483 'enable-meta-key' 484 When set to 'on', Readline will try to enable any meta 485 modifier key the terminal claims to support when it is called. 486 On many terminals, the meta key is used to send eight-bit 487 characters. The default is 'on'. 488 489 'expand-tilde' 490 If set to 'on', tilde expansion is performed when Readline 491 attempts word completion. The default is 'off'. 492 493 'history-preserve-point' 494 If set to 'on', the history code attempts to place the point 495 (the current cursor position) at the same location on each 496 history line retrieved with 'previous-history' or 497 'next-history'. The default is 'off'. 498 499 'history-size' 500 Set the maximum number of history entries saved in the history 501 list. If set to zero, any existing history entries are 502 deleted and no new entries are saved. If set to a value less 503 than zero, the number of history entries is not limited. By 504 default, the number of history entries is not limited. If an 505 attempt is made to set HISTORY-SIZE to a non-numeric value, 506 the maximum number of history entries will be set to 500. 507 508 'horizontal-scroll-mode' 509 This variable can be set to either 'on' or 'off'. Setting it 510 to 'on' means that the text of the lines being edited will 511 scroll horizontally on a single screen line when they are 512 longer than the width of the screen, instead of wrapping onto 513 a new screen line. This variable is automatically set to 'on' 514 for terminals of height 1. By default, this variable is set 515 to 'off'. 516 517 'input-meta' 518 If set to 'on', Readline will enable eight-bit input (it will 519 not clear the eighth bit in the characters it reads), 520 regardless of what the terminal claims it can support. The 521 default value is 'off', but Readline will set it to 'on' if 522 the locale contains eight-bit characters. The name 523 'meta-flag' is a synonym for this variable. 524 525 'isearch-terminators' 526 The string of characters that should terminate an incremental 527 search without subsequently executing the character as a 528 command (*note Searching::). If this variable has not been 529 given a value, the characters <ESC> and 'C-J' will terminate 530 an incremental search. 531 532 'keymap' 533 Sets Readline's idea of the current keymap for key binding 534 commands. Built-in 'keymap' names are 'emacs', 535 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', 536 'vi-command', and 'vi-insert'. 'vi' is equivalent to 537 'vi-command' ('vi-move' is also a synonym); 'emacs' is 538 equivalent to 'emacs-standard'. Applications may add 539 additional names. The default value is 'emacs'. The value of 540 the 'editing-mode' variable also affects the default keymap. 541 542 'keyseq-timeout' 543 Specifies the duration Readline will wait for a character when 544 reading an ambiguous key sequence (one that can form a 545 complete key sequence using the input read so far, or can take 546 additional input to complete a longer key sequence). If no 547 input is received within the timeout, Readline will use the 548 shorter but complete key sequence. Readline uses this value 549 to determine whether or not input is available on the current 550 input source ('rl_instream' by default). The value is 551 specified in milliseconds, so a value of 1000 means that 552 Readline will wait one second for additional input. If this 553 variable is set to a value less than or equal to zero, or to a 554 non-numeric value, Readline will wait until another key is 555 pressed to decide which key sequence to complete. The default 556 value is '500'. 557 558 'mark-directories' 559 If set to 'on', completed directory names have a slash 560 appended. The default is 'on'. 561 562 'mark-modified-lines' 563 This variable, when set to 'on', causes Readline to display an 564 asterisk ('*') at the start of history lines which have been 565 modified. This variable is 'off' by default. 566 567 'mark-symlinked-directories' 568 If set to 'on', completed names which are symbolic links to 569 directories have a slash appended (subject to the value of 570 'mark-directories'). The default is 'off'. 571 572 'match-hidden-files' 573 This variable, when set to 'on', causes Readline to match 574 files whose names begin with a '.' (hidden files) when 575 performing filename completion. If set to 'off', the leading 576 '.' must be supplied by the user in the filename to be 577 completed. This variable is 'on' by default. 578 579 'menu-complete-display-prefix' 580 If set to 'on', menu completion displays the common prefix of 581 the list of possible completions (which may be empty) before 582 cycling through the list. The default is 'off'. 583 584 'output-meta' 585 If set to 'on', Readline will display characters with the 586 eighth bit set directly rather than as a meta-prefixed escape 587 sequence. The default is 'off', but Readline will set it to 588 'on' if the locale contains eight-bit characters. 589 590 'page-completions' 591 If set to 'on', Readline uses an internal 'more'-like pager to 592 display a screenful of possible completions at a time. This 593 variable is 'on' by default. 594 595 'print-completions-horizontally' 596 If set to 'on', Readline will display completions with matches 597 sorted horizontally in alphabetical order, rather than down 598 the screen. The default is 'off'. 599 600 'revert-all-at-newline' 601 If set to 'on', Readline will undo all changes to history 602 lines before returning when 'accept-line' is executed. By 603 default, history lines may be modified and retain individual 604 undo lists across calls to 'readline'. The default is 'off'. 605 606 'show-all-if-ambiguous' 607 This alters the default behavior of the completion functions. 608 If set to 'on', words which have more than one possible 609 completion cause the matches to be listed immediately instead 610 of ringing the bell. The default value is 'off'. 611 612 'show-all-if-unmodified' 613 This alters the default behavior of the completion functions 614 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to 615 'on', words which have more than one possible completion 616 without any possible partial completion (the possible 617 completions don't share a common prefix) cause the matches to 618 be listed immediately instead of ringing the bell. The 619 default value is 'off'. 620 621 'show-mode-in-prompt' 622 If set to 'on', add a string to the beginning of the prompt 623 indicating the editing mode: emacs, vi command, or vi 624 insertion. The mode strings are user-settable (e.g., 625 EMACS-MODE-STRING). The default value is 'off'. 626 627 'skip-completed-text' 628 If set to 'on', this alters the default completion behavior 629 when inserting a single match into the line. It's only active 630 when performing completion in the middle of a word. If 631 enabled, readline does not insert characters from the 632 completion that match characters after point in the word being 633 completed, so portions of the word following the cursor are 634 not duplicated. For instance, if this is enabled, attempting 635 completion when the cursor is after the 'e' in 'Makefile' will 636 result in 'Makefile' rather than 'Makefilefile', assuming 637 there is a single possible completion. The default value is 638 'off'. 639 640 'vi-cmd-mode-string' 641 If the SHOW-MODE-IN-PROMPT variable is enabled, this string is 642 displayed immediately before the last line of the primary 643 prompt when vi editing mode is active and in command mode. 644 The value is expanded like a key binding, so the standard set 645 of meta- and control prefixes and backslash escape sequences 646 is available. Use the '\1' and '\2' escapes to begin and end 647 sequences of non-printing characters, which can be used to 648 embed a terminal control sequence into the mode string. The 649 default is '(cmd)'. 650 651 'vi-ins-mode-string' 652 If the SHOW-MODE-IN-PROMPT variable is enabled, this string is 653 displayed immediately before the last line of the primary 654 prompt when vi editing mode is active and in insertion mode. 655 The value is expanded like a key binding, so the standard set 656 of meta- and control prefixes and backslash escape sequences 657 is available. Use the '\1' and '\2' escapes to begin and end 658 sequences of non-printing characters, which can be used to 659 embed a terminal control sequence into the mode string. The 660 default is '(ins)'. 661 662 'visible-stats' 663 If set to 'on', a character denoting a file's type is appended 664 to the filename when listing possible completions. The 665 default is 'off'. 666 667Key Bindings 668 The syntax for controlling key bindings in the init file is simple. 669 First you need to find the name of the command that you want to 670 change. The following sections contain tables of the command name, 671 the default keybinding, if any, and a short description of what the 672 command does. 673 674 Once you know the name of the command, simply place on a line in 675 the init file the name of the key you wish to bind the command to, 676 a colon, and then the name of the command. There can be no space 677 between the key name and the colon - that will be interpreted as 678 part of the key name. The name of the key can be expressed in 679 different ways, depending on what you find most comfortable. 680 681 In addition to command names, readline allows keys to be bound to a 682 string that is inserted when the key is pressed (a MACRO). 683 684 KEYNAME: FUNCTION-NAME or MACRO 685 KEYNAME is the name of a key spelled out in English. For 686 example: 687 Control-u: universal-argument 688 Meta-Rubout: backward-kill-word 689 Control-o: "> output" 690 691 In the example above, 'C-u' is bound to the function 692 'universal-argument', 'M-DEL' is bound to the function 693 'backward-kill-word', and 'C-o' is bound to run the macro 694 expressed on the right hand side (that is, to insert the text 695 '> output' into the line). 696 697 A number of symbolic character names are recognized while 698 processing this key binding syntax: DEL, ESC, ESCAPE, LFD, 699 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. 700 701 "KEYSEQ": FUNCTION-NAME or MACRO 702 KEYSEQ differs from KEYNAME above in that strings denoting an 703 entire key sequence can be specified, by placing the key 704 sequence in double quotes. Some GNU Emacs style key escapes 705 can be used, as in the following example, but the special 706 character names are not recognized. 707 708 "\C-u": universal-argument 709 "\C-x\C-r": re-read-init-file 710 "\e[11~": "Function Key 1" 711 712 In the above example, 'C-u' is again bound to the function 713 'universal-argument' (just as it was in the first example), 714 ''C-x' 'C-r'' is bound to the function 're-read-init-file', 715 and '<ESC> <[> <1> <1> <~>' is bound to insert the text 716 'Function Key 1'. 717 718 The following GNU Emacs style escape sequences are available when 719 specifying key sequences: 720 721 '\C-' 722 control prefix 723 '\M-' 724 meta prefix 725 '\e' 726 an escape character 727 '\\' 728 backslash 729 '\"' 730 <">, a double quotation mark 731 '\'' 732 <'>, a single quote or apostrophe 733 734 In addition to the GNU Emacs style escape sequences, a second set 735 of backslash escapes is available: 736 737 '\a' 738 alert (bell) 739 '\b' 740 backspace 741 '\d' 742 delete 743 '\f' 744 form feed 745 '\n' 746 newline 747 '\r' 748 carriage return 749 '\t' 750 horizontal tab 751 '\v' 752 vertical tab 753 '\NNN' 754 the eight-bit character whose value is the octal value NNN 755 (one to three digits) 756 '\xHH' 757 the eight-bit character whose value is the hexadecimal value 758 HH (one or two hex digits) 759 760 When entering the text of a macro, single or double quotes must be 761 used to indicate a macro definition. Unquoted text is assumed to 762 be a function name. In the macro body, the backslash escapes 763 described above are expanded. Backslash will quote any other 764 character in the macro text, including '"' and '''. For example, 765 the following binding will make ''C-x' \' insert a single '\' into 766 the line: 767 "\C-x\\": "\\" 768 769 770File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File 771 7721.3.2 Conditional Init Constructs 773--------------------------------- 774 775Readline implements a facility similar in spirit to the conditional 776compilation features of the C preprocessor which allows key bindings and 777variable settings to be performed as the result of tests. There are 778four parser directives used. 779 780'$if' 781 The '$if' construct allows bindings to be made based on the editing 782 mode, the terminal being used, or the application using Readline. 783 The text of the test, after any comparison operator, extends to the 784 end of the line; unless otherwise noted, no characters are required 785 to isolate it. 786 787 'mode' 788 The 'mode=' form of the '$if' directive is used to test 789 whether Readline is in 'emacs' or 'vi' mode. This may be used 790 in conjunction with the 'set keymap' command, for instance, to 791 set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps 792 only if Readline is starting out in 'emacs' mode. 793 794 'term' 795 The 'term=' form may be used to include terminal-specific key 796 bindings, perhaps to bind the key sequences output by the 797 terminal's function keys. The word on the right side of the 798 '=' is tested against both the full name of the terminal and 799 the portion of the terminal name before the first '-'. This 800 allows 'sun' to match both 'sun' and 'sun-cmd', for instance. 801 802 'version' 803 The 'version' test may be used to perform comparisons against 804 specific Readline versions. The 'version' expands to the 805 current Readline version. The set of comparison operators 806 includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The 807 version number supplied on the right side of the operator 808 consists of a major version number, an optional decimal point, 809 and an optional minor version (e.g., '7.1'). If the minor 810 version is omitted, it is assumed to be '0'. The operator may 811 be separated from the string 'version' and from the version 812 number argument by whitespace. The following example sets a 813 variable if the Readline version being used is 7.0 or newer: 814 $if version >= 7.0 815 set show-mode-in-prompt on 816 $endif 817 818 'application' 819 The APPLICATION construct is used to include 820 application-specific settings. Each program using the 821 Readline library sets the APPLICATION NAME, and you can test 822 for a particular value. This could be used to bind key 823 sequences to functions useful for a specific program. For 824 instance, the following command adds a key sequence that 825 quotes the current or previous word in Bash: 826 $if Bash 827 # Quote the current or previous word 828 "\C-xq": "\eb\"\ef\"" 829 $endif 830 831 'variable' 832 The VARIABLE construct provides simple equality tests for 833 Readline variables and values. The permitted comparison 834 operators are '=', '==', and '!='. The variable name must be 835 separated from the comparison operator by whitespace; the 836 operator may be separated from the value on the right hand 837 side by whitespace. Both string and boolean variables may be 838 tested. Boolean variables must be tested against the values 839 ON and OFF. The following example is equivalent to the 840 'mode=emacs' test described above: 841 $if editing-mode == emacs 842 set show-mode-in-prompt on 843 $endif 844 845'$endif' 846 This command, as seen in the previous example, terminates an '$if' 847 command. 848 849'$else' 850 Commands in this branch of the '$if' directive are executed if the 851 test fails. 852 853'$include' 854 This directive takes a single filename as an argument and reads 855 commands and bindings from that file. For example, the following 856 directive reads from '/etc/inputrc': 857 $include /etc/inputrc 858 859 860File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File 861 8621.3.3 Sample Init File 863---------------------- 864 865Here is an example of an INPUTRC file. This illustrates key binding, 866variable assignment, and conditional syntax. 867 868 # This file controls the behaviour of line input editing for 869 # programs that use the GNU Readline library. Existing 870 # programs include FTP, Bash, and GDB. 871 # 872 # You can re-read the inputrc file with C-x C-r. 873 # Lines beginning with '#' are comments. 874 # 875 # First, include any system-wide bindings and variable 876 # assignments from /etc/Inputrc 877 $include /etc/Inputrc 878 879 # 880 # Set various bindings for emacs mode. 881 882 set editing-mode emacs 883 884 $if mode=emacs 885 886 Meta-Control-h: backward-kill-word Text after the function name is ignored 887 888 # 889 # Arrow keys in keypad mode 890 # 891 #"\M-OD": backward-char 892 #"\M-OC": forward-char 893 #"\M-OA": previous-history 894 #"\M-OB": next-history 895 # 896 # Arrow keys in ANSI mode 897 # 898 "\M-[D": backward-char 899 "\M-[C": forward-char 900 "\M-[A": previous-history 901 "\M-[B": next-history 902 # 903 # Arrow keys in 8 bit keypad mode 904 # 905 #"\M-\C-OD": backward-char 906 #"\M-\C-OC": forward-char 907 #"\M-\C-OA": previous-history 908 #"\M-\C-OB": next-history 909 # 910 # Arrow keys in 8 bit ANSI mode 911 # 912 #"\M-\C-[D": backward-char 913 #"\M-\C-[C": forward-char 914 #"\M-\C-[A": previous-history 915 #"\M-\C-[B": next-history 916 917 C-q: quoted-insert 918 919 $endif 920 921 # An old-style binding. This happens to be the default. 922 TAB: complete 923 924 # Macros that are convenient for shell interaction 925 $if Bash 926 # edit the path 927 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" 928 # prepare to type a quoted word -- 929 # insert open and close double quotes 930 # and move to just after the open quote 931 "\C-x\"": "\"\"\C-b" 932 # insert a backslash (testing backslash escapes 933 # in sequences and macros) 934 "\C-x\\": "\\" 935 # Quote the current or previous word 936 "\C-xq": "\eb\"\ef\"" 937 # Add a binding to refresh the line, which is unbound 938 "\C-xr": redraw-current-line 939 # Edit variable on current line. 940 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 941 $endif 942 943 # use a visible bell if one is available 944 set bell-style visible 945 946 # don't strip characters to 7 bits when reading 947 set input-meta on 948 949 # allow iso-latin1 characters to be inserted rather 950 # than converted to prefix-meta sequences 951 set convert-meta off 952 953 # display characters with the eighth bit set directly 954 # rather than as meta-prefixed characters 955 set output-meta on 956 957 # if there are 150 or more possible completions for a word, 958 # ask whether or not the user wants to see all of them 959 set completion-query-items 150 960 961 # For FTP 962 $if Ftp 963 "\C-xg": "get \M-?" 964 "\C-xt": "put \M-?" 965 "\M-.": yank-last-arg 966 $endif 967 968 969File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing 970 9711.4 Bindable Readline Commands 972============================== 973 974* Menu: 975 976* Commands For Moving:: Moving about the line. 977* Commands For History:: Getting at previous lines. 978* Commands For Text:: Commands for changing text. 979* Commands For Killing:: Commands for killing and yanking. 980* Numeric Arguments:: Specifying numeric arguments, repeat counts. 981* Commands For Completion:: Getting Readline to do the typing for you. 982* Keyboard Macros:: Saving and re-executing typed characters 983* Miscellaneous Commands:: Other miscellaneous commands. 984 985This section describes Readline commands that may be bound to key 986sequences. Command names without an accompanying key sequence are 987unbound by default. 988 989 In the following descriptions, "point" refers to the current cursor 990position, and "mark" refers to a cursor position saved by the 'set-mark' 991command. The text between the point and mark is referred to as the 992"region". 993 994 995File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands 996 9971.4.1 Commands For Moving 998------------------------- 999 1000'beginning-of-line (C-a)' 1001 Move to the start of the current line. 1002 1003'end-of-line (C-e)' 1004 Move to the end of the line. 1005 1006'forward-char (C-f)' 1007 Move forward a character. 1008 1009'backward-char (C-b)' 1010 Move back a character. 1011 1012'forward-word (M-f)' 1013 Move forward to the end of the next word. Words are composed of 1014 letters and digits. 1015 1016'backward-word (M-b)' 1017 Move back to the start of the current or previous word. Words are 1018 composed of letters and digits. 1019 1020'previous-screen-line ()' 1021 Attempt to move point to the same physical screen column on the 1022 previous physical screen line. This will not have the desired 1023 effect if the current Readline line does not take up more than one 1024 physical line or if point is not greater than the length of the 1025 prompt plus the screen width. 1026 1027'next-screen-line ()' 1028 Attempt to move point to the same physical screen column on the 1029 next physical screen line. This will not have the desired effect 1030 if the current Readline line does not take up more than one 1031 physical line or if the length of the current Readline line is not 1032 greater than the length of the prompt plus the screen width. 1033 1034'clear-display (M-C-l)' 1035 Clear the screen and, if possible, the terminal's scrollback 1036 buffer, then redraw the current line, leaving the current line at 1037 the top of the screen. 1038 1039'clear-screen (C-l)' 1040 Clear the screen, then redraw the current line, leaving the current 1041 line at the top of the screen. 1042 1043'redraw-current-line ()' 1044 Refresh the current line. By default, this is unbound. 1045 1046 1047File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands 1048 10491.4.2 Commands For Manipulating The History 1050------------------------------------------- 1051 1052'accept-line (Newline or Return)' 1053 Accept the line regardless of where the cursor is. If this line is 1054 non-empty, it may be added to the history list for future recall 1055 with 'add_history()'. If this line is a modified history line, the 1056 history line is restored to its original state. 1057 1058'previous-history (C-p)' 1059 Move 'back' through the history list, fetching the previous 1060 command. 1061 1062'next-history (C-n)' 1063 Move 'forward' through the history list, fetching the next command. 1064 1065'beginning-of-history (M-<)' 1066 Move to the first line in the history. 1067 1068'end-of-history (M->)' 1069 Move to the end of the input history, i.e., the line currently 1070 being entered. 1071 1072'reverse-search-history (C-r)' 1073 Search backward starting at the current line and moving 'up' 1074 through the history as necessary. This is an incremental search. 1075 This command sets the region to the matched text and activates the 1076 mark. 1077 1078'forward-search-history (C-s)' 1079 Search forward starting at the current line and moving 'down' 1080 through the history as necessary. This is an incremental search. 1081 This command sets the region to the matched text and activates the 1082 mark. 1083 1084'non-incremental-reverse-search-history (M-p)' 1085 Search backward starting at the current line and moving 'up' 1086 through the history as necessary using a non-incremental search for 1087 a string supplied by the user. The search string may match 1088 anywhere in a history line. 1089 1090'non-incremental-forward-search-history (M-n)' 1091 Search forward starting at the current line and moving 'down' 1092 through the history as necessary using a non-incremental search for 1093 a string supplied by the user. The search string may match 1094 anywhere in a history line. 1095 1096'history-search-forward ()' 1097 Search forward through the history for the string of characters 1098 between the start of the current line and the point. The search 1099 string must match at the beginning of a history line. This is a 1100 non-incremental search. By default, this command is unbound. 1101 1102'history-search-backward ()' 1103 Search backward through the history for the string of characters 1104 between the start of the current line and the point. The search 1105 string must match at the beginning of a history line. This is a 1106 non-incremental search. By default, this command is unbound. 1107 1108'history-substring-search-forward ()' 1109 Search forward through the history for the string of characters 1110 between the start of the current line and the point. The search 1111 string may match anywhere in a history line. This is a 1112 non-incremental search. By default, this command is unbound. 1113 1114'history-substring-search-backward ()' 1115 Search backward through the history for the string of characters 1116 between the start of the current line and the point. The search 1117 string may match anywhere in a history line. This is a 1118 non-incremental search. By default, this command is unbound. 1119 1120'yank-nth-arg (M-C-y)' 1121 Insert the first argument to the previous command (usually the 1122 second word on the previous line) at point. With an argument N, 1123 insert the Nth word from the previous command (the words in the 1124 previous command begin with word 0). A negative argument inserts 1125 the Nth word from the end of the previous command. Once the 1126 argument N is computed, the argument is extracted as if the '!N' 1127 history expansion had been specified. 1128 1129'yank-last-arg (M-. or M-_)' 1130 Insert last argument to the previous command (the last word of the 1131 previous history entry). With a numeric argument, behave exactly 1132 like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back 1133 through the history list, inserting the last word (or the word 1134 specified by the argument to the first call) of each line in turn. 1135 Any numeric argument supplied to these successive calls determines 1136 the direction to move through the history. A negative argument 1137 switches the direction through the history (back or forward). The 1138 history expansion facilities are used to extract the last argument, 1139 as if the '!$' history expansion had been specified. 1140 1141'operate-and-get-next (C-o)' 1142 Accept the current line for return to the calling application as if 1143 a newline had been entered, and fetch the next line relative to the 1144 current line from the history for editing. A numeric argument, if 1145 supplied, specifies the history entry to use instead of the current 1146 line. 1147 1148 1149File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands 1150 11511.4.3 Commands For Changing Text 1152-------------------------------- 1153 1154'end-of-file (usually C-d)' 1155 The character indicating end-of-file as set, for example, by 1156 'stty'. If this character is read when there are no characters on 1157 the line, and point is at the beginning of the line, Readline 1158 interprets it as the end of input and returns EOF. 1159 1160'delete-char (C-d)' 1161 Delete the character at point. If this function is bound to the 1162 same character as the tty EOF character, as 'C-d' commonly is, see 1163 above for the effects. 1164 1165'backward-delete-char (Rubout)' 1166 Delete the character behind the cursor. A numeric argument means 1167 to kill the characters instead of deleting them. 1168 1169'forward-backward-delete-char ()' 1170 Delete the character under the cursor, unless the cursor is at the 1171 end of the line, in which case the character behind the cursor is 1172 deleted. By default, this is not bound to a key. 1173 1174'quoted-insert (C-q or C-v)' 1175 Add the next character typed to the line verbatim. This is how to 1176 insert key sequences like 'C-q', for example. 1177 1178'tab-insert (M-<TAB>)' 1179 Insert a tab character. 1180 1181'self-insert (a, b, A, 1, !, ...)' 1182 Insert yourself. 1183 1184'bracketed-paste-begin ()' 1185 This function is intended to be bound to the "bracketed paste" 1186 escape sequence sent by some terminals, and such a binding is 1187 assigned by default. It allows Readline to insert the pasted text 1188 as a single unit without treating each character as if it had been 1189 read from the keyboard. The characters are inserted as if each one 1190 was bound to 'self-insert' instead of executing any editing 1191 commands. 1192 1193 Bracketed paste sets the region (the characters between point and 1194 the mark) to the inserted text. It uses the concept of an _active 1195 mark_: when the mark is active, Readline redisplay uses the 1196 terminal's standout mode to denote the region. 1197 1198'transpose-chars (C-t)' 1199 Drag the character before the cursor forward over the character at 1200 the cursor, moving the cursor forward as well. If the insertion 1201 point is at the end of the line, then this transposes the last two 1202 characters of the line. Negative arguments have no effect. 1203 1204'transpose-words (M-t)' 1205 Drag the word before point past the word after point, moving point 1206 past that word as well. If the insertion point is at the end of 1207 the line, this transposes the last two words on the line. 1208 1209'upcase-word (M-u)' 1210 Uppercase the current (or following) word. With a negative 1211 argument, uppercase the previous word, but do not move the cursor. 1212 1213'downcase-word (M-l)' 1214 Lowercase the current (or following) word. With a negative 1215 argument, lowercase the previous word, but do not move the cursor. 1216 1217'capitalize-word (M-c)' 1218 Capitalize the current (or following) word. With a negative 1219 argument, capitalize the previous word, but do not move the cursor. 1220 1221'overwrite-mode ()' 1222 Toggle overwrite mode. With an explicit positive numeric argument, 1223 switches to overwrite mode. With an explicit non-positive numeric 1224 argument, switches to insert mode. This command affects only 1225 'emacs' mode; 'vi' mode does overwrite differently. Each call to 1226 'readline()' starts in insert mode. 1227 1228 In overwrite mode, characters bound to 'self-insert' replace the 1229 text at point rather than pushing the text to the right. 1230 Characters bound to 'backward-delete-char' replace the character 1231 before point with a space. 1232 1233 By default, this command is unbound. 1234 1235 1236File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands 1237 12381.4.4 Killing And Yanking 1239------------------------- 1240 1241'kill-line (C-k)' 1242 Kill the text from point to the end of the line. With a negative 1243 numeric argument, kill backward from the cursor to the beginning of 1244 the current line. 1245 1246'backward-kill-line (C-x Rubout)' 1247 Kill backward from the cursor to the beginning of the current line. 1248 With a negative numeric argument, kill forward from the cursor to 1249 the end of the current line. 1250 1251'unix-line-discard (C-u)' 1252 Kill backward from the cursor to the beginning of the current line. 1253 1254'kill-whole-line ()' 1255 Kill all characters on the current line, no matter where point is. 1256 By default, this is unbound. 1257 1258'kill-word (M-d)' 1259 Kill from point to the end of the current word, or if between 1260 words, to the end of the next word. Word boundaries are the same 1261 as 'forward-word'. 1262 1263'backward-kill-word (M-<DEL>)' 1264 Kill the word behind point. Word boundaries are the same as 1265 'backward-word'. 1266 1267'shell-transpose-words (M-C-t)' 1268 Drag the word before point past the word after point, moving point 1269 past that word as well. If the insertion point is at the end of 1270 the line, this transposes the last two words on the line. Word 1271 boundaries are the same as 'shell-forward-word' and 1272 'shell-backward-word'. 1273 1274'unix-word-rubout (C-w)' 1275 Kill the word behind point, using white space as a word boundary. 1276 The killed text is saved on the kill-ring. 1277 1278'unix-filename-rubout ()' 1279 Kill the word behind point, using white space and the slash 1280 character as the word boundaries. The killed text is saved on the 1281 kill-ring. 1282 1283'delete-horizontal-space ()' 1284 Delete all spaces and tabs around point. By default, this is 1285 unbound. 1286 1287'kill-region ()' 1288 Kill the text in the current region. By default, this command is 1289 unbound. 1290 1291'copy-region-as-kill ()' 1292 Copy the text in the region to the kill buffer, so it can be yanked 1293 right away. By default, this command is unbound. 1294 1295'copy-backward-word ()' 1296 Copy the word before point to the kill buffer. The word boundaries 1297 are the same as 'backward-word'. By default, this command is 1298 unbound. 1299 1300'copy-forward-word ()' 1301 Copy the word following point to the kill buffer. The word 1302 boundaries are the same as 'forward-word'. By default, this 1303 command is unbound. 1304 1305'yank (C-y)' 1306 Yank the top of the kill ring into the buffer at point. 1307 1308'yank-pop (M-y)' 1309 Rotate the kill-ring, and yank the new top. You can only do this 1310 if the prior command is 'yank' or 'yank-pop'. 1311 1312 1313File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands 1314 13151.4.5 Specifying Numeric Arguments 1316---------------------------------- 1317 1318'digit-argument (M-0, M-1, ... M--)' 1319 Add this digit to the argument already accumulating, or start a new 1320 argument. 'M--' starts a negative argument. 1321 1322'universal-argument ()' 1323 This is another way to specify an argument. If this command is 1324 followed by one or more digits, optionally with a leading minus 1325 sign, those digits define the argument. If the command is followed 1326 by digits, executing 'universal-argument' again ends the numeric 1327 argument, but is otherwise ignored. As a special case, if this 1328 command is immediately followed by a character that is neither a 1329 digit nor minus sign, the argument count for the next command is 1330 multiplied by four. The argument count is initially one, so 1331 executing this function the first time makes the argument count 1332 four, a second time makes the argument count sixteen, and so on. 1333 By default, this is not bound to a key. 1334 1335 1336File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands 1337 13381.4.6 Letting Readline Type For You 1339----------------------------------- 1340 1341'complete (<TAB>)' 1342 Attempt to perform completion on the text before point. The actual 1343 completion performed is application-specific. The default is 1344 filename completion. 1345 1346'possible-completions (M-?)' 1347 List the possible completions of the text before point. When 1348 displaying completions, Readline sets the number of columns used 1349 for display to the value of 'completion-display-width', the value 1350 of the environment variable 'COLUMNS', or the screen width, in that 1351 order. 1352 1353'insert-completions (M-*)' 1354 Insert all completions of the text before point that would have 1355 been generated by 'possible-completions'. 1356 1357'menu-complete ()' 1358 Similar to 'complete', but replaces the word to be completed with a 1359 single match from the list of possible completions. Repeated 1360 execution of 'menu-complete' steps through the list of possible 1361 completions, inserting each match in turn. At the end of the list 1362 of completions, the bell is rung (subject to the setting of 1363 'bell-style') and the original text is restored. An argument of N 1364 moves N positions forward in the list of matches; a negative 1365 argument may be used to move backward through the list. This 1366 command is intended to be bound to <TAB>, but is unbound by 1367 default. 1368 1369'menu-complete-backward ()' 1370 Identical to 'menu-complete', but moves backward through the list 1371 of possible completions, as if 'menu-complete' had been given a 1372 negative argument. 1373 1374'delete-char-or-list ()' 1375 Deletes the character under the cursor if not at the beginning or 1376 end of the line (like 'delete-char'). If at the end of the line, 1377 behaves identically to 'possible-completions'. This command is 1378 unbound by default. 1379 1380 1381File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands 1382 13831.4.7 Keyboard Macros 1384--------------------- 1385 1386'start-kbd-macro (C-x ()' 1387 Begin saving the characters typed into the current keyboard macro. 1388 1389'end-kbd-macro (C-x ))' 1390 Stop saving the characters typed into the current keyboard macro 1391 and save the definition. 1392 1393'call-last-kbd-macro (C-x e)' 1394 Re-execute the last keyboard macro defined, by making the 1395 characters in the macro appear as if typed at the keyboard. 1396 1397'print-last-kbd-macro ()' 1398 Print the last keboard macro defined in a format suitable for the 1399 INPUTRC file. 1400 1401 1402File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands 1403 14041.4.8 Some Miscellaneous Commands 1405--------------------------------- 1406 1407're-read-init-file (C-x C-r)' 1408 Read in the contents of the INPUTRC file, and incorporate any 1409 bindings or variable assignments found there. 1410 1411'abort (C-g)' 1412 Abort the current editing command and ring the terminal's bell 1413 (subject to the setting of 'bell-style'). 1414 1415'do-lowercase-version (M-A, M-B, M-X, ...)' 1416 If the metafied character X is upper case, run the command that is 1417 bound to the corresponding metafied lower case character. The 1418 behavior is undefined if X is already lower case. 1419 1420'prefix-meta (<ESC>)' 1421 Metafy the next character typed. This is for keyboards without a 1422 meta key. Typing '<ESC> f' is equivalent to typing 'M-f'. 1423 1424'undo (C-_ or C-x C-u)' 1425 Incremental undo, separately remembered for each line. 1426 1427'revert-line (M-r)' 1428 Undo all changes made to this line. This is like executing the 1429 'undo' command enough times to get back to the beginning. 1430 1431'tilde-expand (M-~)' 1432 Perform tilde expansion on the current word. 1433 1434'set-mark (C-@)' 1435 Set the mark to the point. If a numeric argument is supplied, the 1436 mark is set to that position. 1437 1438'exchange-point-and-mark (C-x C-x)' 1439 Swap the point with the mark. The current cursor position is set 1440 to the saved position, and the old cursor position is saved as the 1441 mark. 1442 1443'character-search (C-])' 1444 A character is read and point is moved to the next occurrence of 1445 that character. A negative count searches for previous 1446 occurrences. 1447 1448'character-search-backward (M-C-])' 1449 A character is read and point is moved to the previous occurrence 1450 of that character. A negative count searches for subsequent 1451 occurrences. 1452 1453'skip-csi-sequence ()' 1454 Read enough characters to consume a multi-key sequence such as 1455 those defined for keys like Home and End. Such sequences begin 1456 with a Control Sequence Indicator (CSI), usually ESC-[. If this 1457 sequence is bound to "\e[", keys producing such sequences will have 1458 no effect unless explicitly bound to a readline command, instead of 1459 inserting stray characters into the editing buffer. This is 1460 unbound by default, but usually bound to ESC-[. 1461 1462'insert-comment (M-#)' 1463 Without a numeric argument, the value of the 'comment-begin' 1464 variable is inserted at the beginning of the current line. If a 1465 numeric argument is supplied, this command acts as a toggle: if the 1466 characters at the beginning of the line do not match the value of 1467 'comment-begin', the value is inserted, otherwise the characters in 1468 'comment-begin' are deleted from the beginning of the line. In 1469 either case, the line is accepted as if a newline had been typed. 1470 1471'dump-functions ()' 1472 Print all of the functions and their key bindings to the Readline 1473 output stream. If a numeric argument is supplied, the output is 1474 formatted in such a way that it can be made part of an INPUTRC 1475 file. This command is unbound by default. 1476 1477'dump-variables ()' 1478 Print all of the settable variables and their values to the 1479 Readline output stream. If a numeric argument is supplied, the 1480 output is formatted in such a way that it can be made part of an 1481 INPUTRC file. This command is unbound by default. 1482 1483'dump-macros ()' 1484 Print all of the Readline key sequences bound to macros and the 1485 strings they output. If a numeric argument is supplied, the output 1486 is formatted in such a way that it can be made part of an INPUTRC 1487 file. This command is unbound by default. 1488 1489'emacs-editing-mode (C-e)' 1490 When in 'vi' command mode, this causes a switch to 'emacs' editing 1491 mode. 1492 1493'vi-editing-mode (M-C-j)' 1494 When in 'emacs' editing mode, this causes a switch to 'vi' editing 1495 mode. 1496 1497 1498File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing 1499 15001.5 Readline vi Mode 1501==================== 1502 1503While the Readline library does not have a full set of 'vi' editing 1504functions, it does contain enough to allow simple editing of the line. 1505The Readline 'vi' mode behaves as specified in the POSIX standard. 1506 1507 In order to switch interactively between 'emacs' and 'vi' editing 1508modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' 1509mode and to vi-editing-mode in 'emacs' mode). The Readline default is 1510'emacs' mode. 1511 1512 When you enter a line in 'vi' mode, you are already placed in 1513'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches 1514you into 'command' mode, where you can edit the text of the line with 1515the standard 'vi' movement keys, move to previous history lines with 'k' 1516and subsequent lines with 'j', and so forth. 1517 1518 This document describes the GNU Readline Library, a utility for 1519aiding in the consistency of user interface across discrete programs 1520that need to provide a command line interface. 1521 1522 Copyright (C) 1988-2020 Free Software Foundation, Inc. 1523 1524 Permission is granted to make and distribute verbatim copies of this 1525manual provided the copyright notice and this permission notice pare 1526preserved on all copies. 1527 1528 Permission is granted to copy and distribute modified versions of 1529this manual under the conditions for verbatim copying, provided that the 1530entire resulting derived work is distributed under the terms of a 1531permission notice identical to this one. 1532 1533 Permission is granted to copy and distribute translations of this 1534manual into another language, under the above conditions for modified 1535versions, except that this permission notice may be stated in a 1536translation approved by the Foundation. 1537 1538 1539File: readline.info, Node: Programming with GNU Readline, Next: GNU Free Documentation License, Prev: Command Line Editing, Up: Top 1540 15412 Programming with GNU Readline 1542******************************* 1543 1544This chapter describes the interface between the GNU Readline Library 1545and other programs. If you are a programmer, and you wish to include 1546the features found in GNU Readline such as completion, line editing, and 1547interactive history manipulation in your own programs, this section is 1548for you. 1549 1550* Menu: 1551 1552* Basic Behavior:: Using the default behavior of Readline. 1553* Custom Functions:: Adding your own functions to Readline. 1554* Readline Variables:: Variables accessible to custom 1555 functions. 1556* Readline Convenience Functions:: Functions which Readline supplies to 1557 aid in writing your own custom 1558 functions. 1559* Readline Signal Handling:: How Readline behaves when it receives signals. 1560* Custom Completers:: Supplanting or supplementing Readline's 1561 completion functions. 1562 1563 1564File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline 1565 15662.1 Basic Behavior 1567================== 1568 1569Many programs provide a command line interface, such as 'mail', 'ftp', 1570and 'sh'. For such programs, the default behaviour of Readline is 1571sufficient. This section describes how to use Readline in the simplest 1572way possible, perhaps to replace calls in your code to 'gets()' or 1573'fgets()'. 1574 1575 The function 'readline()' prints a prompt PROMPT and then reads and 1576returns a single line of text from the user. If PROMPT is 'NULL' or the 1577empty string, no prompt is displayed. The line 'readline' returns is 1578allocated with 'malloc()'; the caller should 'free()' the line when it 1579has finished with it. The declaration for 'readline' in ANSI C is 1580 1581 char *readline (const char *PROMPT); 1582 1583So, one might say 1584 char *line = readline ("Enter a line: "); 1585in order to read a line of text from the user. The line returned has 1586the final newline removed, so only the text remains. 1587 1588 If 'readline' encounters an 'EOF' while reading the line, and the 1589line is empty at that point, then '(char *)NULL' is returned. 1590Otherwise, the line is ended just as if a newline had been typed. 1591 1592 Readline performs some expansion on the PROMPT before it is displayed 1593on the screen. See the description of 'rl_expand_prompt' (*note 1594Redisplay::) for additional details, especially if PROMPT will contain 1595characters that do not consume physical screen space when displayed. 1596 1597 If you want the user to be able to get at the line later, (with <C-p> 1598for example), you must call 'add_history()' to save the line away in a 1599"history" list of such lines. 1600 1601 add_history (line); 1602 1603For full details on the GNU History Library, see the associated manual. 1604 1605 It is preferable to avoid saving empty lines on the history list, 1606since users rarely have a burning need to reuse a blank line. Here is a 1607function which usefully replaces the standard 'gets()' library function, 1608and has the advantage of no static buffer to overflow: 1609 1610 /* A static variable for holding the line. */ 1611 static char *line_read = (char *)NULL; 1612 1613 /* Read a string, and return a pointer to it. 1614 Returns NULL on EOF. */ 1615 char * 1616 rl_gets () 1617 { 1618 /* If the buffer has already been allocated, 1619 return the memory to the free pool. */ 1620 if (line_read) 1621 { 1622 free (line_read); 1623 line_read = (char *)NULL; 1624 } 1625 1626 /* Get a line from the user. */ 1627 line_read = readline (""); 1628 1629 /* If the line has any text in it, 1630 save it on the history. */ 1631 if (line_read && *line_read) 1632 add_history (line_read); 1633 1634 return (line_read); 1635 } 1636 1637 This function gives the user the default behaviour of <TAB> 1638completion: completion on file names. If you do not want Readline to 1639complete on filenames, you can change the binding of the <TAB> key with 1640'rl_bind_key()'. 1641 1642 int rl_bind_key (int KEY, rl_command_func_t *FUNCTION); 1643 1644 'rl_bind_key()' takes two arguments: KEY is the character that you 1645want to bind, and FUNCTION is the address of the function to call when 1646KEY is pressed. Binding <TAB> to 'rl_insert()' makes <TAB> insert 1647itself. 'rl_bind_key()' returns non-zero if KEY is not a valid ASCII 1648character code (between 0 and 255). 1649 1650 Thus, to disable the default <TAB> behavior, the following suffices: 1651 rl_bind_key ('\t', rl_insert); 1652 1653 This code should be executed once at the start of your program; you 1654might write a function called 'initialize_readline()' which performs 1655this and other desired initializations, such as installing custom 1656completers (*note Custom Completers::). 1657 1658 1659File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline 1660 16612.2 Custom Functions 1662==================== 1663 1664Readline provides many functions for manipulating the text of the line, 1665but it isn't possible to anticipate the needs of all programs. This 1666section describes the various functions and variables defined within the 1667Readline library which allow a user program to add customized 1668functionality to Readline. 1669 1670 Before declaring any functions that customize Readline's behavior, or 1671using any functionality Readline provides in other code, an application 1672writer should include the file '<readline/readline.h>' in any file that 1673uses Readline's features. Since some of the definitions in 'readline.h' 1674use the 'stdio' library, the file '<stdio.h>' should be included before 1675'readline.h'. 1676 1677 'readline.h' defines a C preprocessor variable that should be treated 1678as an integer, 'RL_READLINE_VERSION', which may be used to conditionally 1679compile application code depending on the installed Readline version. 1680The value is a hexadecimal encoding of the major and minor version 1681numbers of the library, of the form 0xMMMM. MM is the two-digit major 1682version number; MM is the two-digit minor version number. For Readline 16834.2, for example, the value of 'RL_READLINE_VERSION' would be '0x0402'. 1684 1685* Menu: 1686 1687* Readline Typedefs:: C declarations to make code readable. 1688* Function Writing:: Variables and calling conventions. 1689 1690 1691File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions 1692 16932.2.1 Readline Typedefs 1694----------------------- 1695 1696For readability, we declare a number of new object types, all pointers 1697to functions. 1698 1699 The reason for declaring these new types is to make it easier to 1700write code describing pointers to C functions with appropriately 1701prototyped arguments and return values. 1702 1703 For instance, say we want to declare a variable FUNC as a pointer to 1704a function which takes two 'int' arguments and returns an 'int' (this is 1705the type of all of the Readline bindable functions). Instead of the 1706classic C declaration 1707 1708 'int (*func)();' 1709 1710or the ANSI-C style declaration 1711 1712 'int (*func)(int, int);' 1713 1714we may write 1715 1716 'rl_command_func_t *func;' 1717 1718 The full list of function pointer types available is 1719 1720'typedef int rl_command_func_t (int, int);' 1721 1722'typedef char *rl_compentry_func_t (const char *, int);' 1723 1724'typedef char **rl_completion_func_t (const char *, int, int);' 1725 1726'typedef char *rl_quote_func_t (char *, int, char *);' 1727 1728'typedef char *rl_dequote_func_t (char *, int);' 1729 1730'typedef int rl_compignore_func_t (char **);' 1731 1732'typedef void rl_compdisp_func_t (char **, int, int);' 1733 1734'typedef int rl_hook_func_t (void);' 1735 1736'typedef int rl_getc_func_t (FILE *);' 1737 1738'typedef int rl_linebuf_func_t (char *, int);' 1739 1740'typedef int rl_intfunc_t (int);' 1741'#define rl_ivoidfunc_t rl_hook_func_t' 1742'typedef int rl_icpfunc_t (char *);' 1743'typedef int rl_icppfunc_t (char **);' 1744 1745'typedef void rl_voidfunc_t (void);' 1746'typedef void rl_vintfunc_t (int);' 1747'typedef void rl_vcpfunc_t (char *);' 1748'typedef void rl_vcppfunc_t (char **);' 1749 1750 1751File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions 1752 17532.2.2 Writing a New Function 1754---------------------------- 1755 1756In order to write new functions for Readline, you need to know the 1757calling conventions for keyboard-invoked functions, and the names of the 1758variables that describe the current state of the line read so far. 1759 1760 The calling sequence for a command 'foo' looks like 1761 1762 int foo (int count, int key) 1763 1764where COUNT is the numeric argument (or 1 if defaulted) and KEY is the 1765key that invoked this function. 1766 1767 It is completely up to the function as to what should be done with 1768the numeric argument. Some functions use it as a repeat count, some as 1769a flag, and others to choose alternate behavior (refreshing the current 1770line as opposed to refreshing the screen, for example). Some choose to 1771ignore it. In general, if a function uses the numeric argument as a 1772repeat count, it should be able to do something useful with both 1773negative and positive arguments. At the very least, it should be aware 1774that it can be passed a negative argument. 1775 1776 A command function should return 0 if its action completes 1777successfully, and a value greater than zero if some error occurs. This 1778is the convention obeyed by all of the builtin Readline bindable command 1779functions. 1780 1781 1782File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline 1783 17842.3 Readline Variables 1785====================== 1786 1787These variables are available to function writers. 1788 1789 -- Variable: char * rl_line_buffer 1790 This is the line gathered so far. You are welcome to modify the 1791 contents of the line, but see *note Allowing Undoing::. The 1792 function 'rl_extend_line_buffer' is available to increase the 1793 memory allocated to 'rl_line_buffer'. 1794 1795 -- Variable: int rl_point 1796 The offset of the current cursor position in 'rl_line_buffer' (the 1797 _point_). 1798 1799 -- Variable: int rl_end 1800 The number of characters present in 'rl_line_buffer'. When 1801 'rl_point' is at the end of the line, 'rl_point' and 'rl_end' are 1802 equal. 1803 1804 -- Variable: int rl_mark 1805 The MARK (saved position) in the current line. If set, the mark 1806 and point define a _region_. 1807 1808 -- Variable: int rl_done 1809 Setting this to a non-zero value causes Readline to return the 1810 current line immediately. 1811 1812 -- Variable: int rl_num_chars_to_read 1813 Setting this to a positive value before calling 'readline()' causes 1814 Readline to return after accepting that many characters, rather 1815 than reading up to a character bound to 'accept-line'. 1816 1817 -- Variable: int rl_pending_input 1818 Setting this to a value makes it the next keystroke read. This is 1819 a way to stuff a single character into the input stream. 1820 1821 -- Variable: int rl_dispatching 1822 Set to a non-zero value if a function is being called from a key 1823 binding; zero otherwise. Application functions can test this to 1824 discover whether they were called directly or by Readline's 1825 dispatching mechanism. 1826 1827 -- Variable: int rl_erase_empty_line 1828 Setting this to a non-zero value causes Readline to completely 1829 erase the current line, including any prompt, any time a newline is 1830 typed as the only character on an otherwise-empty line. The cursor 1831 is moved to the beginning of the newly-blank line. 1832 1833 -- Variable: char * rl_prompt 1834 The prompt Readline uses. This is set from the argument to 1835 'readline()', and should not be assigned to directly. The 1836 'rl_set_prompt()' function (*note Redisplay::) may be used to 1837 modify the prompt string after calling 'readline()'. 1838 1839 -- Variable: char * rl_display_prompt 1840 The string displayed as the prompt. This is usually identical to 1841 RL_PROMPT, but may be changed temporarily by functions that use the 1842 prompt string as a message area, such as incremental search. 1843 1844 -- Variable: int rl_already_prompted 1845 If an application wishes to display the prompt itself, rather than 1846 have Readline do it the first time 'readline()' is called, it 1847 should set this variable to a non-zero value after displaying the 1848 prompt. The prompt must also be passed as the argument to 1849 'readline()' so the redisplay functions can update the display 1850 properly. The calling application is responsible for managing the 1851 value; Readline never sets it. 1852 1853 -- Variable: const char * rl_library_version 1854 The version number of this revision of the library. 1855 1856 -- Variable: int rl_readline_version 1857 An integer encoding the current version of the library. The 1858 encoding is of the form 0xMMMM, where MM is the two-digit major 1859 version number, and MM is the two-digit minor version number. For 1860 example, for Readline-4.2, 'rl_readline_version' would have the 1861 value 0x0402. 1862 1863 -- Variable: int rl_gnu_readline_p 1864 Always set to 1, denoting that this is GNU readline rather than 1865 some emulation. 1866 1867 -- Variable: const char * rl_terminal_name 1868 The terminal type, used for initialization. If not set by the 1869 application, Readline sets this to the value of the 'TERM' 1870 environment variable the first time it is called. 1871 1872 -- Variable: const char * rl_readline_name 1873 This variable is set to a unique name by each application using 1874 Readline. The value allows conditional parsing of the inputrc file 1875 (*note Conditional Init Constructs::). 1876 1877 -- Variable: FILE * rl_instream 1878 The stdio stream from which Readline reads input. If 'NULL', 1879 Readline defaults to STDIN. 1880 1881 -- Variable: FILE * rl_outstream 1882 The stdio stream to which Readline performs output. If 'NULL', 1883 Readline defaults to STDOUT. 1884 1885 -- Variable: int rl_prefer_env_winsize 1886 If non-zero, Readline gives values found in the 'LINES' and 1887 'COLUMNS' environment variables greater precedence than values 1888 fetched from the kernel when computing the screen dimensions. 1889 1890 -- Variable: rl_command_func_t * rl_last_func 1891 The address of the last command function Readline executed. May be 1892 used to test whether or not a function is being executed twice in 1893 succession, for example. 1894 1895 -- Variable: rl_hook_func_t * rl_startup_hook 1896 If non-zero, this is the address of a function to call just before 1897 'readline' prints the first prompt. 1898 1899 -- Variable: rl_hook_func_t * rl_pre_input_hook 1900 If non-zero, this is the address of a function to call after the 1901 first prompt has been printed and just before 'readline' starts 1902 reading input characters. 1903 1904 -- Variable: rl_hook_func_t * rl_event_hook 1905 If non-zero, this is the address of a function to call periodically 1906 when Readline is waiting for terminal input. By default, this will 1907 be called at most ten times a second if there is no keyboard input. 1908 1909 -- Variable: rl_getc_func_t * rl_getc_function 1910 If non-zero, Readline will call indirectly through this pointer to 1911 get a character from the input stream. By default, it is set to 1912 'rl_getc', the default Readline character input function (*note 1913 Character Input::). In general, an application that sets 1914 RL_GETC_FUNCTION should consider setting RL_INPUT_AVAILABLE_HOOK as 1915 well. 1916 1917 -- Variable: rl_hook_func_t * rl_signal_event_hook 1918 If non-zero, this is the address of a function to call if a read 1919 system call is interrupted when Readline is reading terminal input. 1920 1921 -- Variable: rl_hook_func_t * rl_input_available_hook 1922 If non-zero, Readline will use this function's return value when it 1923 needs to determine whether or not there is available input on the 1924 current input source. The default hook checks 'rl_instream'; if an 1925 application is using a different input source, it should set the 1926 hook appropriately. Readline queries for available input when 1927 implementing intra-key-sequence timeouts during input and 1928 incremental searches. This may use an application-specific timeout 1929 before returning a value; Readline uses the value passed to 1930 'rl_set_keyboard_input_timeout()' or the value of the user-settable 1931 KEYSEQ-TIMEOUT variable. This is designed for use by applications 1932 using Readline's callback interface (*note Alternate Interface::), 1933 which may not use the traditional 'read(2)' and file descriptor 1934 interface, or other applications using a different input mechanism. 1935 If an application uses an input mechanism or hook that can 1936 potentially exceed the value of KEYSEQ-TIMEOUT, it should increase 1937 the timeout or set this hook appropriately even when not using the 1938 callback interface. In general, an application that sets 1939 RL_GETC_FUNCTION should consider setting RL_INPUT_AVAILABLE_HOOK as 1940 well. 1941 1942 -- Variable: rl_voidfunc_t * rl_redisplay_function 1943 If non-zero, Readline will call indirectly through this pointer to 1944 update the display with the current contents of the editing buffer. 1945 By default, it is set to 'rl_redisplay', the default Readline 1946 redisplay function (*note Redisplay::). 1947 1948 -- Variable: rl_vintfunc_t * rl_prep_term_function 1949 If non-zero, Readline will call indirectly through this pointer to 1950 initialize the terminal. The function takes a single argument, an 1951 'int' flag that says whether or not to use eight-bit characters. 1952 By default, this is set to 'rl_prep_terminal' (*note Terminal 1953 Management::). 1954 1955 -- Variable: rl_voidfunc_t * rl_deprep_term_function 1956 If non-zero, Readline will call indirectly through this pointer to 1957 reset the terminal. This function should undo the effects of 1958 'rl_prep_term_function'. By default, this is set to 1959 'rl_deprep_terminal' (*note Terminal Management::). 1960 1961 -- Variable: Keymap rl_executing_keymap 1962 This variable is set to the keymap (*note Keymaps::) in which the 1963 currently executing readline function was found. 1964 1965 -- Variable: Keymap rl_binding_keymap 1966 This variable is set to the keymap (*note Keymaps::) in which the 1967 last key binding occurred. 1968 1969 -- Variable: char * rl_executing_macro 1970 This variable is set to the text of any currently-executing macro. 1971 1972 -- Variable: int rl_executing_key 1973 The key that caused the dispatch to the currently-executing 1974 Readline function. 1975 1976 -- Variable: char * rl_executing_keyseq 1977 The full key sequence that caused the dispatch to the 1978 currently-executing Readline function. 1979 1980 -- Variable: int rl_key_sequence_length 1981 The number of characters in RL_EXECUTING_KEYSEQ. 1982 1983 -- Variable: int rl_readline_state 1984 A variable with bit values that encapsulate the current Readline 1985 state. A bit is set with the 'RL_SETSTATE' macro, and unset with 1986 the 'RL_UNSETSTATE' macro. Use the 'RL_ISSTATE' macro to test 1987 whether a particular state bit is set. Current state bits include: 1988 1989 'RL_STATE_NONE' 1990 Readline has not yet been called, nor has it begun to 1991 initialize. 1992 'RL_STATE_INITIALIZING' 1993 Readline is initializing its internal data structures. 1994 'RL_STATE_INITIALIZED' 1995 Readline has completed its initialization. 1996 'RL_STATE_TERMPREPPED' 1997 Readline has modified the terminal modes to do its own input 1998 and redisplay. 1999 'RL_STATE_READCMD' 2000 Readline is reading a command from the keyboard. 2001 'RL_STATE_METANEXT' 2002 Readline is reading more input after reading the meta-prefix 2003 character. 2004 'RL_STATE_DISPATCHING' 2005 Readline is dispatching to a command. 2006 'RL_STATE_MOREINPUT' 2007 Readline is reading more input while executing an editing 2008 command. 2009 'RL_STATE_ISEARCH' 2010 Readline is performing an incremental history search. 2011 'RL_STATE_NSEARCH' 2012 Readline is performing a non-incremental history search. 2013 'RL_STATE_SEARCH' 2014 Readline is searching backward or forward through the history 2015 for a string. 2016 'RL_STATE_NUMERICARG' 2017 Readline is reading a numeric argument. 2018 'RL_STATE_MACROINPUT' 2019 Readline is currently getting its input from a 2020 previously-defined keyboard macro. 2021 'RL_STATE_MACRODEF' 2022 Readline is currently reading characters defining a keyboard 2023 macro. 2024 'RL_STATE_OVERWRITE' 2025 Readline is in overwrite mode. 2026 'RL_STATE_COMPLETING' 2027 Readline is performing word completion. 2028 'RL_STATE_SIGHANDLER' 2029 Readline is currently executing the readline signal handler. 2030 'RL_STATE_UNDOING' 2031 Readline is performing an undo. 2032 'RL_STATE_INPUTPENDING' 2033 Readline has input pending due to a call to 2034 'rl_execute_next()'. 2035 'RL_STATE_TTYCSAVED' 2036 Readline has saved the values of the terminal's special 2037 characters. 2038 'RL_STATE_CALLBACK' 2039 Readline is currently using the alternate (callback) interface 2040 (*note Alternate Interface::). 2041 'RL_STATE_VIMOTION' 2042 Readline is reading the argument to a vi-mode "motion" 2043 command. 2044 'RL_STATE_MULTIKEY' 2045 Readline is reading a multiple-keystroke command. 2046 'RL_STATE_VICMDONCE' 2047 Readline has entered vi command (movement) mode at least one 2048 time during the current call to 'readline()'. 2049 'RL_STATE_DONE' 2050 Readline has read a key sequence bound to 'accept-line' and is 2051 about to return the line to the caller. 2052 2053 -- Variable: int rl_explicit_arg 2054 Set to a non-zero value if an explicit numeric argument was 2055 specified by the user. Only valid in a bindable command function. 2056 2057 -- Variable: int rl_numeric_arg 2058 Set to the value of any numeric argument explicitly specified by 2059 the user before executing the current Readline function. Only 2060 valid in a bindable command function. 2061 2062 -- Variable: int rl_editing_mode 2063 Set to a value denoting Readline's current editing mode. A value 2064 of 1 means Readline is currently in emacs mode; 0 means that vi 2065 mode is active. 2066 2067 2068File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline 2069 20702.4 Readline Convenience Functions 2071================================== 2072 2073* Menu: 2074 2075* Function Naming:: How to give a function you write a name. 2076* Keymaps:: Making keymaps. 2077* Binding Keys:: Changing Keymaps. 2078* Associating Function Names and Bindings:: Translate function names to 2079 key sequences. 2080* Allowing Undoing:: How to make your functions undoable. 2081* Redisplay:: Functions to control line display. 2082* Modifying Text:: Functions to modify 'rl_line_buffer'. 2083* Character Input:: Functions to read keyboard input. 2084* Terminal Management:: Functions to manage terminal settings. 2085* Utility Functions:: Generally useful functions and hooks. 2086* Miscellaneous Functions:: Functions that don't fall into any category. 2087* Alternate Interface:: Using Readline in a 'callback' fashion. 2088* A Readline Example:: An example Readline function. 2089* Alternate Interface Example:: An example program using the alternate interface. 2090 2091 2092File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions 2093 20942.4.1 Naming a Function 2095----------------------- 2096 2097The user can dynamically change the bindings of keys while using 2098Readline. This is done by representing the function with a descriptive 2099name. The user is able to type the descriptive name when referring to 2100the function. Thus, in an init file, one might find 2101 2102 Meta-Rubout: backward-kill-word 2103 2104 This binds the keystroke <Meta-Rubout> to the function 2105_descriptively_ named 'backward-kill-word'. You, as the programmer, 2106should bind the functions you write to descriptive names as well. 2107Readline provides a function for doing that: 2108 2109 -- Function: int rl_add_defun (const char *name, rl_command_func_t 2110 *function, int key) 2111 Add NAME to the list of named functions. Make FUNCTION be the 2112 function that gets called. If KEY is not -1, then bind it to 2113 FUNCTION using 'rl_bind_key()'. 2114 2115 Using this function alone is sufficient for most applications. It is 2116the recommended way to add a few functions to the default functions that 2117Readline has built in. If you need to do something other than adding a 2118function to Readline, you may need to use the underlying functions 2119described below. 2120 2121 2122File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions 2123 21242.4.2 Selecting a Keymap 2125------------------------ 2126 2127Key bindings take place on a "keymap". The keymap is the association 2128between the keys that the user types and the functions that get run. 2129You can make your own keymaps, copy existing keymaps, and tell Readline 2130which keymap to use. 2131 2132 -- Function: Keymap rl_make_bare_keymap (void) 2133 Returns a new, empty keymap. The space for the keymap is allocated 2134 with 'malloc()'; the caller should free it by calling 2135 'rl_free_keymap()' when done. 2136 2137 -- Function: Keymap rl_copy_keymap (Keymap map) 2138 Return a new keymap which is a copy of MAP. 2139 2140 -- Function: Keymap rl_make_keymap (void) 2141 Return a new keymap with the printing characters bound to 2142 rl_insert, the lowercase Meta characters bound to run their 2143 equivalents, and the Meta digits bound to produce numeric 2144 arguments. 2145 2146 -- Function: void rl_discard_keymap (Keymap keymap) 2147 Free the storage associated with the data in KEYMAP. The caller 2148 should free KEYMAP. 2149 2150 -- Function: void rl_free_keymap (Keymap keymap) 2151 Free all storage associated with KEYMAP. This calls 2152 'rl_discard_keymap' to free subordindate keymaps and macros. 2153 2154 -- Function: int rl_empty_keymap (Keymap keymap) 2155 Return non-zero if there are no keys bound to functions in KEYMAP; 2156 zero if there are any keys bound. 2157 2158 Readline has several internal keymaps. These functions allow you to 2159change which keymap is active. 2160 2161 -- Function: Keymap rl_get_keymap (void) 2162 Returns the currently active keymap. 2163 2164 -- Function: void rl_set_keymap (Keymap keymap) 2165 Makes KEYMAP the currently active keymap. 2166 2167 -- Function: Keymap rl_get_keymap_by_name (const char *name) 2168 Return the keymap matching NAME. NAME is one which would be 2169 supplied in a 'set keymap' inputrc line (*note Readline Init 2170 File::). 2171 2172 -- Function: char * rl_get_keymap_name (Keymap keymap) 2173 Return the name matching KEYMAP. NAME is one which would be 2174 supplied in a 'set keymap' inputrc line (*note Readline Init 2175 File::). 2176 2177 -- Function: int rl_set_keymap_name (const char *name, Keymap keymap) 2178 Set the name of KEYMAP. This name will then be "registered" and 2179 available for use in a 'set keymap' inputrc directive *note 2180 Readline Init File::). The NAME may not be one of Readline's 2181 builtin keymap names; you may not add a different name for one of 2182 Readline's builtin keymaps. You may replace the name associated 2183 with a given keymap by calling this function more than once with 2184 the same KEYMAP argument. You may associate a registered NAME with 2185 a new keymap by calling this function more than once with the same 2186 NAME argument. There is no way to remove a named keymap once the 2187 name has been registered. Readline will make a copy of NAME. The 2188 return value is greater than zero unless NAME is one of Readline's 2189 builtin keymap names or KEYMAP is one of Readline's builtin 2190 keymaps. 2191 2192 2193File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions 2194 21952.4.3 Binding Keys 2196------------------ 2197 2198Key sequences are associate with functions through the keymap. Readline 2199has several internal keymaps: 'emacs_standard_keymap', 2200'emacs_meta_keymap', 'emacs_ctlx_keymap', 'vi_movement_keymap', and 2201'vi_insertion_keymap'. 'emacs_standard_keymap' is the default, and the 2202examples in this manual assume that. 2203 2204 Since 'readline()' installs a set of default key bindings the first 2205time it is called, there is always the danger that a custom binding 2206installed before the first call to 'readline()' will be overridden. An 2207alternate mechanism is to install custom key bindings in an 2208initialization function assigned to the 'rl_startup_hook' variable 2209(*note Readline Variables::). 2210 2211 These functions manage key bindings. 2212 2213 -- Function: int rl_bind_key (int key, rl_command_func_t *function) 2214 Binds KEY to FUNCTION in the currently active keymap. Returns 2215 non-zero in the case of an invalid KEY. 2216 2217 -- Function: int rl_bind_key_in_map (int key, rl_command_func_t 2218 *function, Keymap map) 2219 Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an 2220 invalid KEY. 2221 2222 -- Function: int rl_bind_key_if_unbound (int key, rl_command_func_t 2223 *function) 2224 Binds KEY to FUNCTION if it is not already bound in the currently 2225 active keymap. Returns non-zero in the case of an invalid KEY or 2226 if KEY is already bound. 2227 2228 -- Function: int rl_bind_key_if_unbound_in_map (int key, 2229 rl_command_func_t *function, Keymap map) 2230 Binds KEY to FUNCTION if it is not already bound in MAP. Returns 2231 non-zero in the case of an invalid KEY or if KEY is already bound. 2232 2233 -- Function: int rl_unbind_key (int key) 2234 Bind KEY to the null function in the currently active keymap. 2235 Returns non-zero in case of error. 2236 2237 -- Function: int rl_unbind_key_in_map (int key, Keymap map) 2238 Bind KEY to the null function in MAP. Returns non-zero in case of 2239 error. 2240 2241 -- Function: int rl_unbind_function_in_map (rl_command_func_t 2242 *function, Keymap map) 2243 Unbind all keys that execute FUNCTION in MAP. 2244 2245 -- Function: int rl_unbind_command_in_map (const char *command, Keymap 2246 map) 2247 Unbind all keys that are bound to COMMAND in MAP. 2248 2249 -- Function: int rl_bind_keyseq (const char *keyseq, rl_command_func_t 2250 *function) 2251 Bind the key sequence represented by the string KEYSEQ to the 2252 function FUNCTION, beginning in the current keymap. This makes new 2253 keymaps as necessary. The return value is non-zero if KEYSEQ is 2254 invalid. 2255 2256 -- Function: int rl_bind_keyseq_in_map (const char *keyseq, 2257 rl_command_func_t *function, Keymap map) 2258 Bind the key sequence represented by the string KEYSEQ to the 2259 function FUNCTION. This makes new keymaps as necessary. Initial 2260 bindings are performed in MAP. The return value is non-zero if 2261 KEYSEQ is invalid. 2262 2263 -- Function: int rl_set_key (const char *keyseq, rl_command_func_t 2264 *function, Keymap map) 2265 Equivalent to 'rl_bind_keyseq_in_map'. 2266 2267 -- Function: int rl_bind_keyseq_if_unbound (const char *keyseq, 2268 rl_command_func_t *function) 2269 Binds KEYSEQ to FUNCTION if it is not already bound in the 2270 currently active keymap. Returns non-zero in the case of an 2271 invalid KEYSEQ or if KEYSEQ is already bound. 2272 2273 -- Function: int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, 2274 rl_command_func_t *function, Keymap map) 2275 Binds KEYSEQ to FUNCTION if it is not already bound in MAP. 2276 Returns non-zero in the case of an invalid KEYSEQ or if KEYSEQ is 2277 already bound. 2278 2279 -- Function: int rl_generic_bind (int type, const char *keyseq, char 2280 *data, Keymap map) 2281 Bind the key sequence represented by the string KEYSEQ to the 2282 arbitrary pointer DATA. TYPE says what kind of data is pointed to 2283 by DATA; this can be a function ('ISFUNC'), a macro ('ISMACR'), or 2284 a keymap ('ISKMAP'). This makes new keymaps as necessary. The 2285 initial keymap in which to do bindings is MAP. 2286 2287 -- Function: int rl_parse_and_bind (char *line) 2288 Parse LINE as if it had been read from the 'inputrc' file and 2289 perform any key bindings and variable assignments found (*note 2290 Readline Init File::). 2291 2292 -- Function: int rl_read_init_file (const char *filename) 2293 Read keybindings and variable assignments from FILENAME (*note 2294 Readline Init File::). 2295 2296 2297File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions 2298 22992.4.4 Associating Function Names and Bindings 2300--------------------------------------------- 2301 2302These functions allow you to find out what keys invoke named functions 2303and the functions invoked by a particular key sequence. You may also 2304associate a new function name with an arbitrary function. 2305 2306 -- Function: rl_command_func_t * rl_named_function (const char *name) 2307 Return the function with name NAME. 2308 2309 -- Function: rl_command_func_t * rl_function_of_keyseq (const char 2310 *keyseq, Keymap map, int *type) 2311 Return the function invoked by KEYSEQ in keymap MAP. If MAP is 2312 'NULL', the current keymap is used. If TYPE is not 'NULL', the 2313 type of the object is returned in the 'int' variable it points to 2314 (one of 'ISFUNC', 'ISKMAP', or 'ISMACR'). It takes a "translated" 2315 key sequence and should not be used if the key sequence can include 2316 NUL. 2317 2318 -- Function: rl_command_func_t * rl_function_of_keyseq_len (const char 2319 *keyseq, size_t len, Keymap map, int *type) 2320 Return the function invoked by KEYSEQ of length LEN in keymap MAP. 2321 Equivalent to 'rl_function_of_keyseq' with the addition of the LEN 2322 parameter. It takes a "translated" key sequence and should be used 2323 if the key sequence can include NUL. 2324 2325 -- Function: char ** rl_invoking_keyseqs (rl_command_func_t *function) 2326 Return an array of strings representing the key sequences used to 2327 invoke FUNCTION in the current keymap. 2328 2329 -- Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t 2330 *function, Keymap map) 2331 Return an array of strings representing the key sequences used to 2332 invoke FUNCTION in the keymap MAP. 2333 2334 -- Function: void rl_function_dumper (int readable) 2335 Print the readline function names and the key sequences currently 2336 bound to them to 'rl_outstream'. If READABLE is non-zero, the list 2337 is formatted in such a way that it can be made part of an 'inputrc' 2338 file and re-read. 2339 2340 -- Function: void rl_list_funmap_names (void) 2341 Print the names of all bindable Readline functions to 2342 'rl_outstream'. 2343 2344 -- Function: const char ** rl_funmap_names (void) 2345 Return a NULL terminated array of known function names. The array 2346 is sorted. The array itself is allocated, but not the strings 2347 inside. You should free the array, but not the pointers, using 2348 'free' or 'rl_free' when you are done. 2349 2350 -- Function: int rl_add_funmap_entry (const char *name, 2351 rl_command_func_t *function) 2352 Add NAME to the list of bindable Readline command names, and make 2353 FUNCTION the function to be called when NAME is invoked. 2354 2355 2356File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions 2357 23582.4.5 Allowing Undoing 2359---------------------- 2360 2361Supporting the undo command is a painless thing, and makes your 2362functions much more useful. It is certainly easy to try something if 2363you know you can undo it. 2364 2365 If your function simply inserts text once, or deletes text once, and 2366uses 'rl_insert_text()' or 'rl_delete_text()' to do it, then undoing is 2367already done for you automatically. 2368 2369 If you do multiple insertions or multiple deletions, or any 2370combination of these operations, you should group them together into one 2371operation. This is done with 'rl_begin_undo_group()' and 2372'rl_end_undo_group()'. 2373 2374 The types of events that can be undone are: 2375 2376 enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END }; 2377 2378 Notice that 'UNDO_DELETE' means to insert some text, and 2379'UNDO_INSERT' means to delete some text. That is, the undo code tells 2380what to undo, not how to undo it. 'UNDO_BEGIN' and 'UNDO_END' are tags 2381added by 'rl_begin_undo_group()' and 'rl_end_undo_group()'. 2382 2383 -- Function: int rl_begin_undo_group (void) 2384 Begins saving undo information in a group construct. The undo 2385 information usually comes from calls to 'rl_insert_text()' and 2386 'rl_delete_text()', but could be the result of calls to 2387 'rl_add_undo()'. 2388 2389 -- Function: int rl_end_undo_group (void) 2390 Closes the current undo group started with 'rl_begin_undo_group 2391 ()'. There should be one call to 'rl_end_undo_group()' for each 2392 call to 'rl_begin_undo_group()'. 2393 2394 -- Function: void rl_add_undo (enum undo_code what, int start, int end, 2395 char *text) 2396 Remember how to undo an event (according to WHAT). The affected 2397 text runs from START to END, and encompasses TEXT. 2398 2399 -- Function: void rl_free_undo_list (void) 2400 Free the existing undo list. 2401 2402 -- Function: int rl_do_undo (void) 2403 Undo the first thing on the undo list. Returns '0' if there was 2404 nothing to undo, non-zero if something was undone. 2405 2406 Finally, if you neither insert nor delete text, but directly modify 2407the existing text (e.g., change its case), call 'rl_modifying()' once, 2408just before you modify the text. You must supply the indices of the 2409text range that you are going to modify. 2410 2411 -- Function: int rl_modifying (int start, int end) 2412 Tell Readline to save the text between START and END as a single 2413 undo unit. It is assumed that you will subsequently modify that 2414 text. 2415 2416 2417File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions 2418 24192.4.6 Redisplay 2420--------------- 2421 2422 -- Function: void rl_redisplay (void) 2423 Change what's displayed on the screen to reflect the current 2424 contents of 'rl_line_buffer'. 2425 2426 -- Function: int rl_forced_update_display (void) 2427 Force the line to be updated and redisplayed, whether or not 2428 Readline thinks the screen display is correct. 2429 2430 -- Function: int rl_on_new_line (void) 2431 Tell the update functions that we have moved onto a new (empty) 2432 line, usually after outputting a newline. 2433 2434 -- Function: int rl_on_new_line_with_prompt (void) 2435 Tell the update functions that we have moved onto a new line, with 2436 RL_PROMPT already displayed. This could be used by applications 2437 that want to output the prompt string themselves, but still need 2438 Readline to know the prompt string length for redisplay. It should 2439 be used after setting RL_ALREADY_PROMPTED. 2440 2441 -- Function: int rl_clear_visible_line (void) 2442 Clear the screen lines corresponding to the current line's 2443 contents. 2444 2445 -- Function: int rl_reset_line_state (void) 2446 Reset the display state to a clean state and redisplay the current 2447 line starting on a new line. 2448 2449 -- Function: int rl_crlf (void) 2450 Move the cursor to the start of the next screen line. 2451 2452 -- Function: int rl_show_char (int c) 2453 Display character C on 'rl_outstream'. If Readline has not been 2454 set to display meta characters directly, this will convert meta 2455 characters to a meta-prefixed key sequence. This is intended for 2456 use by applications which wish to do their own redisplay. 2457 2458 -- Function: int rl_message (const char *, ...) 2459 The arguments are a format string as would be supplied to 'printf', 2460 possibly containing conversion specifications such as '%d', and any 2461 additional arguments necessary to satisfy the conversion 2462 specifications. The resulting string is displayed in the "echo 2463 area". The echo area is also used to display numeric arguments and 2464 search strings. You should call 'rl_save_prompt' to save the 2465 prompt information before calling this function. 2466 2467 -- Function: int rl_clear_message (void) 2468 Clear the message in the echo area. If the prompt was saved with a 2469 call to 'rl_save_prompt' before the last call to 'rl_message', call 2470 'rl_restore_prompt' before calling this function. 2471 2472 -- Function: void rl_save_prompt (void) 2473 Save the local Readline prompt display state in preparation for 2474 displaying a new message in the message area with 'rl_message()'. 2475 2476 -- Function: void rl_restore_prompt (void) 2477 Restore the local Readline prompt display state saved by the most 2478 recent call to 'rl_save_prompt'. if 'rl_save_prompt' was called to 2479 save the prompt before a call to 'rl_message', this function should 2480 be called before the corresponding call to 'rl_clear_message'. 2481 2482 -- Function: int rl_expand_prompt (char *prompt) 2483 Expand any special character sequences in PROMPT and set up the 2484 local Readline prompt redisplay variables. This function is called 2485 by 'readline()'. It may also be called to expand the primary 2486 prompt if the 'rl_on_new_line_with_prompt()' function or 2487 'rl_already_prompted' variable is used. It returns the number of 2488 visible characters on the last line of the (possibly multi-line) 2489 prompt. Applications may indicate that the prompt contains 2490 characters that take up no physical screen space when displayed by 2491 bracketing a sequence of such characters with the special markers 2492 'RL_PROMPT_START_IGNORE' and 'RL_PROMPT_END_IGNORE' (declared in 2493 'readline.h'). This may be used to embed terminal-specific escape 2494 sequences in prompts. 2495 2496 -- Function: int rl_set_prompt (const char *prompt) 2497 Make Readline use PROMPT for subsequent redisplay. This calls 2498 'rl_expand_prompt()' to expand the prompt and sets 'rl_prompt' to 2499 the result. 2500 2501 2502File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions 2503 25042.4.7 Modifying Text 2505-------------------- 2506 2507 -- Function: int rl_insert_text (const char *text) 2508 Insert TEXT into the line at the current cursor position. Returns 2509 the number of characters inserted. 2510 2511 -- Function: int rl_delete_text (int start, int end) 2512 Delete the text between START and END in the current line. Returns 2513 the number of characters deleted. 2514 2515 -- Function: char * rl_copy_text (int start, int end) 2516 Return a copy of the text between START and END in the current 2517 line. 2518 2519 -- Function: int rl_kill_text (int start, int end) 2520 Copy the text between START and END in the current line to the kill 2521 ring, appending or prepending to the last kill if the last command 2522 was a kill command. The text is deleted. If START is less than 2523 END, the text is appended, otherwise prepended. If the last 2524 command was not a kill, a new kill ring slot is used. 2525 2526 -- Function: int rl_push_macro_input (char *macro) 2527 Cause MACRO to be inserted into the line, as if it had been invoked 2528 by a key bound to a macro. Not especially useful; use 2529 'rl_insert_text()' instead. 2530 2531 2532File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions 2533 25342.4.8 Character Input 2535--------------------- 2536 2537 -- Function: int rl_read_key (void) 2538 Return the next character available from Readline's current input 2539 stream. This handles input inserted into the input stream via 2540 RL_PENDING_INPUT (*note Readline Variables::) and 2541 'rl_stuff_char()', macros, and characters read from the keyboard. 2542 While waiting for input, this function will call any function 2543 assigned to the 'rl_event_hook' variable. 2544 2545 -- Function: int rl_getc (FILE *stream) 2546 Return the next character available from STREAM, which is assumed 2547 to be the keyboard. 2548 2549 -- Function: int rl_stuff_char (int c) 2550 Insert C into the Readline input stream. It will be "read" before 2551 Readline attempts to read characters from the terminal with 2552 'rl_read_key()'. Up to 512 characters may be pushed back. 2553 'rl_stuff_char' returns 1 if the character was successfully 2554 inserted; 0 otherwise. 2555 2556 -- Function: int rl_execute_next (int c) 2557 Make C be the next command to be executed when 'rl_read_key()' is 2558 called. This sets RL_PENDING_INPUT. 2559 2560 -- Function: int rl_clear_pending_input (void) 2561 Unset RL_PENDING_INPUT, effectively negating the effect of any 2562 previous call to 'rl_execute_next()'. This works only if the 2563 pending input has not already been read with 'rl_read_key()'. 2564 2565 -- Function: int rl_set_keyboard_input_timeout (int u) 2566 While waiting for keyboard input in 'rl_read_key()', Readline will 2567 wait for U microseconds for input before calling any function 2568 assigned to 'rl_event_hook'. U must be greater than or equal to 2569 zero (a zero-length timeout is equivalent to a poll). The default 2570 waiting period is one-tenth of a second. Returns the old timeout 2571 value. 2572 2573 2574File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions 2575 25762.4.9 Terminal Management 2577------------------------- 2578 2579 -- Function: void rl_prep_terminal (int meta_flag) 2580 Modify the terminal settings for Readline's use, so 'readline()' 2581 can read a single character at a time from the keyboard. The 2582 META_FLAG argument should be non-zero if Readline should read 2583 eight-bit input. 2584 2585 -- Function: void rl_deprep_terminal (void) 2586 Undo the effects of 'rl_prep_terminal()', leaving the terminal in 2587 the state in which it was before the most recent call to 2588 'rl_prep_terminal()'. 2589 2590 -- Function: void rl_tty_set_default_bindings (Keymap kmap) 2591 Read the operating system's terminal editing characters (as would 2592 be displayed by 'stty') to their Readline equivalents. The 2593 bindings are performed in KMAP. 2594 2595 -- Function: void rl_tty_unset_default_bindings (Keymap kmap) 2596 Reset the bindings manipulated by 'rl_tty_set_default_bindings' so 2597 that the terminal editing characters are bound to 'rl_insert'. The 2598 bindings are performed in KMAP. 2599 2600 -- Function: int rl_tty_set_echoing (int value) 2601 Set Readline's idea of whether or not it is echoing output to its 2602 output stream (RL_OUTSTREAM). If VALUE is 0, Readline does not 2603 display output to RL_OUTSTREAM; any other value enables output. 2604 The initial value is set when Readline initializes the terminal 2605 settings. This function returns the previous value. 2606 2607 -- Function: int rl_reset_terminal (const char *terminal_name) 2608 Reinitialize Readline's idea of the terminal settings using 2609 TERMINAL_NAME as the terminal type (e.g., 'vt100'). If 2610 TERMINAL_NAME is 'NULL', the value of the 'TERM' environment 2611 variable is used. 2612 2613 2614File: readline.info, Node: Utility Functions, Next: Miscellaneous Functions, Prev: Terminal Management, Up: Readline Convenience Functions 2615 26162.4.10 Utility Functions 2617------------------------ 2618 2619 -- Function: int rl_save_state (struct readline_state *sp) 2620 Save a snapshot of Readline's internal state to SP. The contents 2621 of the READLINE_STATE structure are documented in 'readline.h'. 2622 The caller is responsible for allocating the structure. 2623 2624 -- Function: int rl_restore_state (struct readline_state *sp) 2625 Restore Readline's internal state to that stored in SP, which must 2626 have been saved by a call to 'rl_save_state'. The contents of the 2627 READLINE_STATE structure are documented in 'readline.h'. The 2628 caller is responsible for freeing the structure. 2629 2630 -- Function: void rl_free (void *mem) 2631 Deallocate the memory pointed to by MEM. MEM must have been 2632 allocated by 'malloc'. 2633 2634 -- Function: void rl_replace_line (const char *text, int clear_undo) 2635 Replace the contents of 'rl_line_buffer' with TEXT. The point and 2636 mark are preserved, if possible. If CLEAR_UNDO is non-zero, the 2637 undo list associated with the current line is cleared. 2638 2639 -- Function: void rl_extend_line_buffer (int len) 2640 Ensure that 'rl_line_buffer' has enough space to hold LEN 2641 characters, possibly reallocating it if necessary. 2642 2643 -- Function: int rl_initialize (void) 2644 Initialize or re-initialize Readline's internal state. It's not 2645 strictly necessary to call this; 'readline()' calls it before 2646 reading any input. 2647 2648 -- Function: int rl_ding (void) 2649 Ring the terminal bell, obeying the setting of 'bell-style'. 2650 2651 -- Function: int rl_alphabetic (int c) 2652 Return 1 if C is an alphabetic character. 2653 2654 -- Function: void rl_display_match_list (char **matches, int len, int 2655 max) 2656 A convenience function for displaying a list of strings in columnar 2657 format on Readline's output stream. 'matches' is the list of 2658 strings, in argv format, such as a list of completion matches. 2659 'len' is the number of strings in 'matches', and 'max' is the 2660 length of the longest string in 'matches'. This function uses the 2661 setting of 'print-completions-horizontally' to select how the 2662 matches are displayed (*note Readline Init File Syntax::). When 2663 displaying completions, this function sets the number of columns 2664 used for display to the value of 'completion-display-width', the 2665 value of the environment variable 'COLUMNS', or the screen width, 2666 in that order. 2667 2668 The following are implemented as macros, defined in 'chardefs.h'. 2669Applications should refrain from using them. 2670 2671 -- Function: int _rl_uppercase_p (int c) 2672 Return 1 if C is an uppercase alphabetic character. 2673 2674 -- Function: int _rl_lowercase_p (int c) 2675 Return 1 if C is a lowercase alphabetic character. 2676 2677 -- Function: int _rl_digit_p (int c) 2678 Return 1 if C is a numeric character. 2679 2680 -- Function: int _rl_to_upper (int c) 2681 If C is a lowercase alphabetic character, return the corresponding 2682 uppercase character. 2683 2684 -- Function: int _rl_to_lower (int c) 2685 If C is an uppercase alphabetic character, return the corresponding 2686 lowercase character. 2687 2688 -- Function: int _rl_digit_value (int c) 2689 If C is a number, return the value it represents. 2690 2691 2692File: readline.info, Node: Miscellaneous Functions, Next: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions 2693 26942.4.11 Miscellaneous Functions 2695------------------------------ 2696 2697 -- Function: int rl_macro_bind (const char *keyseq, const char *macro, 2698 Keymap map) 2699 Bind the key sequence KEYSEQ to invoke the macro MACRO. The 2700 binding is performed in MAP. When KEYSEQ is invoked, the MACRO 2701 will be inserted into the line. This function is deprecated; use 2702 'rl_generic_bind()' instead. 2703 2704 -- Function: void rl_macro_dumper (int readable) 2705 Print the key sequences bound to macros and their values, using the 2706 current keymap, to 'rl_outstream'. If READABLE is non-zero, the 2707 list is formatted in such a way that it can be made part of an 2708 'inputrc' file and re-read. 2709 2710 -- Function: int rl_variable_bind (const char *variable, const char 2711 *value) 2712 Make the Readline variable VARIABLE have VALUE. This behaves as if 2713 the readline command 'set VARIABLE VALUE' had been executed in an 2714 'inputrc' file (*note Readline Init File Syntax::). 2715 2716 -- Function: char * rl_variable_value (const char *variable) 2717 Return a string representing the value of the Readline variable 2718 VARIABLE. For boolean variables, this string is either 'on' or 2719 'off'. 2720 2721 -- Function: void rl_variable_dumper (int readable) 2722 Print the readline variable names and their current values to 2723 'rl_outstream'. If READABLE is non-zero, the list is formatted in 2724 such a way that it can be made part of an 'inputrc' file and 2725 re-read. 2726 2727 -- Function: int rl_set_paren_blink_timeout (int u) 2728 Set the time interval (in microseconds) that Readline waits when 2729 showing a balancing character when 'blink-matching-paren' has been 2730 enabled. 2731 2732 -- Function: char * rl_get_termcap (const char *cap) 2733 Retrieve the string value of the termcap capability CAP. Readline 2734 fetches the termcap entry for the current terminal name and uses 2735 those capabilities to move around the screen line and perform other 2736 terminal-specific operations, like erasing a line. Readline does 2737 not use all of a terminal's capabilities, and this function will 2738 return values for only those capabilities Readline uses. 2739 2740 -- Function: void rl_clear_history (void) 2741 Clear the history list by deleting all of the entries, in the same 2742 manner as the History library's 'clear_history()' function. This 2743 differs from 'clear_history' because it frees private data Readline 2744 saves in the history list. 2745 2746 -- Function: void rl_activate_mark (void) 2747 Enable an _active_ mark. When this is enabled, the text between 2748 point and mark (the REGION) is displayed in the terminal's standout 2749 mode (a FACE). This is called by various readline functions that 2750 set the mark and insert text, and is available for applications to 2751 call. 2752 2753 -- Function: void rl_deactivate_mark (void) 2754 Turn off the active mark. 2755 2756 -- Function: void rl_keep_mark_active (void) 2757 Indicate that the mark should remain active when the current 2758 readline function completes and after redisplay occurs. In most 2759 cases, the mark remains active for only the duration of a single 2760 bindable readline function. 2761 2762 -- Function: int rl_mark_active_p (void) 2763 Return a non-zero value if the mark is currently active; zero 2764 otherwise. 2765 2766 2767File: readline.info, Node: Alternate Interface, Next: A Readline Example, Prev: Miscellaneous Functions, Up: Readline Convenience Functions 2768 27692.4.12 Alternate Interface 2770-------------------------- 2771 2772An alternate interface is available to plain 'readline()'. Some 2773applications need to interleave keyboard I/O with file, device, or 2774window system I/O, typically by using a main loop to 'select()' on 2775various file descriptors. To accommodate this need, readline can also 2776be invoked as a 'callback' function from an event loop. There are 2777functions available to make this easy. 2778 2779 -- Function: void rl_callback_handler_install (const char *prompt, 2780 rl_vcpfunc_t *lhandler) 2781 Set up the terminal for readline I/O and display the initial 2782 expanded value of PROMPT. Save the value of LHANDLER to use as a 2783 handler function to call when a complete line of input has been 2784 entered. The handler function receives the text of the line as an 2785 argument. As with 'readline()', the handler function should 'free' 2786 the line when it it finished with it. 2787 2788 -- Function: void rl_callback_read_char (void) 2789 Whenever an application determines that keyboard input is 2790 available, it should call 'rl_callback_read_char()', which will 2791 read the next character from the current input source. If that 2792 character completes the line, 'rl_callback_read_char' will invoke 2793 the LHANDLER function installed by 'rl_callback_handler_install' to 2794 process the line. Before calling the LHANDLER function, the 2795 terminal settings are reset to the values they had before calling 2796 'rl_callback_handler_install'. If the LHANDLER function returns, 2797 and the line handler remains installed, the terminal settings are 2798 modified for Readline's use again. 'EOF' is indicated by calling 2799 LHANDLER with a 'NULL' line. 2800 2801 -- Function: void rl_callback_sigcleanup (void) 2802 Clean up any internal state the callback interface uses to maintain 2803 state between calls to rl_callback_read_char (e.g., the state of 2804 any active incremental searches). This is intended to be used by 2805 applications that wish to perform their own signal handling; 2806 Readline's internal signal handler calls this when appropriate. 2807 2808 -- Function: void rl_callback_handler_remove (void) 2809 Restore the terminal to its initial state and remove the line 2810 handler. You may call this function from within a callback as well 2811 as independently. If the LHANDLER installed by 2812 'rl_callback_handler_install' does not exit the program, either 2813 this function or the function referred to by the value of 2814 'rl_deprep_term_function' should be called before the program exits 2815 to reset the terminal settings. 2816 2817 2818File: readline.info, Node: A Readline Example, Next: Alternate Interface Example, Prev: Alternate Interface, Up: Readline Convenience Functions 2819 28202.4.13 A Readline Example 2821------------------------- 2822 2823Here is a function which changes lowercase characters to their uppercase 2824equivalents, and uppercase characters to lowercase. If this function 2825was bound to 'M-c', then typing 'M-c' would change the case of the 2826character under point. Typing 'M-1 0 M-c' would change the case of the 2827following 10 characters, leaving the cursor on the last character 2828changed. 2829 2830 /* Invert the case of the COUNT following characters. */ 2831 int 2832 invert_case_line (count, key) 2833 int count, key; 2834 { 2835 register int start, end, i; 2836 2837 start = rl_point; 2838 2839 if (rl_point >= rl_end) 2840 return (0); 2841 2842 if (count < 0) 2843 { 2844 direction = -1; 2845 count = -count; 2846 } 2847 else 2848 direction = 1; 2849 2850 /* Find the end of the range to modify. */ 2851 end = start + (count * direction); 2852 2853 /* Force it to be within range. */ 2854 if (end > rl_end) 2855 end = rl_end; 2856 else if (end < 0) 2857 end = 0; 2858 2859 if (start == end) 2860 return (0); 2861 2862 if (start > end) 2863 { 2864 int temp = start; 2865 start = end; 2866 end = temp; 2867 } 2868 2869 /* Tell readline that we are modifying the line, 2870 so it will save the undo information. */ 2871 rl_modifying (start, end); 2872 2873 for (i = start; i != end; i++) 2874 { 2875 if (_rl_uppercase_p (rl_line_buffer[i])) 2876 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); 2877 else if (_rl_lowercase_p (rl_line_buffer[i])) 2878 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); 2879 } 2880 /* Move point to on top of the last character changed. */ 2881 rl_point = (direction == 1) ? end - 1 : start; 2882 return (0); 2883 } 2884 2885 2886File: readline.info, Node: Alternate Interface Example, Prev: A Readline Example, Up: Readline Convenience Functions 2887 28882.4.14 Alternate Interface Example 2889---------------------------------- 2890 2891Here is a complete program that illustrates Readline's alternate 2892interface. It reads lines from the terminal and displays them, 2893providing the standard history and TAB completion functions. It 2894understands the EOF character or "exit" to exit the program. 2895 2896 /* Standard include files. stdio.h is required. */ 2897 #include <stdlib.h> 2898 #include <string.h> 2899 #include <unistd.h> 2900 #include <locale.h> 2901 2902 /* Used for select(2) */ 2903 #include <sys/types.h> 2904 #include <sys/select.h> 2905 2906 #include <signal.h> 2907 2908 #include <stdio.h> 2909 2910 /* Standard readline include files. */ 2911 #include <readline/readline.h> 2912 #include <readline/history.h> 2913 2914 static void cb_linehandler (char *); 2915 static void sighandler (int); 2916 2917 int running; 2918 int sigwinch_received; 2919 const char *prompt = "rltest$ "; 2920 2921 /* Handle SIGWINCH and window size changes when readline is not active and 2922 reading a character. */ 2923 static void 2924 sighandler (int sig) 2925 { 2926 sigwinch_received = 1; 2927 } 2928 2929 /* Callback function called for each line when accept-line executed, EOF 2930 seen, or EOF character read. This sets a flag and returns; it could 2931 also call exit(3). */ 2932 static void 2933 cb_linehandler (char *line) 2934 { 2935 /* Can use ^D (stty eof) or `exit' to exit. */ 2936 if (line == NULL || strcmp (line, "exit") == 0) 2937 { 2938 if (line == 0) 2939 printf ("\n"); 2940 printf ("exit\n"); 2941 /* This function needs to be called to reset the terminal settings, 2942 and calling it from the line handler keeps one extra prompt from 2943 being displayed. */ 2944 rl_callback_handler_remove (); 2945 2946 running = 0; 2947 } 2948 else 2949 { 2950 if (*line) 2951 add_history (line); 2952 printf ("input line: %s\n", line); 2953 free (line); 2954 } 2955 } 2956 2957 int 2958 main (int c, char **v) 2959 { 2960 fd_set fds; 2961 int r; 2962 2963 /* Set the default locale values according to environment variables. */ 2964 setlocale (LC_ALL, ""); 2965 2966 /* Handle window size changes when readline is not active and reading 2967 characters. */ 2968 signal (SIGWINCH, sighandler); 2969 2970 /* Install the line handler. */ 2971 rl_callback_handler_install (prompt, cb_linehandler); 2972 2973 /* Enter a simple event loop. This waits until something is available 2974 to read on readline's input stream (defaults to standard input) and 2975 calls the builtin character read callback to read it. It does not 2976 have to modify the user's terminal settings. */ 2977 running = 1; 2978 while (running) 2979 { 2980 FD_ZERO (&fds); 2981 FD_SET (fileno (rl_instream), &fds); 2982 2983 r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); 2984 if (r < 0 && errno != EINTR) 2985 { 2986 perror ("rltest: select"); 2987 rl_callback_handler_remove (); 2988 break; 2989 } 2990 if (sigwinch_received) 2991 { 2992 rl_resize_terminal (); 2993 sigwinch_received = 0; 2994 } 2995 if (r < 0) 2996 continue; 2997 2998 if (FD_ISSET (fileno (rl_instream), &fds)) 2999 rl_callback_read_char (); 3000 } 3001 3002 printf ("rltest: Event loop has exited\n"); 3003 return 0; 3004 } 3005 3006 3007File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline 3008 30092.5 Readline Signal Handling 3010============================ 3011 3012Signals are asynchronous events sent to a process by the Unix kernel, 3013sometimes on behalf of another process. They are intended to indicate 3014exceptional events, like a user pressing the interrupt key on his 3015terminal, or a network connection being broken. There is a class of 3016signals that can be sent to the process currently reading input from the 3017keyboard. Since Readline changes the terminal attributes when it is 3018called, it needs to perform special processing when such a signal is 3019received in order to restore the terminal to a sane state, or provide 3020application writers with functions to do so manually. 3021 3022 Readline contains an internal signal handler that is installed for a 3023number of signals ('SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGALRM', 3024'SIGTSTP', 'SIGTTIN', and 'SIGTTOU'). When one of these signals is 3025received, the signal handler will reset the terminal attributes to those 3026that were in effect before 'readline()' was called, reset the signal 3027handling to what it was before 'readline()' was called, and resend the 3028signal to the calling application. If and when the calling 3029application's signal handler returns, Readline will reinitialize the 3030terminal and continue to accept input. When a 'SIGINT' is received, the 3031Readline signal handler performs some additional work, which will cause 3032any partially-entered line to be aborted (see the description of 3033'rl_free_line_state()' below). 3034 3035 There is an additional Readline signal handler, for 'SIGWINCH', which 3036the kernel sends to a process whenever the terminal's size changes (for 3037example, if a user resizes an 'xterm'). The Readline 'SIGWINCH' handler 3038updates Readline's internal screen size information, and then calls any 3039'SIGWINCH' signal handler the calling application has installed. 3040Readline calls the application's 'SIGWINCH' signal handler without 3041resetting the terminal to its original state. If the application's 3042signal handler does more than update its idea of the terminal size and 3043return (for example, a 'longjmp' back to a main processing loop), it 3044_must_ call 'rl_cleanup_after_signal()' (described below), to restore 3045the terminal state. 3046 3047 When an application is using the callback interface (*note Alternate 3048Interface::), Readline installs signal handlers only for the duration of 3049the call to 'rl_callback_read_char'. Applications using the callback 3050interface should be prepared to clean up Readline's state if they wish 3051to handle the signal before the line handler completes and restores the 3052terminal state. 3053 3054 If an application using the callback interface wishes to have 3055Readline install its signal handlers at the time the application calls 3056'rl_callback_handler_install' and remove them only when a complete line 3057of input has been read, it should set the 3058'rl_persistent_signal_handlers' variable to a non-zero value. This 3059allows an application to defer all of the handling of the signals 3060Readline catches to Readline. Applications should use this variable 3061with care; it can result in Readline catching signals and not acting on 3062them (or allowing the application to react to them) until the 3063application calls 'rl_callback_read_char'. This can result in an 3064application becoming less responsive to keyboard signals like SIGINT. If 3065an application does not want or need to perform any signal handling, or 3066does not need to do any processing between calls to 3067'rl_callback_read_char', setting this variable may be desirable. 3068 3069 Readline provides two variables that allow application writers to 3070control whether or not it will catch certain signals and act on them 3071when they are received. It is important that applications change the 3072values of these variables only when calling 'readline()', not in a 3073signal handler, so Readline's internal signal state is not corrupted. 3074 3075 -- Variable: int rl_catch_signals 3076 If this variable is non-zero, Readline will install signal handlers 3077 for 'SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGALRM', 'SIGTSTP', 3078 'SIGTTIN', and 'SIGTTOU'. 3079 3080 The default value of 'rl_catch_signals' is 1. 3081 3082 -- Variable: int rl_catch_sigwinch 3083 If this variable is set to a non-zero value, Readline will install 3084 a signal handler for 'SIGWINCH'. 3085 3086 The default value of 'rl_catch_sigwinch' is 1. 3087 3088 -- Variable: int rl_persistent_signal_handlers 3089 If an application using the callback interface wishes Readline's 3090 signal handlers to be installed and active during the set of calls 3091 to 'rl_callback_read_char' that constitutes an entire single line, 3092 it should set this variable to a non-zero value. 3093 3094 The default value of 'rl_persistent_signal_handlers' is 0. 3095 3096 -- Variable: int rl_change_environment 3097 If this variable is set to a non-zero value, and Readline is 3098 handling 'SIGWINCH', Readline will modify the LINES and COLUMNS 3099 environment variables upon receipt of a 'SIGWINCH' 3100 3101 The default value of 'rl_change_environment' is 1. 3102 3103 If an application does not wish to have Readline catch any signals, 3104or to handle signals other than those Readline catches ('SIGHUP', for 3105example), Readline provides convenience functions to do the necessary 3106terminal and internal state cleanup upon receipt of a signal. 3107 3108 -- Function: int rl_pending_signal (void) 3109 Return the signal number of the most recent signal Readline 3110 received but has not yet handled, or 0 if there is no pending 3111 signal. 3112 3113 -- Function: void rl_cleanup_after_signal (void) 3114 This function will reset the state of the terminal to what it was 3115 before 'readline()' was called, and remove the Readline signal 3116 handlers for all signals, depending on the values of 3117 'rl_catch_signals' and 'rl_catch_sigwinch'. 3118 3119 -- Function: void rl_free_line_state (void) 3120 This will free any partial state associated with the current input 3121 line (undo information, any partial history entry, any 3122 partially-entered keyboard macro, and any partially-entered numeric 3123 argument). This should be called before 3124 'rl_cleanup_after_signal()'. The Readline signal handler for 3125 'SIGINT' calls this to abort the current input line. 3126 3127 -- Function: void rl_reset_after_signal (void) 3128 This will reinitialize the terminal and reinstall any Readline 3129 signal handlers, depending on the values of 'rl_catch_signals' and 3130 'rl_catch_sigwinch'. 3131 3132 If an application wants to force Readline to handle any signals that 3133have arrived while it has been executing, 'rl_check_signals()' will call 3134Readline's internal signal handler if there are any pending signals. 3135This is primarily intended for those applications that use a custom 3136'rl_getc_function' (*note Readline Variables::) and wish to handle 3137signals received while waiting for input. 3138 3139 -- Function: void rl_check_signals (void) 3140 If there are any pending signals, call Readline's internal signal 3141 handling functions to process them. 'rl_pending_signal()' can be 3142 used independently to determine whether or not there are any 3143 pending signals. 3144 3145 If an application does not wish Readline to catch 'SIGWINCH', it may 3146call 'rl_resize_terminal()' or 'rl_set_screen_size()' to force Readline 3147to update its idea of the terminal size when it receives a 'SIGWINCH'. 3148 3149 -- Function: void rl_echo_signal_char (int sig) 3150 If an application wishes to install its own signal handlers, but 3151 still have readline display characters that generate signals, 3152 calling this function with SIG set to 'SIGINT', 'SIGQUIT', or 3153 'SIGTSTP' will display the character generating that signal. 3154 3155 -- Function: void rl_resize_terminal (void) 3156 Update Readline's internal screen size by reading values from the 3157 kernel. 3158 3159 -- Function: void rl_set_screen_size (int rows, int cols) 3160 Set Readline's idea of the terminal size to ROWS rows and COLS 3161 columns. If either ROWS or COLUMNS is less than or equal to 0, 3162 Readline's idea of that terminal dimension is unchanged. This is 3163 intended to tell Readline the physical dimensions of the terminal, 3164 and is used internally to calculate the maximum number of 3165 characters that may appear on a single line and on the screen. 3166 3167 If an application does not want to install a 'SIGWINCH' handler, but 3168is still interested in the screen dimensions, it may query Readline's 3169idea of the screen size. 3170 3171 -- Function: void rl_get_screen_size (int *rows, int *cols) 3172 Return Readline's idea of the terminal's size in the variables 3173 pointed to by the arguments. 3174 3175 -- Function: void rl_reset_screen_size (void) 3176 Cause Readline to reobtain the screen size and recalculate its 3177 dimensions. 3178 3179 The following functions install and remove Readline's signal 3180handlers. 3181 3182 -- Function: int rl_set_signals (void) 3183 Install Readline's signal handler for 'SIGINT', 'SIGQUIT', 3184 'SIGTERM', 'SIGHUP', 'SIGALRM', 'SIGTSTP', 'SIGTTIN', 'SIGTTOU', 3185 and 'SIGWINCH', depending on the values of 'rl_catch_signals' and 3186 'rl_catch_sigwinch'. 3187 3188 -- Function: int rl_clear_signals (void) 3189 Remove all of the Readline signal handlers installed by 3190 'rl_set_signals()'. 3191 3192 3193File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline 3194 31952.6 Custom Completers 3196===================== 3197 3198Typically, a program that reads commands from the user has a way of 3199disambiguating commands and data. If your program is one of these, then 3200it can provide completion for commands, data, or both. The following 3201sections describe how your program and Readline cooperate to provide 3202this service. 3203 3204* Menu: 3205 3206* How Completing Works:: The logic used to do completion. 3207* Completion Functions:: Functions provided by Readline. 3208* Completion Variables:: Variables which control completion. 3209* A Short Completion Example:: An example of writing completer subroutines. 3210 3211 3212File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers 3213 32142.6.1 How Completing Works 3215-------------------------- 3216 3217In order to complete some text, the full list of possible completions 3218must be available. That is, it is not possible to accurately expand a 3219partial word without knowing all of the possible words which make sense 3220in that context. The Readline library provides the user interface to 3221completion, and two of the most common completion functions: filename 3222and username. For completing other types of text, you must write your 3223own completion function. This section describes exactly what such 3224functions must do, and provides an example. 3225 3226 There are three major functions used to perform completion: 3227 3228 1. The user-interface function 'rl_complete()'. This function is 3229 called with the same arguments as other bindable Readline 3230 functions: COUNT and INVOKING_KEY. It isolates the word to be 3231 completed and calls 'rl_completion_matches()' to generate a list of 3232 possible completions. It then either lists the possible 3233 completions, inserts the possible completions, or actually performs 3234 the completion, depending on which behavior is desired. 3235 3236 2. The internal function 'rl_completion_matches()' uses an 3237 application-supplied "generator" function to generate the list of 3238 possible matches, and then returns the array of these matches. The 3239 caller should place the address of its generator function in 3240 'rl_completion_entry_function'. 3241 3242 3. The generator function is called repeatedly from 3243 'rl_completion_matches()', returning a string each time. The 3244 arguments to the generator function are TEXT and STATE. TEXT is 3245 the partial word to be completed. STATE is zero the first time the 3246 function is called, allowing the generator to perform any necessary 3247 initialization, and a positive non-zero integer for each subsequent 3248 call. The generator function returns '(char *)NULL' to inform 3249 'rl_completion_matches()' that there are no more possibilities 3250 left. Usually the generator function computes the list of possible 3251 completions when STATE is zero, and returns them one at a time on 3252 subsequent calls. Each string the generator function returns as a 3253 match must be allocated with 'malloc()'; Readline frees the strings 3254 when it has finished with them. Such a generator function is 3255 referred to as an "application-specific completion function". 3256 3257 -- Function: int rl_complete (int ignore, int invoking_key) 3258 Complete the word at or before point. You have supplied the 3259 function that does the initial simple matching selection algorithm 3260 (see 'rl_completion_matches()'). The default is to do filename 3261 completion. 3262 3263 -- Variable: rl_compentry_func_t * rl_completion_entry_function 3264 This is a pointer to the generator function for 3265 'rl_completion_matches()'. If the value of 3266 'rl_completion_entry_function' is 'NULL' then the default filename 3267 generator function, 'rl_filename_completion_function()', is used. 3268 An "application-specific completion function" is a function whose 3269 address is assigned to 'rl_completion_entry_function' and whose 3270 return values are used to generate possible completions. 3271 3272 3273File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers 3274 32752.6.2 Completion Functions 3276-------------------------- 3277 3278Here is the complete list of callable completion functions present in 3279Readline. 3280 3281 -- Function: int rl_complete_internal (int what_to_do) 3282 Complete the word at or before point. WHAT_TO_DO says what to do 3283 with the completion. A value of '?' means list the possible 3284 completions. 'TAB' means do standard completion. '*' means insert 3285 all of the possible completions. '!' means to display all of the 3286 possible completions, if there is more than one, as well as 3287 performing partial completion. '@' is similar to '!', but possible 3288 completions are not listed if the possible completions share a 3289 common prefix. 3290 3291 -- Function: int rl_complete (int ignore, int invoking_key) 3292 Complete the word at or before point. You have supplied the 3293 function that does the initial simple matching selection algorithm 3294 (see 'rl_completion_matches()' and 'rl_completion_entry_function'). 3295 The default is to do filename completion. This calls 3296 'rl_complete_internal()' with an argument depending on 3297 INVOKING_KEY. 3298 3299 -- Function: int rl_possible_completions (int count, int invoking_key) 3300 List the possible completions. See description of 'rl_complete 3301 ()'. This calls 'rl_complete_internal()' with an argument of '?'. 3302 3303 -- Function: int rl_insert_completions (int count, int invoking_key) 3304 Insert the list of possible completions into the line, deleting the 3305 partially-completed word. See description of 'rl_complete()'. 3306 This calls 'rl_complete_internal()' with an argument of '*'. 3307 3308 -- Function: int rl_completion_mode (rl_command_func_t *cfunc) 3309 Returns the appropriate value to pass to 'rl_complete_internal()' 3310 depending on whether CFUNC was called twice in succession and the 3311 values of the 'show-all-if-ambiguous' and 'show-all-if-unmodified' 3312 variables. Application-specific completion functions may use this 3313 function to present the same interface as 'rl_complete()'. 3314 3315 -- Function: char ** rl_completion_matches (const char *text, 3316 rl_compentry_func_t *entry_func) 3317 Returns an array of strings which is a list of completions for 3318 TEXT. If there are no completions, returns 'NULL'. The first 3319 entry in the returned array is the substitution for TEXT. The 3320 remaining entries are the possible completions. The array is 3321 terminated with a 'NULL' pointer. 3322 3323 ENTRY_FUNC is a function of two args, and returns a 'char *'. The 3324 first argument is TEXT. The second is a state argument; it is zero 3325 on the first call, and non-zero on subsequent calls. ENTRY_FUNC 3326 returns a 'NULL' pointer to the caller when there are no more 3327 matches. 3328 3329 -- Function: char * rl_filename_completion_function (const char *text, 3330 int state) 3331 A generator function for filename completion in the general case. 3332 TEXT is a partial filename. The Bash source is a useful reference 3333 for writing application-specific completion functions (the Bash 3334 completion functions call this and other Readline functions). 3335 3336 -- Function: char * rl_username_completion_function (const char *text, 3337 int state) 3338 A completion generator for usernames. TEXT contains a partial 3339 username preceded by a random character (usually '~'). As with all 3340 completion generators, STATE is zero on the first call and non-zero 3341 for subsequent calls. 3342 3343 3344File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers 3345 33462.6.3 Completion Variables 3347-------------------------- 3348 3349 -- Variable: rl_compentry_func_t * rl_completion_entry_function 3350 A pointer to the generator function for 'rl_completion_matches()'. 3351 'NULL' means to use 'rl_filename_completion_function()', the 3352 default filename completer. 3353 3354 -- Variable: rl_completion_func_t * rl_attempted_completion_function 3355 A pointer to an alternative function to create matches. The 3356 function is called with TEXT, START, and END. START and END are 3357 indices in 'rl_line_buffer' defining the boundaries of TEXT, which 3358 is a character string. If this function exists and returns 'NULL', 3359 or if this variable is set to 'NULL', then 'rl_complete()' will 3360 call the value of 'rl_completion_entry_function' to generate 3361 matches, otherwise the array of strings returned will be used. If 3362 this function sets the 'rl_attempted_completion_over' variable to a 3363 non-zero value, Readline will not perform its default completion 3364 even if this function returns no matches. 3365 3366 -- Variable: rl_quote_func_t * rl_filename_quoting_function 3367 A pointer to a function that will quote a filename in an 3368 application-specific fashion. This is called if filename 3369 completion is being attempted and one of the characters in 3370 'rl_filename_quote_characters' appears in a completed filename. 3371 The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER. 3372 The TEXT is the filename to be quoted. The MATCH_TYPE is either 3373 'SINGLE_MATCH', if there is only one completion match, or 3374 'MULT_MATCH'. Some functions use this to decide whether or not to 3375 insert a closing quote character. The QUOTE_POINTER is a pointer 3376 to any opening quote character the user typed. Some functions 3377 choose to reset this character. 3378 3379 -- Variable: rl_dequote_func_t * rl_filename_dequoting_function 3380 A pointer to a function that will remove application-specific 3381 quoting characters from a filename before completion is attempted, 3382 so those characters do not interfere with matching the text against 3383 names in the filesystem. It is called with TEXT, the text of the 3384 word to be dequoted, and QUOTE_CHAR, which is the quoting character 3385 that delimits the filename (usually ''' or '"'). If QUOTE_CHAR is 3386 zero, the filename was not in an embedded string. 3387 3388 -- Variable: rl_linebuf_func_t * rl_char_is_quoted_p 3389 A pointer to a function to call that determines whether or not a 3390 specific character in the line buffer is quoted, according to 3391 whatever quoting mechanism the program calling Readline uses. The 3392 function is called with two arguments: TEXT, the text of the line, 3393 and INDEX, the index of the character in the line. It is used to 3394 decide whether a character found in 3395 'rl_completer_word_break_characters' should be used to break words 3396 for the completer. 3397 3398 -- Variable: rl_compignore_func_t * rl_ignore_some_completions_function 3399 This function, if defined, is called by the completer when real 3400 filename completion is done, after all the matching names have been 3401 generated. It is passed a 'NULL' terminated array of matches. The 3402 first element ('matches[0]') is the maximal substring common to all 3403 matches. This function can re-arrange the list of matches as 3404 required, but each element deleted from the array must be freed. 3405 3406 -- Variable: rl_icppfunc_t * rl_directory_completion_hook 3407 This function, if defined, is allowed to modify the directory 3408 portion of filenames Readline completes. It could be used to 3409 expand symbolic links or shell variables in pathnames. It is 3410 called with the address of a string (the current directory name) as 3411 an argument, and may modify that string. If the string is replaced 3412 with a new string, the old value should be freed. Any modified 3413 directory name should have a trailing slash. The modified value 3414 will be used as part of the completion, replacing the directory 3415 portion of the pathname the user typed. At the least, even if no 3416 other expansion is performed, this function should remove any quote 3417 characters from the directory name, because its result will be 3418 passed directly to 'opendir()'. 3419 3420 The directory completion hook returns an integer that should be 3421 non-zero if the function modifies its directory argument. The 3422 function should not modify the directory argument if it returns 0. 3423 3424 -- Variable: rl_icppfunc_t * rl_directory_rewrite_hook; 3425 If non-zero, this is the address of a function to call when 3426 completing a directory name. This function takes the address of 3427 the directory name to be modified as an argument. Unlike 3428 'rl_directory_completion_hook', it only modifies the directory name 3429 used in 'opendir', not what is displayed when the possible 3430 completions are printed or inserted. It is called before 3431 rl_directory_completion_hook. At the least, even if no other 3432 expansion is performed, this function should remove any quote 3433 characters from the directory name, because its result will be 3434 passed directly to 'opendir()'. 3435 3436 The directory rewrite hook returns an integer that should be 3437 non-zero if the function modifies its directory argument. The 3438 function should not modify the directory argument if it returns 0. 3439 3440 -- Variable: rl_icppfunc_t * rl_filename_stat_hook 3441 If non-zero, this is the address of a function for the completer to 3442 call before deciding which character to append to a completed name. 3443 This function modifies its filename name argument, and the modified 3444 value is passed to 'stat()' to determine the file's type and 3445 characteristics. This function does not need to remove quote 3446 characters from the filename. 3447 3448 The stat hook returns an integer that should be non-zero if the 3449 function modifies its directory argument. The function should not 3450 modify the directory argument if it returns 0. 3451 3452 -- Variable: rl_dequote_func_t * rl_filename_rewrite_hook 3453 If non-zero, this is the address of a function called when reading 3454 directory entries from the filesystem for completion and comparing 3455 them to the partial word to be completed. The function should 3456 perform any necessary application or system-specific conversion on 3457 the filename, such as converting between character sets or 3458 converting from a filesystem format to a character input format. 3459 The function takes two arguments: FNAME, the filename to be 3460 converted, and FNLEN, its length in bytes. It must either return 3461 its first argument (if no conversion takes place) or the converted 3462 filename in newly-allocated memory. The converted form is used to 3463 compare against the word to be completed, and, if it matches, is 3464 added to the list of matches. Readline will free the allocated 3465 string. 3466 3467 -- Variable: rl_compdisp_func_t * rl_completion_display_matches_hook 3468 If non-zero, then this is the address of a function to call when 3469 completing a word would normally display the list of possible 3470 matches. This function is called in lieu of Readline displaying 3471 the list. It takes three arguments: ('char **'MATCHES, 'int' 3472 NUM_MATCHES, 'int' MAX_LENGTH) where MATCHES is the array of 3473 matching strings, NUM_MATCHES is the number of strings in that 3474 array, and MAX_LENGTH is the length of the longest string in that 3475 array. Readline provides a convenience function, 3476 'rl_display_match_list', that takes care of doing the display to 3477 Readline's output stream. You may call that function from this 3478 hook. 3479 3480 -- Variable: const char * rl_basic_word_break_characters 3481 The basic list of characters that signal a break between words for 3482 the completer routine. The default value of this variable is the 3483 characters which break words for completion in Bash: '" 3484 \t\n\"\\'`@$><=;|&{("'. 3485 3486 -- Variable: const char * rl_basic_quote_characters 3487 A list of quote characters which can cause a word break. 3488 3489 -- Variable: const char * rl_completer_word_break_characters 3490 The list of characters that signal a break between words for 3491 'rl_complete_internal()'. The default list is the value of 3492 'rl_basic_word_break_characters'. 3493 3494 -- Variable: rl_cpvfunc_t * rl_completion_word_break_hook 3495 If non-zero, this is the address of a function to call when 3496 Readline is deciding where to separate words for word completion. 3497 It should return a character string like 3498 'rl_completer_word_break_characters' to be used to perform the 3499 current completion. The function may choose to set 3500 'rl_completer_word_break_characters' itself. If the function 3501 returns 'NULL', 'rl_completer_word_break_characters' is used. 3502 3503 -- Variable: const char * rl_completer_quote_characters 3504 A list of characters which can be used to quote a substring of the 3505 line. Completion occurs on the entire substring, and within the 3506 substring 'rl_completer_word_break_characters' are treated as any 3507 other character, unless they also appear within this list. 3508 3509 -- Variable: const char * rl_filename_quote_characters 3510 A list of characters that cause a filename to be quoted by the 3511 completer when they appear in a completed filename. The default is 3512 the null string. 3513 3514 -- Variable: const char * rl_special_prefixes 3515 The list of characters that are word break characters, but should 3516 be left in TEXT when it is passed to the completion function. 3517 Programs can use this to help determine what kind of completing to 3518 do. For instance, Bash sets this variable to "$@" so that it can 3519 complete shell variables and hostnames. 3520 3521 -- Variable: int rl_completion_query_items 3522 Up to this many items will be displayed in response to a 3523 possible-completions call. After that, readline asks the user if 3524 she is sure she wants to see them all. The default value is 100. 3525 A negative value indicates that Readline should never ask the user. 3526 3527 -- Variable: int rl_completion_append_character 3528 When a single completion alternative matches at the end of the 3529 command line, this character is appended to the inserted completion 3530 text. The default is a space character (' '). Setting this to the 3531 null character ('\0') prevents anything being appended 3532 automatically. This can be changed in application-specific 3533 completion functions to provide the "most sensible word separator 3534 character" according to an application-specific command line syntax 3535 specification. It is set to the default before any 3536 application-specific completion function is called, and may only be 3537 changed within such a function. 3538 3539 -- Variable: int rl_completion_suppress_append 3540 If non-zero, RL_COMPLETION_APPEND_CHARACTER is not appended to 3541 matches at the end of the command line, as described above. It is 3542 set to 0 before any application-specific completion function is 3543 called, and may only be changed within such a function. 3544 3545 -- Variable: int rl_completion_quote_character 3546 When Readline is completing quoted text, as delimited by one of the 3547 characters in RL_COMPLETER_QUOTE_CHARACTERS, it sets this variable 3548 to the quoting character found. This is set before any 3549 application-specific completion function is called. 3550 3551 -- Variable: int rl_completion_suppress_quote 3552 If non-zero, Readline does not append a matching quote character 3553 when performing completion on a quoted string. It is set to 0 3554 before any application-specific completion function is called, and 3555 may only be changed within such a function. 3556 3557 -- Variable: int rl_completion_found_quote 3558 When Readline is completing quoted text, it sets this variable to a 3559 non-zero value if the word being completed contains or is delimited 3560 by any quoting characters, including backslashes. This is set 3561 before any application-specific completion function is called. 3562 3563 -- Variable: int rl_completion_mark_symlink_dirs 3564 If non-zero, a slash will be appended to completed filenames that 3565 are symbolic links to directory names, subject to the value of the 3566 user-settable MARK-DIRECTORIES variable. This variable exists so 3567 that application-specific completion functions can override the 3568 user's global preference (set via the MARK-SYMLINKED-DIRECTORIES 3569 Readline variable) if appropriate. This variable is set to the 3570 user's preference before any application-specific completion 3571 function is called, so unless that function modifies the value, the 3572 user's preferences are honored. 3573 3574 -- Variable: int rl_ignore_completion_duplicates 3575 If non-zero, then duplicates in the matches are removed. The 3576 default is 1. 3577 3578 -- Variable: int rl_filename_completion_desired 3579 Non-zero means that the results of the matches are to be treated as 3580 filenames. This is _always_ zero when completion is attempted, and 3581 can only be changed within an application-specific completion 3582 function. If it is set to a non-zero value by such a function, 3583 directory names have a slash appended and Readline attempts to 3584 quote completed filenames if they contain any characters in 3585 'rl_filename_quote_characters' and 'rl_filename_quoting_desired' is 3586 set to a non-zero value. 3587 3588 -- Variable: int rl_filename_quoting_desired 3589 Non-zero means that the results of the matches are to be quoted 3590 using double quotes (or an application-specific quoting mechanism) 3591 if the completed filename contains any characters in 3592 'rl_filename_quote_chars'. This is _always_ non-zero when 3593 completion is attempted, and can only be changed within an 3594 application-specific completion function. The quoting is effected 3595 via a call to the function pointed to by 3596 'rl_filename_quoting_function'. 3597 3598 -- Variable: int rl_attempted_completion_over 3599 If an application-specific completion function assigned to 3600 'rl_attempted_completion_function' sets this variable to a non-zero 3601 value, Readline will not perform its default filename completion 3602 even if the application's completion function returns no matches. 3603 It should be set only by an application's completion function. 3604 3605 -- Variable: int rl_sort_completion_matches 3606 If an application sets this variable to 0, Readline will not sort 3607 the list of completions (which implies that it cannot remove any 3608 duplicate completions). The default value is 1, which means that 3609 Readline will sort the completions and, depending on the value of 3610 'rl_ignore_completion_duplicates', will attempt to remove duplicate 3611 matches. 3612 3613 -- Variable: int rl_completion_type 3614 Set to a character describing the type of completion Readline is 3615 currently attempting; see the description of 3616 'rl_complete_internal()' (*note Completion Functions::) for the 3617 list of characters. This is set to the appropriate value before 3618 any application-specific completion function is called, allowing 3619 such functions to present the same interface as 'rl_complete()'. 3620 3621 -- Variable: int rl_completion_invoking_key 3622 Set to the final character in the key sequence that invoked one of 3623 the completion functions that call 'rl_complete_internal()'. This 3624 is set to the appropriate value before any application-specific 3625 completion function is called. 3626 3627 -- Variable: int rl_inhibit_completion 3628 If this variable is non-zero, completion is inhibited. The 3629 completion character will be inserted as any other bound to 3630 'self-insert'. 3631 3632 3633File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers 3634 36352.6.4 A Short Completion Example 3636-------------------------------- 3637 3638Here is a small application demonstrating the use of the GNU Readline 3639library. It is called 'fileman', and the source code resides in 3640'examples/fileman.c'. This sample application provides completion of 3641command names, line editing features, and access to the history list. 3642 3643 /* fileman.c -- A tiny application which demonstrates how to use the 3644 GNU Readline library. This application interactively allows users 3645 to manipulate files and their modes. */ 3646 3647 #ifdef HAVE_CONFIG_H 3648 # include <config.h> 3649 #endif 3650 3651 #include <sys/types.h> 3652 #ifdef HAVE_SYS_FILE_H 3653 # include <sys/file.h> 3654 #endif 3655 #include <sys/stat.h> 3656 3657 #ifdef HAVE_UNISTD_H 3658 # include <unistd.h> 3659 #endif 3660 3661 #include <fcntl.h> 3662 #include <stdio.h> 3663 #include <errno.h> 3664 3665 #if defined (HAVE_STRING_H) 3666 # include <string.h> 3667 #else /* !HAVE_STRING_H */ 3668 # include <strings.h> 3669 #endif /* !HAVE_STRING_H */ 3670 3671 #ifdef HAVE_STDLIB_H 3672 # include <stdlib.h> 3673 #endif 3674 3675 #include <time.h> 3676 3677 #include <readline/readline.h> 3678 #include <readline/history.h> 3679 3680 extern char *xmalloc PARAMS((size_t)); 3681 3682 /* The names of functions that actually do the manipulation. */ 3683 int com_list PARAMS((char *)); 3684 int com_view PARAMS((char *)); 3685 int com_rename PARAMS((char *)); 3686 int com_stat PARAMS((char *)); 3687 int com_pwd PARAMS((char *)); 3688 int com_delete PARAMS((char *)); 3689 int com_help PARAMS((char *)); 3690 int com_cd PARAMS((char *)); 3691 int com_quit PARAMS((char *)); 3692 3693 /* A structure which contains information on the commands this program 3694 can understand. */ 3695 3696 typedef struct { 3697 char *name; /* User printable name of the function. */ 3698 rl_icpfunc_t *func; /* Function to call to do the job. */ 3699 char *doc; /* Documentation for this function. */ 3700 } COMMAND; 3701 3702 COMMAND commands[] = { 3703 { "cd", com_cd, "Change to directory DIR" }, 3704 { "delete", com_delete, "Delete FILE" }, 3705 { "help", com_help, "Display this text" }, 3706 { "?", com_help, "Synonym for `help'" }, 3707 { "list", com_list, "List files in DIR" }, 3708 { "ls", com_list, "Synonym for `list'" }, 3709 { "pwd", com_pwd, "Print the current working directory" }, 3710 { "quit", com_quit, "Quit using Fileman" }, 3711 { "rename", com_rename, "Rename FILE to NEWNAME" }, 3712 { "stat", com_stat, "Print out statistics on FILE" }, 3713 { "view", com_view, "View the contents of FILE" }, 3714 { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL } 3715 }; 3716 3717 /* Forward declarations. */ 3718 char *stripwhite (); 3719 COMMAND *find_command (); 3720 3721 /* The name of this program, as taken from argv[0]. */ 3722 char *progname; 3723 3724 /* When non-zero, this global means the user is done using this program. */ 3725 int done; 3726 3727 char * 3728 dupstr (s) 3729 char *s; 3730 { 3731 char *r; 3732 3733 r = xmalloc (strlen (s) + 1); 3734 strcpy (r, s); 3735 return (r); 3736 } 3737 3738 main (argc, argv) 3739 int argc; 3740 char **argv; 3741 { 3742 char *line, *s; 3743 3744 progname = argv[0]; 3745 3746 initialize_readline (); /* Bind our completer. */ 3747 3748 /* Loop reading and executing lines until the user quits. */ 3749 for ( ; done == 0; ) 3750 { 3751 line = readline ("FileMan: "); 3752 3753 if (!line) 3754 break; 3755 3756 /* Remove leading and trailing whitespace from the line. 3757 Then, if there is anything left, add it to the history list 3758 and execute it. */ 3759 s = stripwhite (line); 3760 3761 if (*s) 3762 { 3763 add_history (s); 3764 execute_line (s); 3765 } 3766 3767 free (line); 3768 } 3769 exit (0); 3770 } 3771 3772 /* Execute a command line. */ 3773 int 3774 execute_line (line) 3775 char *line; 3776 { 3777 register int i; 3778 COMMAND *command; 3779 char *word; 3780 3781 /* Isolate the command word. */ 3782 i = 0; 3783 while (line[i] && whitespace (line[i])) 3784 i++; 3785 word = line + i; 3786 3787 while (line[i] && !whitespace (line[i])) 3788 i++; 3789 3790 if (line[i]) 3791 line[i++] = '\0'; 3792 3793 command = find_command (word); 3794 3795 if (!command) 3796 { 3797 fprintf (stderr, "%s: No such command for FileMan.\n", word); 3798 return (-1); 3799 } 3800 3801 /* Get argument to command, if any. */ 3802 while (whitespace (line[i])) 3803 i++; 3804 3805 word = line + i; 3806 3807 /* Call the function. */ 3808 return ((*(command->func)) (word)); 3809 } 3810 3811 /* Look up NAME as the name of a command, and return a pointer to that 3812 command. Return a NULL pointer if NAME isn't a command name. */ 3813 COMMAND * 3814 find_command (name) 3815 char *name; 3816 { 3817 register int i; 3818 3819 for (i = 0; commands[i].name; i++) 3820 if (strcmp (name, commands[i].name) == 0) 3821 return (&commands[i]); 3822 3823 return ((COMMAND *)NULL); 3824 } 3825 3826 /* Strip whitespace from the start and end of STRING. Return a pointer 3827 into STRING. */ 3828 char * 3829 stripwhite (string) 3830 char *string; 3831 { 3832 register char *s, *t; 3833 3834 for (s = string; whitespace (*s); s++) 3835 ; 3836 3837 if (*s == 0) 3838 return (s); 3839 3840 t = s + strlen (s) - 1; 3841 while (t > s && whitespace (*t)) 3842 t--; 3843 *++t = '\0'; 3844 3845 return s; 3846 } 3847 3848 /* **************************************************************** */ 3849 /* */ 3850 /* Interface to Readline Completion */ 3851 /* */ 3852 /* **************************************************************** */ 3853 3854 char *command_generator PARAMS((const char *, int)); 3855 char **fileman_completion PARAMS((const char *, int, int)); 3856 3857 /* Tell the GNU Readline library how to complete. We want to try to complete 3858 on command names if this is the first word in the line, or on filenames 3859 if not. */ 3860 initialize_readline () 3861 { 3862 /* Allow conditional parsing of the ~/.inputrc file. */ 3863 rl_readline_name = "FileMan"; 3864 3865 /* Tell the completer that we want a crack first. */ 3866 rl_attempted_completion_function = fileman_completion; 3867 } 3868 3869 /* Attempt to complete on the contents of TEXT. START and END bound the 3870 region of rl_line_buffer that contains the word to complete. TEXT is 3871 the word to complete. We can use the entire contents of rl_line_buffer 3872 in case we want to do some simple parsing. Return the array of matches, 3873 or NULL if there aren't any. */ 3874 char ** 3875 fileman_completion (text, start, end) 3876 const char *text; 3877 int start, end; 3878 { 3879 char **matches; 3880 3881 matches = (char **)NULL; 3882 3883 /* If this word is at the start of the line, then it is a command 3884 to complete. Otherwise it is the name of a file in the current 3885 directory. */ 3886 if (start == 0) 3887 matches = rl_completion_matches (text, command_generator); 3888 3889 return (matches); 3890 } 3891 3892 /* Generator function for command completion. STATE lets us know whether 3893 to start from scratch; without any state (i.e. STATE == 0), then we 3894 start at the top of the list. */ 3895 char * 3896 command_generator (text, state) 3897 const char *text; 3898 int state; 3899 { 3900 static int list_index, len; 3901 char *name; 3902 3903 /* If this is a new word to complete, initialize now. This includes 3904 saving the length of TEXT for efficiency, and initializing the index 3905 variable to 0. */ 3906 if (!state) 3907 { 3908 list_index = 0; 3909 len = strlen (text); 3910 } 3911 3912 /* Return the next name which partially matches from the command list. */ 3913 while (name = commands[list_index].name) 3914 { 3915 list_index++; 3916 3917 if (strncmp (name, text, len) == 0) 3918 return (dupstr(name)); 3919 } 3920 3921 /* If no names matched, then return NULL. */ 3922 return ((char *)NULL); 3923 } 3924 3925 /* **************************************************************** */ 3926 /* */ 3927 /* FileMan Commands */ 3928 /* */ 3929 /* **************************************************************** */ 3930 3931 /* String to pass to system (). This is for the LIST, VIEW and RENAME 3932 commands. */ 3933 static char syscom[1024]; 3934 3935 /* List the file(s) named in arg. */ 3936 com_list (arg) 3937 char *arg; 3938 { 3939 if (!arg) 3940 arg = ""; 3941 3942 sprintf (syscom, "ls -FClg %s", arg); 3943 return (system (syscom)); 3944 } 3945 3946 com_view (arg) 3947 char *arg; 3948 { 3949 if (!valid_argument ("view", arg)) 3950 return 1; 3951 3952 #if defined (__MSDOS__) 3953 /* more.com doesn't grok slashes in pathnames */ 3954 sprintf (syscom, "less %s", arg); 3955 #else 3956 sprintf (syscom, "more %s", arg); 3957 #endif 3958 return (system (syscom)); 3959 } 3960 3961 com_rename (arg) 3962 char *arg; 3963 { 3964 too_dangerous ("rename"); 3965 return (1); 3966 } 3967 3968 com_stat (arg) 3969 char *arg; 3970 { 3971 struct stat finfo; 3972 3973 if (!valid_argument ("stat", arg)) 3974 return (1); 3975 3976 if (stat (arg, &finfo) == -1) 3977 { 3978 perror (arg); 3979 return (1); 3980 } 3981 3982 printf ("Statistics for `%s':\n", arg); 3983 3984 printf ("%s has %d link%s, and is %d byte%s in length.\n", 3985 arg, 3986 finfo.st_nlink, 3987 (finfo.st_nlink == 1) ? "" : "s", 3988 finfo.st_size, 3989 (finfo.st_size == 1) ? "" : "s"); 3990 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); 3991 printf (" Last access at: %s", ctime (&finfo.st_atime)); 3992 printf (" Last modified at: %s", ctime (&finfo.st_mtime)); 3993 return (0); 3994 } 3995 3996 com_delete (arg) 3997 char *arg; 3998 { 3999 too_dangerous ("delete"); 4000 return (1); 4001 } 4002 4003 /* Print out help for ARG, or for all of the commands if ARG is 4004 not present. */ 4005 com_help (arg) 4006 char *arg; 4007 { 4008 register int i; 4009 int printed = 0; 4010 4011 for (i = 0; commands[i].name; i++) 4012 { 4013 if (!*arg || (strcmp (arg, commands[i].name) == 0)) 4014 { 4015 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); 4016 printed++; 4017 } 4018 } 4019 4020 if (!printed) 4021 { 4022 printf ("No commands match `%s'. Possibilities are:\n", arg); 4023 4024 for (i = 0; commands[i].name; i++) 4025 { 4026 /* Print in six columns. */ 4027 if (printed == 6) 4028 { 4029 printed = 0; 4030 printf ("\n"); 4031 } 4032 4033 printf ("%s\t", commands[i].name); 4034 printed++; 4035 } 4036 4037 if (printed) 4038 printf ("\n"); 4039 } 4040 return (0); 4041 } 4042 4043 /* Change to the directory ARG. */ 4044 com_cd (arg) 4045 char *arg; 4046 { 4047 if (chdir (arg) == -1) 4048 { 4049 perror (arg); 4050 return 1; 4051 } 4052 4053 com_pwd (""); 4054 return (0); 4055 } 4056 4057 /* Print out the current working directory. */ 4058 com_pwd (ignore) 4059 char *ignore; 4060 { 4061 char dir[1024], *s; 4062 4063 s = getcwd (dir, sizeof(dir) - 1); 4064 if (s == 0) 4065 { 4066 printf ("Error getting pwd: %s\n", dir); 4067 return 1; 4068 } 4069 4070 printf ("Current directory is %s\n", dir); 4071 return 0; 4072 } 4073 4074 /* The user wishes to quit using this program. Just set DONE non-zero. */ 4075 com_quit (arg) 4076 char *arg; 4077 { 4078 done = 1; 4079 return (0); 4080 } 4081 4082 /* Function which tells you that you can't do this. */ 4083 too_dangerous (caller) 4084 char *caller; 4085 { 4086 fprintf (stderr, 4087 "%s: Too dangerous for me to distribute. Write it yourself.\n", 4088 caller); 4089 } 4090 4091 /* Return non-zero if ARG is a valid argument for CALLER, else print 4092 an error message and return zero. */ 4093 int 4094 valid_argument (caller, arg) 4095 char *caller, *arg; 4096 { 4097 if (!arg || !*arg) 4098 { 4099 fprintf (stderr, "%s: Argument required.\n", caller); 4100 return (0); 4101 } 4102 4103 return (1); 4104 } 4105 4106 4107File: readline.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU Readline, Up: Top 4108 4109Appendix A GNU Free Documentation License 4110***************************************** 4111 4112 Version 1.3, 3 November 2008 4113 4114 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 4115 <http://fsf.org/> 4116 4117 Everyone is permitted to copy and distribute verbatim copies 4118 of this license document, but changing it is not allowed. 4119 4120 0. PREAMBLE 4121 4122 The purpose of this License is to make a manual, textbook, or other 4123 functional and useful document "free" in the sense of freedom: to 4124 assure everyone the effective freedom to copy and redistribute it, 4125 with or without modifying it, either commercially or 4126 noncommercially. Secondarily, this License preserves for the 4127 author and publisher a way to get credit for their work, while not 4128 being considered responsible for modifications made by others. 4129 4130 This License is a kind of "copyleft", which means that derivative 4131 works of the document must themselves be free in the same sense. 4132 It complements the GNU General Public License, which is a copyleft 4133 license designed for free software. 4134 4135 We have designed this License in order to use it for manuals for 4136 free software, because free software needs free documentation: a 4137 free program should come with manuals providing the same freedoms 4138 that the software does. But this License is not limited to 4139 software manuals; it can be used for any textual work, regardless 4140 of subject matter or whether it is published as a printed book. We 4141 recommend this License principally for works whose purpose is 4142 instruction or reference. 4143 4144 1. APPLICABILITY AND DEFINITIONS 4145 4146 This License applies to any manual or other work, in any medium, 4147 that contains a notice placed by the copyright holder saying it can 4148 be distributed under the terms of this License. Such a notice 4149 grants a world-wide, royalty-free license, unlimited in duration, 4150 to use that work under the conditions stated herein. The 4151 "Document", below, refers to any such manual or work. Any member 4152 of the public is a licensee, and is addressed as "you". You accept 4153 the license if you copy, modify or distribute the work in a way 4154 requiring permission under copyright law. 4155 4156 A "Modified Version" of the Document means any work containing the 4157 Document or a portion of it, either copied verbatim, or with 4158 modifications and/or translated into another language. 4159 4160 A "Secondary Section" is a named appendix or a front-matter section 4161 of the Document that deals exclusively with the relationship of the 4162 publishers or authors of the Document to the Document's overall 4163 subject (or to related matters) and contains nothing that could 4164 fall directly within that overall subject. (Thus, if the Document 4165 is in part a textbook of mathematics, a Secondary Section may not 4166 explain any mathematics.) The relationship could be a matter of 4167 historical connection with the subject or with related matters, or 4168 of legal, commercial, philosophical, ethical or political position 4169 regarding them. 4170 4171 The "Invariant Sections" are certain Secondary Sections whose 4172 titles are designated, as being those of Invariant Sections, in the 4173 notice that says that the Document is released under this License. 4174 If a section does not fit the above definition of Secondary then it 4175 is not allowed to be designated as Invariant. The Document may 4176 contain zero Invariant Sections. If the Document does not identify 4177 any Invariant Sections then there are none. 4178 4179 The "Cover Texts" are certain short passages of text that are 4180 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 4181 that says that the Document is released under this License. A 4182 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 4183 be at most 25 words. 4184 4185 A "Transparent" copy of the Document means a machine-readable copy, 4186 represented in a format whose specification is available to the 4187 general public, that is suitable for revising the document 4188 straightforwardly with generic text editors or (for images composed 4189 of pixels) generic paint programs or (for drawings) some widely 4190 available drawing editor, and that is suitable for input to text 4191 formatters or for automatic translation to a variety of formats 4192 suitable for input to text formatters. A copy made in an otherwise 4193 Transparent file format whose markup, or absence of markup, has 4194 been arranged to thwart or discourage subsequent modification by 4195 readers is not Transparent. An image format is not Transparent if 4196 used for any substantial amount of text. A copy that is not 4197 "Transparent" is called "Opaque". 4198 4199 Examples of suitable formats for Transparent copies include plain 4200 ASCII without markup, Texinfo input format, LaTeX input format, 4201 SGML or XML using a publicly available DTD, and standard-conforming 4202 simple HTML, PostScript or PDF designed for human modification. 4203 Examples of transparent image formats include PNG, XCF and JPG. 4204 Opaque formats include proprietary formats that can be read and 4205 edited only by proprietary word processors, SGML or XML for which 4206 the DTD and/or processing tools are not generally available, and 4207 the machine-generated HTML, PostScript or PDF produced by some word 4208 processors for output purposes only. 4209 4210 The "Title Page" means, for a printed book, the title page itself, 4211 plus such following pages as are needed to hold, legibly, the 4212 material this License requires to appear in the title page. For 4213 works in formats which do not have any title page as such, "Title 4214 Page" means the text near the most prominent appearance of the 4215 work's title, preceding the beginning of the body of the text. 4216 4217 The "publisher" means any person or entity that distributes copies 4218 of the Document to the public. 4219 4220 A section "Entitled XYZ" means a named subunit of the Document 4221 whose title either is precisely XYZ or contains XYZ in parentheses 4222 following text that translates XYZ in another language. (Here XYZ 4223 stands for a specific section name mentioned below, such as 4224 "Acknowledgements", "Dedications", "Endorsements", or "History".) 4225 To "Preserve the Title" of such a section when you modify the 4226 Document means that it remains a section "Entitled XYZ" according 4227 to this definition. 4228 4229 The Document may include Warranty Disclaimers next to the notice 4230 which states that this License applies to the Document. These 4231 Warranty Disclaimers are considered to be included by reference in 4232 this License, but only as regards disclaiming warranties: any other 4233 implication that these Warranty Disclaimers may have is void and 4234 has no effect on the meaning of this License. 4235 4236 2. VERBATIM COPYING 4237 4238 You may copy and distribute the Document in any medium, either 4239 commercially or noncommercially, provided that this License, the 4240 copyright notices, and the license notice saying this License 4241 applies to the Document are reproduced in all copies, and that you 4242 add no other conditions whatsoever to those of this License. You 4243 may not use technical measures to obstruct or control the reading 4244 or further copying of the copies you make or distribute. However, 4245 you may accept compensation in exchange for copies. If you 4246 distribute a large enough number of copies you must also follow the 4247 conditions in section 3. 4248 4249 You may also lend copies, under the same conditions stated above, 4250 and you may publicly display copies. 4251 4252 3. COPYING IN QUANTITY 4253 4254 If you publish printed copies (or copies in media that commonly 4255 have printed covers) of the Document, numbering more than 100, and 4256 the Document's license notice requires Cover Texts, you must 4257 enclose the copies in covers that carry, clearly and legibly, all 4258 these Cover Texts: Front-Cover Texts on the front cover, and 4259 Back-Cover Texts on the back cover. Both covers must also clearly 4260 and legibly identify you as the publisher of these copies. The 4261 front cover must present the full title with all words of the title 4262 equally prominent and visible. You may add other material on the 4263 covers in addition. Copying with changes limited to the covers, as 4264 long as they preserve the title of the Document and satisfy these 4265 conditions, can be treated as verbatim copying in other respects. 4266 4267 If the required texts for either cover are too voluminous to fit 4268 legibly, you should put the first ones listed (as many as fit 4269 reasonably) on the actual cover, and continue the rest onto 4270 adjacent pages. 4271 4272 If you publish or distribute Opaque copies of the Document 4273 numbering more than 100, you must either include a machine-readable 4274 Transparent copy along with each Opaque copy, or state in or with 4275 each Opaque copy a computer-network location from which the general 4276 network-using public has access to download using public-standard 4277 network protocols a complete Transparent copy of the Document, free 4278 of added material. If you use the latter option, you must take 4279 reasonably prudent steps, when you begin distribution of Opaque 4280 copies in quantity, to ensure that this Transparent copy will 4281 remain thus accessible at the stated location until at least one 4282 year after the last time you distribute an Opaque copy (directly or 4283 through your agents or retailers) of that edition to the public. 4284 4285 It is requested, but not required, that you contact the authors of 4286 the Document well before redistributing any large number of copies, 4287 to give them a chance to provide you with an updated version of the 4288 Document. 4289 4290 4. MODIFICATIONS 4291 4292 You may copy and distribute a Modified Version of the Document 4293 under the conditions of sections 2 and 3 above, provided that you 4294 release the Modified Version under precisely this License, with the 4295 Modified Version filling the role of the Document, thus licensing 4296 distribution and modification of the Modified Version to whoever 4297 possesses a copy of it. In addition, you must do these things in 4298 the Modified Version: 4299 4300 A. Use in the Title Page (and on the covers, if any) a title 4301 distinct from that of the Document, and from those of previous 4302 versions (which should, if there were any, be listed in the 4303 History section of the Document). You may use the same title 4304 as a previous version if the original publisher of that 4305 version gives permission. 4306 4307 B. List on the Title Page, as authors, one or more persons or 4308 entities responsible for authorship of the modifications in 4309 the Modified Version, together with at least five of the 4310 principal authors of the Document (all of its principal 4311 authors, if it has fewer than five), unless they release you 4312 from this requirement. 4313 4314 C. State on the Title page the name of the publisher of the 4315 Modified Version, as the publisher. 4316 4317 D. Preserve all the copyright notices of the Document. 4318 4319 E. Add an appropriate copyright notice for your modifications 4320 adjacent to the other copyright notices. 4321 4322 F. Include, immediately after the copyright notices, a license 4323 notice giving the public permission to use the Modified 4324 Version under the terms of this License, in the form shown in 4325 the Addendum below. 4326 4327 G. Preserve in that license notice the full lists of Invariant 4328 Sections and required Cover Texts given in the Document's 4329 license notice. 4330 4331 H. Include an unaltered copy of this License. 4332 4333 I. Preserve the section Entitled "History", Preserve its Title, 4334 and add to it an item stating at least the title, year, new 4335 authors, and publisher of the Modified Version as given on the 4336 Title Page. If there is no section Entitled "History" in the 4337 Document, create one stating the title, year, authors, and 4338 publisher of the Document as given on its Title Page, then add 4339 an item describing the Modified Version as stated in the 4340 previous sentence. 4341 4342 J. Preserve the network location, if any, given in the Document 4343 for public access to a Transparent copy of the Document, and 4344 likewise the network locations given in the Document for 4345 previous versions it was based on. These may be placed in the 4346 "History" section. You may omit a network location for a work 4347 that was published at least four years before the Document 4348 itself, or if the original publisher of the version it refers 4349 to gives permission. 4350 4351 K. For any section Entitled "Acknowledgements" or "Dedications", 4352 Preserve the Title of the section, and preserve in the section 4353 all the substance and tone of each of the contributor 4354 acknowledgements and/or dedications given therein. 4355 4356 L. Preserve all the Invariant Sections of the Document, unaltered 4357 in their text and in their titles. Section numbers or the 4358 equivalent are not considered part of the section titles. 4359 4360 M. Delete any section Entitled "Endorsements". Such a section 4361 may not be included in the Modified Version. 4362 4363 N. Do not retitle any existing section to be Entitled 4364 "Endorsements" or to conflict in title with any Invariant 4365 Section. 4366 4367 O. Preserve any Warranty Disclaimers. 4368 4369 If the Modified Version includes new front-matter sections or 4370 appendices that qualify as Secondary Sections and contain no 4371 material copied from the Document, you may at your option designate 4372 some or all of these sections as invariant. To do this, add their 4373 titles to the list of Invariant Sections in the Modified Version's 4374 license notice. These titles must be distinct from any other 4375 section titles. 4376 4377 You may add a section Entitled "Endorsements", provided it contains 4378 nothing but endorsements of your Modified Version by various 4379 parties--for example, statements of peer review or that the text 4380 has been approved by an organization as the authoritative 4381 definition of a standard. 4382 4383 You may add a passage of up to five words as a Front-Cover Text, 4384 and a passage of up to 25 words as a Back-Cover Text, to the end of 4385 the list of Cover Texts in the Modified Version. Only one passage 4386 of Front-Cover Text and one of Back-Cover Text may be added by (or 4387 through arrangements made by) any one entity. If the Document 4388 already includes a cover text for the same cover, previously added 4389 by you or by arrangement made by the same entity you are acting on 4390 behalf of, you may not add another; but you may replace the old 4391 one, on explicit permission from the previous publisher that added 4392 the old one. 4393 4394 The author(s) and publisher(s) of the Document do not by this 4395 License give permission to use their names for publicity for or to 4396 assert or imply endorsement of any Modified Version. 4397 4398 5. COMBINING DOCUMENTS 4399 4400 You may combine the Document with other documents released under 4401 this License, under the terms defined in section 4 above for 4402 modified versions, provided that you include in the combination all 4403 of the Invariant Sections of all of the original documents, 4404 unmodified, and list them all as Invariant Sections of your 4405 combined work in its license notice, and that you preserve all 4406 their Warranty Disclaimers. 4407 4408 The combined work need only contain one copy of this License, and 4409 multiple identical Invariant Sections may be replaced with a single 4410 copy. If there are multiple Invariant Sections with the same name 4411 but different contents, make the title of each such section unique 4412 by adding at the end of it, in parentheses, the name of the 4413 original author or publisher of that section if known, or else a 4414 unique number. Make the same adjustment to the section titles in 4415 the list of Invariant Sections in the license notice of the 4416 combined work. 4417 4418 In the combination, you must combine any sections Entitled 4419 "History" in the various original documents, forming one section 4420 Entitled "History"; likewise combine any sections Entitled 4421 "Acknowledgements", and any sections Entitled "Dedications". You 4422 must delete all sections Entitled "Endorsements." 4423 4424 6. COLLECTIONS OF DOCUMENTS 4425 4426 You may make a collection consisting of the Document and other 4427 documents released under this License, and replace the individual 4428 copies of this License in the various documents with a single copy 4429 that is included in the collection, provided that you follow the 4430 rules of this License for verbatim copying of each of the documents 4431 in all other respects. 4432 4433 You may extract a single document from such a collection, and 4434 distribute it individually under this License, provided you insert 4435 a copy of this License into the extracted document, and follow this 4436 License in all other respects regarding verbatim copying of that 4437 document. 4438 4439 7. AGGREGATION WITH INDEPENDENT WORKS 4440 4441 A compilation of the Document or its derivatives with other 4442 separate and independent documents or works, in or on a volume of a 4443 storage or distribution medium, is called an "aggregate" if the 4444 copyright resulting from the compilation is not used to limit the 4445 legal rights of the compilation's users beyond what the individual 4446 works permit. When the Document is included in an aggregate, this 4447 License does not apply to the other works in the aggregate which 4448 are not themselves derivative works of the Document. 4449 4450 If the Cover Text requirement of section 3 is applicable to these 4451 copies of the Document, then if the Document is less than one half 4452 of the entire aggregate, the Document's Cover Texts may be placed 4453 on covers that bracket the Document within the aggregate, or the 4454 electronic equivalent of covers if the Document is in electronic 4455 form. Otherwise they must appear on printed covers that bracket 4456 the whole aggregate. 4457 4458 8. TRANSLATION 4459 4460 Translation is considered a kind of modification, so you may 4461 distribute translations of the Document under the terms of section 4462 4. Replacing Invariant Sections with translations requires special 4463 permission from their copyright holders, but you may include 4464 translations of some or all Invariant Sections in addition to the 4465 original versions of these Invariant Sections. You may include a 4466 translation of this License, and all the license notices in the 4467 Document, and any Warranty Disclaimers, provided that you also 4468 include the original English version of this License and the 4469 original versions of those notices and disclaimers. In case of a 4470 disagreement between the translation and the original version of 4471 this License or a notice or disclaimer, the original version will 4472 prevail. 4473 4474 If a section in the Document is Entitled "Acknowledgements", 4475 "Dedications", or "History", the requirement (section 4) to 4476 Preserve its Title (section 1) will typically require changing the 4477 actual title. 4478 4479 9. TERMINATION 4480 4481 You may not copy, modify, sublicense, or distribute the Document 4482 except as expressly provided under this License. Any attempt 4483 otherwise to copy, modify, sublicense, or distribute it is void, 4484 and will automatically terminate your rights under this License. 4485 4486 However, if you cease all violation of this License, then your 4487 license from a particular copyright holder is reinstated (a) 4488 provisionally, unless and until the copyright holder explicitly and 4489 finally terminates your license, and (b) permanently, if the 4490 copyright holder fails to notify you of the violation by some 4491 reasonable means prior to 60 days after the cessation. 4492 4493 Moreover, your license from a particular copyright holder is 4494 reinstated permanently if the copyright holder notifies you of the 4495 violation by some reasonable means, this is the first time you have 4496 received notice of violation of this License (for any work) from 4497 that copyright holder, and you cure the violation prior to 30 days 4498 after your receipt of the notice. 4499 4500 Termination of your rights under this section does not terminate 4501 the licenses of parties who have received copies or rights from you 4502 under this License. If your rights have been terminated and not 4503 permanently reinstated, receipt of a copy of some or all of the 4504 same material does not give you any rights to use it. 4505 4506 10. FUTURE REVISIONS OF THIS LICENSE 4507 4508 The Free Software Foundation may publish new, revised versions of 4509 the GNU Free Documentation License from time to time. Such new 4510 versions will be similar in spirit to the present version, but may 4511 differ in detail to address new problems or concerns. See 4512 <http://www.gnu.org/copyleft/>. 4513 4514 Each version of the License is given a distinguishing version 4515 number. If the Document specifies that a particular numbered 4516 version of this License "or any later version" applies to it, you 4517 have the option of following the terms and conditions either of 4518 that specified version or of any later version that has been 4519 published (not as a draft) by the Free Software Foundation. If the 4520 Document does not specify a version number of this License, you may 4521 choose any version ever published (not as a draft) by the Free 4522 Software Foundation. If the Document specifies that a proxy can 4523 decide which future versions of this License can be used, that 4524 proxy's public statement of acceptance of a version permanently 4525 authorizes you to choose that version for the Document. 4526 4527 11. RELICENSING 4528 4529 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 4530 World Wide Web server that publishes copyrightable works and also 4531 provides prominent facilities for anybody to edit those works. A 4532 public wiki that anybody can edit is an example of such a server. 4533 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 4534 site means any set of copyrightable works thus published on the MMC 4535 site. 4536 4537 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 4538 license published by Creative Commons Corporation, a not-for-profit 4539 corporation with a principal place of business in San Francisco, 4540 California, as well as future copyleft versions of that license 4541 published by that same organization. 4542 4543 "Incorporate" means to publish or republish a Document, in whole or 4544 in part, as part of another Document. 4545 4546 An MMC is "eligible for relicensing" if it is licensed under this 4547 License, and if all works that were first published under this 4548 License somewhere other than this MMC, and subsequently 4549 incorporated in whole or in part into the MMC, (1) had no cover 4550 texts or invariant sections, and (2) were thus incorporated prior 4551 to November 1, 2008. 4552 4553 The operator of an MMC Site may republish an MMC contained in the 4554 site under CC-BY-SA on the same site at any time before August 1, 4555 2009, provided the MMC is eligible for relicensing. 4556 4557ADDENDUM: How to use this License for your documents 4558==================================================== 4559 4560To use this License in a document you have written, include a copy of 4561the License in the document and put the following copyright and license 4562notices just after the title page: 4563 4564 Copyright (C) YEAR YOUR NAME. 4565 Permission is granted to copy, distribute and/or modify this document 4566 under the terms of the GNU Free Documentation License, Version 1.3 4567 or any later version published by the Free Software Foundation; 4568 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 4569 Texts. A copy of the license is included in the section entitled ``GNU 4570 Free Documentation License''. 4571 4572 If you have Invariant Sections, Front-Cover Texts and Back-Cover 4573Texts, replace the "with...Texts." line with this: 4574 4575 with the Invariant Sections being LIST THEIR TITLES, with 4576 the Front-Cover Texts being LIST, and with the Back-Cover Texts 4577 being LIST. 4578 4579 If you have Invariant Sections without Cover Texts, or some other 4580combination of the three, merge those two alternatives to suit the 4581situation. 4582 4583 If your document contains nontrivial examples of program code, we 4584recommend releasing these examples in parallel under your choice of free 4585software license, such as the GNU General Public License, to permit 4586their use in free software. 4587 4588 4589File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top 4590 4591Concept Index 4592************* 4593 4594[index] 4595* Menu: 4596 4597* application-specific completion functions: Custom Completers. 4598 (line 6) 4599* command editing: Readline Bare Essentials. 4600 (line 6) 4601* editing command lines: Readline Bare Essentials. 4602 (line 6) 4603* initialization file, readline: Readline Init File. (line 6) 4604* interaction, readline: Readline Interaction. (line 6) 4605* kill ring: Readline Killing Commands. 4606 (line 18) 4607* killing text: Readline Killing Commands. 4608 (line 6) 4609* notation, readline: Readline Bare Essentials. 4610 (line 6) 4611* readline, function: Basic Behavior. (line 12) 4612* variables, readline: Readline Init File Syntax. 4613 (line 34) 4614* yanking text: Readline Killing Commands. 4615 (line 6) 4616 4617 4618File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top 4619 4620Function and Variable Index 4621*************************** 4622 4623[index] 4624* Menu: 4625 4626* _rl_digit_p: Utility Functions. (line 64) 4627* _rl_digit_value: Utility Functions. (line 75) 4628* _rl_lowercase_p: Utility Functions. (line 61) 4629* _rl_to_lower: Utility Functions. (line 71) 4630* _rl_to_upper: Utility Functions. (line 67) 4631* _rl_uppercase_p: Utility Functions. (line 58) 4632* abort (C-g): Miscellaneous Commands. 4633 (line 10) 4634* accept-line (Newline or Return): Commands For History. 4635 (line 6) 4636* backward-char (C-b): Commands For Moving. (line 15) 4637* backward-delete-char (Rubout): Commands For Text. (line 17) 4638* backward-kill-line (C-x Rubout): Commands For Killing. 4639 (line 11) 4640* backward-kill-word (M-<DEL>): Commands For Killing. 4641 (line 28) 4642* backward-word (M-b): Commands For Moving. (line 22) 4643* beginning-of-history (M-<): Commands For History. 4644 (line 19) 4645* beginning-of-line (C-a): Commands For Moving. (line 6) 4646* bell-style: Readline Init File Syntax. 4647 (line 35) 4648* bind-tty-special-chars: Readline Init File Syntax. 4649 (line 42) 4650* blink-matching-paren: Readline Init File Syntax. 4651 (line 47) 4652* bracketed-paste-begin (): Commands For Text. (line 36) 4653* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) 4654* capitalize-word (M-c): Commands For Text. (line 69) 4655* character-search (C-]): Miscellaneous Commands. 4656 (line 42) 4657* character-search-backward (M-C-]): Miscellaneous Commands. 4658 (line 47) 4659* clear-display (M-C-l): Commands For Moving. (line 40) 4660* clear-screen (C-l): Commands For Moving. (line 45) 4661* colored-completion-prefix: Readline Init File Syntax. 4662 (line 52) 4663* colored-stats: Readline Init File Syntax. 4664 (line 59) 4665* comment-begin: Readline Init File Syntax. 4666 (line 65) 4667* complete (<TAB>): Commands For Completion. 4668 (line 6) 4669* completion-display-width: Readline Init File Syntax. 4670 (line 70) 4671* completion-ignore-case: Readline Init File Syntax. 4672 (line 77) 4673* completion-map-case: Readline Init File Syntax. 4674 (line 82) 4675* completion-prefix-display-length: Readline Init File Syntax. 4676 (line 88) 4677* completion-query-items: Readline Init File Syntax. 4678 (line 95) 4679* convert-meta: Readline Init File Syntax. 4680 (line 105) 4681* copy-backward-word (): Commands For Killing. 4682 (line 60) 4683* copy-forward-word (): Commands For Killing. 4684 (line 65) 4685* copy-region-as-kill (): Commands For Killing. 4686 (line 56) 4687* delete-char (C-d): Commands For Text. (line 12) 4688* delete-char-or-list (): Commands For Completion. 4689 (line 39) 4690* delete-horizontal-space (): Commands For Killing. 4691 (line 48) 4692* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) 4693* disable-completion: Readline Init File Syntax. 4694 (line 113) 4695* do-lowercase-version (M-A, M-B, M-X, ...): Miscellaneous Commands. 4696 (line 14) 4697* downcase-word (M-l): Commands For Text. (line 65) 4698* dump-functions (): Miscellaneous Commands. 4699 (line 70) 4700* dump-macros (): Miscellaneous Commands. 4701 (line 82) 4702* dump-variables (): Miscellaneous Commands. 4703 (line 76) 4704* echo-control-characters: Readline Init File Syntax. 4705 (line 118) 4706* editing-mode: Readline Init File Syntax. 4707 (line 123) 4708* emacs-editing-mode (C-e): Miscellaneous Commands. 4709 (line 88) 4710* emacs-mode-string: Readline Init File Syntax. 4711 (line 129) 4712* enable-bracketed-paste: Readline Init File Syntax. 4713 (line 139) 4714* enable-keypad: Readline Init File Syntax. 4715 (line 147) 4716* end-kbd-macro (C-x )): Keyboard Macros. (line 9) 4717* end-of-file (usually C-d): Commands For Text. (line 6) 4718* end-of-history (M->): Commands For History. 4719 (line 22) 4720* end-of-line (C-e): Commands For Moving. (line 9) 4721* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. 4722 (line 37) 4723* expand-tilde: Readline Init File Syntax. 4724 (line 158) 4725* forward-backward-delete-char (): Commands For Text. (line 21) 4726* forward-char (C-f): Commands For Moving. (line 12) 4727* forward-search-history (C-s): Commands For History. 4728 (line 32) 4729* forward-word (M-f): Commands For Moving. (line 18) 4730* history-preserve-point: Readline Init File Syntax. 4731 (line 162) 4732* history-search-backward (): Commands For History. 4733 (line 56) 4734* history-search-forward (): Commands For History. 4735 (line 50) 4736* history-size: Readline Init File Syntax. 4737 (line 168) 4738* history-substring-search-backward (): Commands For History. 4739 (line 68) 4740* history-substring-search-forward (): Commands For History. 4741 (line 62) 4742* horizontal-scroll-mode: Readline Init File Syntax. 4743 (line 177) 4744* input-meta: Readline Init File Syntax. 4745 (line 186) 4746* insert-comment (M-#): Miscellaneous Commands. 4747 (line 61) 4748* insert-completions (M-*): Commands For Completion. 4749 (line 18) 4750* isearch-terminators: Readline Init File Syntax. 4751 (line 194) 4752* keymap: Readline Init File Syntax. 4753 (line 201) 4754* kill-line (C-k): Commands For Killing. 4755 (line 6) 4756* kill-region (): Commands For Killing. 4757 (line 52) 4758* kill-whole-line (): Commands For Killing. 4759 (line 19) 4760* kill-word (M-d): Commands For Killing. 4761 (line 23) 4762* mark-modified-lines: Readline Init File Syntax. 4763 (line 231) 4764* mark-symlinked-directories: Readline Init File Syntax. 4765 (line 236) 4766* match-hidden-files: Readline Init File Syntax. 4767 (line 241) 4768* menu-complete (): Commands For Completion. 4769 (line 22) 4770* menu-complete-backward (): Commands For Completion. 4771 (line 34) 4772* menu-complete-display-prefix: Readline Init File Syntax. 4773 (line 248) 4774* meta-flag: Readline Init File Syntax. 4775 (line 186) 4776* next-history (C-n): Commands For History. 4777 (line 16) 4778* next-screen-line (): Commands For Moving. (line 33) 4779* non-incremental-forward-search-history (M-n): Commands For History. 4780 (line 44) 4781* non-incremental-reverse-search-history (M-p): Commands For History. 4782 (line 38) 4783* operate-and-get-next (C-o): Commands For History. 4784 (line 95) 4785* output-meta: Readline Init File Syntax. 4786 (line 253) 4787* overwrite-mode (): Commands For Text. (line 73) 4788* page-completions: Readline Init File Syntax. 4789 (line 259) 4790* possible-completions (M-?): Commands For Completion. 4791 (line 11) 4792* prefix-meta (<ESC>): Miscellaneous Commands. 4793 (line 19) 4794* previous-history (C-p): Commands For History. 4795 (line 12) 4796* previous-screen-line (): Commands For Moving. (line 26) 4797* print-last-kbd-macro (): Keyboard Macros. (line 17) 4798* quoted-insert (C-q or C-v): Commands For Text. (line 26) 4799* re-read-init-file (C-x C-r): Miscellaneous Commands. 4800 (line 6) 4801* readline: Basic Behavior. (line 12) 4802* redraw-current-line (): Commands For Moving. (line 49) 4803* reverse-search-history (C-r): Commands For History. 4804 (line 26) 4805* revert-all-at-newline: Readline Init File Syntax. 4806 (line 269) 4807* revert-line (M-r): Miscellaneous Commands. 4808 (line 26) 4809* rl_activate_mark: Miscellaneous Functions. 4810 (line 55) 4811* rl_add_defun: Function Naming. (line 18) 4812* rl_add_funmap_entry: Associating Function Names and Bindings. 4813 (line 54) 4814* rl_add_undo: Allowing Undoing. (line 39) 4815* rl_alphabetic: Utility Functions. (line 38) 4816* rl_already_prompted: Readline Variables. (line 63) 4817* rl_attempted_completion_function: Completion Variables. 4818 (line 11) 4819* rl_attempted_completion_over: Completion Variables. 4820 (line 255) 4821* rl_basic_quote_characters: Completion Variables. 4822 (line 143) 4823* rl_basic_word_break_characters: Completion Variables. 4824 (line 137) 4825* rl_begin_undo_group: Allowing Undoing. (line 28) 4826* rl_binding_keymap: Readline Variables. (line 184) 4827* rl_bind_key: Binding Keys. (line 21) 4828* rl_bind_keyseq: Binding Keys. (line 57) 4829* rl_bind_keyseq_if_unbound: Binding Keys. (line 75) 4830* rl_bind_keyseq_if_unbound_in_map: Binding Keys. (line 81) 4831* rl_bind_keyseq_in_map: Binding Keys. (line 64) 4832* rl_bind_key_if_unbound: Binding Keys. (line 30) 4833* rl_bind_key_if_unbound_in_map: Binding Keys. (line 36) 4834* rl_bind_key_in_map: Binding Keys. (line 25) 4835* rl_callback_handler_install: Alternate Interface. (line 13) 4836* rl_callback_handler_remove: Alternate Interface. (line 42) 4837* rl_callback_read_char: Alternate Interface. (line 22) 4838* rl_callback_sigcleanup: Alternate Interface. (line 35) 4839* rl_catch_signals: Readline Signal Handling. 4840 (line 69) 4841* rl_catch_sigwinch: Readline Signal Handling. 4842 (line 76) 4843* rl_change_environment: Readline Signal Handling. 4844 (line 90) 4845* rl_char_is_quoted_p: Completion Variables. 4846 (line 45) 4847* rl_check_signals: Readline Signal Handling. 4848 (line 133) 4849* rl_cleanup_after_signal: Readline Signal Handling. 4850 (line 107) 4851* rl_clear_history: Miscellaneous Functions. 4852 (line 49) 4853* rl_clear_message: Redisplay. (line 51) 4854* rl_clear_pending_input: Character Input. (line 29) 4855* rl_clear_signals: Readline Signal Handling. 4856 (line 182) 4857* rl_clear_visible_line: Redisplay. (line 25) 4858* rl_complete: How Completing Works. 4859 (line 46) 4860* rl_complete <1>: Completion Functions. 4861 (line 19) 4862* rl_completer_quote_characters: Completion Variables. 4863 (line 160) 4864* rl_completer_word_break_characters: Completion Variables. 4865 (line 146) 4866* rl_complete_internal: Completion Functions. 4867 (line 9) 4868* rl_completion_append_character: Completion Variables. 4869 (line 184) 4870* rl_completion_display_matches_hook: Completion Variables. 4871 (line 124) 4872* rl_completion_entry_function: How Completing Works. 4873 (line 52) 4874* rl_completion_entry_function <1>: Completion Variables. 4875 (line 6) 4876* rl_completion_found_quote: Completion Variables. 4877 (line 214) 4878* rl_completion_invoking_key: Completion Variables. 4879 (line 278) 4880* rl_completion_mark_symlink_dirs: Completion Variables. 4881 (line 220) 4882* rl_completion_matches: Completion Functions. 4883 (line 43) 4884* rl_completion_mode: Completion Functions. 4885 (line 36) 4886* rl_completion_query_items: Completion Variables. 4887 (line 178) 4888* rl_completion_quote_character: Completion Variables. 4889 (line 202) 4890* rl_completion_suppress_append: Completion Variables. 4891 (line 196) 4892* rl_completion_suppress_quote: Completion Variables. 4893 (line 208) 4894* rl_completion_type: Completion Variables. 4895 (line 270) 4896* rl_completion_word_break_hook: Completion Variables. 4897 (line 151) 4898* rl_copy_keymap: Keymaps. (line 16) 4899* rl_copy_text: Modifying Text. (line 14) 4900* rl_crlf: Redisplay. (line 33) 4901* rl_deactivate_mark: Miscellaneous Functions. 4902 (line 62) 4903* rl_delete_text: Modifying Text. (line 10) 4904* rl_deprep_terminal: Terminal Management. (line 12) 4905* rl_deprep_term_function: Readline Variables. (line 174) 4906* rl_ding: Utility Functions. (line 35) 4907* rl_directory_completion_hook: Completion Variables. 4908 (line 63) 4909* rl_directory_rewrite_hook;: Completion Variables. 4910 (line 81) 4911* rl_discard_keymap: Keymaps. (line 25) 4912* rl_dispatching: Readline Variables. (line 40) 4913* rl_display_match_list: Utility Functions. (line 41) 4914* rl_display_prompt: Readline Variables. (line 58) 4915* rl_done: Readline Variables. (line 27) 4916* rl_do_undo: Allowing Undoing. (line 47) 4917* rl_echo_signal_char: Readline Signal Handling. 4918 (line 143) 4919* rl_editing_mode: Readline Variables. (line 281) 4920* rl_empty_keymap: Keymaps. (line 33) 4921* rl_end: Readline Variables. (line 18) 4922* rl_end_undo_group: Allowing Undoing. (line 34) 4923* rl_erase_empty_line: Readline Variables. (line 46) 4924* rl_event_hook: Readline Variables. (line 123) 4925* rl_execute_next: Character Input. (line 25) 4926* rl_executing_key: Readline Variables. (line 191) 4927* rl_executing_keymap: Readline Variables. (line 180) 4928* rl_executing_keyseq: Readline Variables. (line 195) 4929* rl_executing_macro: Readline Variables. (line 188) 4930* rl_expand_prompt: Redisplay. (line 66) 4931* rl_explicit_arg: Readline Variables. (line 272) 4932* rl_extend_line_buffer: Utility Functions. (line 26) 4933* rl_filename_completion_desired: Completion Variables. 4934 (line 235) 4935* rl_filename_completion_function: Completion Functions. 4936 (line 57) 4937* rl_filename_dequoting_function: Completion Variables. 4938 (line 36) 4939* rl_filename_quote_characters: Completion Variables. 4940 (line 166) 4941* rl_filename_quoting_desired: Completion Variables. 4942 (line 245) 4943* rl_filename_quoting_function: Completion Variables. 4944 (line 23) 4945* rl_filename_rewrite_hook: Completion Variables. 4946 (line 109) 4947* rl_filename_stat_hook: Completion Variables. 4948 (line 97) 4949* rl_forced_update_display: Redisplay. (line 10) 4950* rl_free: Utility Functions. (line 17) 4951* rl_free_keymap: Keymaps. (line 29) 4952* rl_free_line_state: Readline Signal Handling. 4953 (line 113) 4954* rl_free_undo_list: Allowing Undoing. (line 44) 4955* rl_function_dumper: Associating Function Names and Bindings. 4956 (line 38) 4957* rl_function_of_keyseq: Associating Function Names and Bindings. 4958 (line 13) 4959* rl_function_of_keyseq_len: Associating Function Names and Bindings. 4960 (line 22) 4961* rl_funmap_names: Associating Function Names and Bindings. 4962 (line 48) 4963* rl_generic_bind: Binding Keys. (line 87) 4964* rl_getc: Character Input. (line 14) 4965* rl_getc_function: Readline Variables. (line 128) 4966* rl_get_keymap: Keymaps. (line 40) 4967* rl_get_keymap_by_name: Keymaps. (line 46) 4968* rl_get_keymap_name: Keymaps. (line 51) 4969* rl_get_screen_size: Readline Signal Handling. 4970 (line 165) 4971* rl_get_termcap: Miscellaneous Functions. 4972 (line 41) 4973* rl_gnu_readline_p: Readline Variables. (line 82) 4974* rl_ignore_completion_duplicates: Completion Variables. 4975 (line 231) 4976* rl_ignore_some_completions_function: Completion Variables. 4977 (line 55) 4978* rl_inhibit_completion: Completion Variables. 4979 (line 284) 4980* rl_initialize: Utility Functions. (line 30) 4981* rl_input_available_hook: Readline Variables. (line 140) 4982* rl_insert_completions: Completion Functions. 4983 (line 31) 4984* rl_insert_text: Modifying Text. (line 6) 4985* rl_instream: Readline Variables. (line 96) 4986* rl_invoking_keyseqs: Associating Function Names and Bindings. 4987 (line 29) 4988* rl_invoking_keyseqs_in_map: Associating Function Names and Bindings. 4989 (line 33) 4990* rl_keep_mark_active: Miscellaneous Functions. 4991 (line 65) 4992* rl_key_sequence_length: Readline Variables. (line 199) 4993* rl_kill_text: Modifying Text. (line 18) 4994* rl_last_func: Readline Variables. (line 109) 4995* rl_library_version: Readline Variables. (line 72) 4996* rl_line_buffer: Readline Variables. (line 8) 4997* rl_list_funmap_names: Associating Function Names and Bindings. 4998 (line 44) 4999* rl_macro_bind: Miscellaneous Functions. 5000 (line 6) 5001* rl_macro_dumper: Miscellaneous Functions. 5002 (line 13) 5003* rl_make_bare_keymap: Keymaps. (line 11) 5004* rl_make_keymap: Keymaps. (line 19) 5005* rl_mark: Readline Variables. (line 23) 5006* rl_mark_active_p: Miscellaneous Functions. 5007 (line 71) 5008* rl_message: Redisplay. (line 42) 5009* rl_modifying: Allowing Undoing. (line 56) 5010* rl_named_function: Associating Function Names and Bindings. 5011 (line 10) 5012* rl_numeric_arg: Readline Variables. (line 276) 5013* rl_num_chars_to_read: Readline Variables. (line 31) 5014* rl_on_new_line: Redisplay. (line 14) 5015* rl_on_new_line_with_prompt: Redisplay. (line 18) 5016* rl_outstream: Readline Variables. (line 100) 5017* rl_parse_and_bind: Binding Keys. (line 95) 5018* rl_pending_input: Readline Variables. (line 36) 5019* rl_pending_signal: Readline Signal Handling. 5020 (line 102) 5021* rl_persistent_signal_handlers: Readline Signal Handling. 5022 (line 82) 5023* rl_point: Readline Variables. (line 14) 5024* rl_possible_completions: Completion Functions. 5025 (line 27) 5026* rl_prefer_env_winsize: Readline Variables. (line 104) 5027* rl_prep_terminal: Terminal Management. (line 6) 5028* rl_prep_term_function: Readline Variables. (line 167) 5029* rl_pre_input_hook: Readline Variables. (line 118) 5030* rl_prompt: Readline Variables. (line 52) 5031* rl_push_macro_input: Modifying Text. (line 25) 5032* rl_readline_name: Readline Variables. (line 91) 5033* rl_readline_state: Readline Variables. (line 202) 5034* rl_readline_version: Readline Variables. (line 75) 5035* rl_read_init_file: Binding Keys. (line 100) 5036* rl_read_key: Character Input. (line 6) 5037* rl_redisplay: Redisplay. (line 6) 5038* rl_redisplay_function: Readline Variables. (line 161) 5039* rl_replace_line: Utility Functions. (line 21) 5040* rl_reset_after_signal: Readline Signal Handling. 5041 (line 121) 5042* rl_reset_line_state: Redisplay. (line 29) 5043* rl_reset_screen_size: Readline Signal Handling. 5044 (line 169) 5045* rl_reset_terminal: Terminal Management. (line 34) 5046* rl_resize_terminal: Readline Signal Handling. 5047 (line 149) 5048* rl_restore_prompt: Redisplay. (line 60) 5049* rl_restore_state: Utility Functions. (line 11) 5050* rl_save_prompt: Redisplay. (line 56) 5051* rl_save_state: Utility Functions. (line 6) 5052* rl_set_key: Binding Keys. (line 71) 5053* rl_set_keyboard_input_timeout: Character Input. (line 34) 5054* rl_set_keymap: Keymaps. (line 43) 5055* rl_set_keymap_name: Keymaps. (line 56) 5056* rl_set_paren_blink_timeout: Miscellaneous Functions. 5057 (line 36) 5058* rl_set_prompt: Redisplay. (line 80) 5059* rl_set_screen_size: Readline Signal Handling. 5060 (line 153) 5061* rl_set_signals: Readline Signal Handling. 5062 (line 176) 5063* rl_show_char: Redisplay. (line 36) 5064* rl_signal_event_hook: Readline Variables. (line 136) 5065* rl_sort_completion_matches: Completion Variables. 5066 (line 262) 5067* rl_special_prefixes: Completion Variables. 5068 (line 171) 5069* rl_startup_hook: Readline Variables. (line 114) 5070* rl_stuff_char: Character Input. (line 18) 5071* rl_terminal_name: Readline Variables. (line 86) 5072* rl_tty_set_default_bindings: Terminal Management. (line 17) 5073* rl_tty_set_echoing: Terminal Management. (line 27) 5074* rl_tty_unset_default_bindings: Terminal Management. (line 22) 5075* rl_unbind_command_in_map: Binding Keys. (line 53) 5076* rl_unbind_function_in_map: Binding Keys. (line 49) 5077* rl_unbind_key: Binding Keys. (line 41) 5078* rl_unbind_key_in_map: Binding Keys. (line 45) 5079* rl_username_completion_function: Completion Functions. 5080 (line 64) 5081* rl_variable_bind: Miscellaneous Functions. 5082 (line 19) 5083* rl_variable_dumper: Miscellaneous Functions. 5084 (line 30) 5085* rl_variable_value: Miscellaneous Functions. 5086 (line 25) 5087* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 33) 5088* set-mark (C-@): Miscellaneous Commands. 5089 (line 33) 5090* shell-transpose-words (M-C-t): Commands For Killing. 5091 (line 32) 5092* show-all-if-ambiguous: Readline Init File Syntax. 5093 (line 275) 5094* show-all-if-unmodified: Readline Init File Syntax. 5095 (line 281) 5096* show-mode-in-prompt: Readline Init File Syntax. 5097 (line 290) 5098* skip-completed-text: Readline Init File Syntax. 5099 (line 296) 5100* skip-csi-sequence (): Miscellaneous Commands. 5101 (line 52) 5102* start-kbd-macro (C-x (): Keyboard Macros. (line 6) 5103* tab-insert (M-<TAB>): Commands For Text. (line 30) 5104* tilde-expand (M-~): Miscellaneous Commands. 5105 (line 30) 5106* transpose-chars (C-t): Commands For Text. (line 50) 5107* transpose-words (M-t): Commands For Text. (line 56) 5108* undo (C-_ or C-x C-u): Miscellaneous Commands. 5109 (line 23) 5110* universal-argument (): Numeric Arguments. (line 10) 5111* unix-filename-rubout (): Commands For Killing. 5112 (line 43) 5113* unix-line-discard (C-u): Commands For Killing. 5114 (line 16) 5115* unix-word-rubout (C-w): Commands For Killing. 5116 (line 39) 5117* upcase-word (M-u): Commands For Text. (line 61) 5118* vi-cmd-mode-string: Readline Init File Syntax. 5119 (line 309) 5120* vi-editing-mode (M-C-j): Miscellaneous Commands. 5121 (line 92) 5122* vi-ins-mode-string: Readline Init File Syntax. 5123 (line 320) 5124* visible-stats: Readline Init File Syntax. 5125 (line 331) 5126* yank (C-y): Commands For Killing. 5127 (line 70) 5128* yank-last-arg (M-. or M-_): Commands For History. 5129 (line 83) 5130* yank-nth-arg (M-C-y): Commands For History. 5131 (line 74) 5132* yank-pop (M-y): Commands For Killing. 5133 (line 73) 5134 5135 5136 5137Tag Table: 5138Node: Top864 5139Node: Command Line Editing1589 5140Node: Introduction and Notation2241 5141Node: Readline Interaction3865 5142Node: Readline Bare Essentials5057 5143Node: Readline Movement Commands6841 5144Node: Readline Killing Commands7802 5145Node: Readline Arguments9721 5146Node: Searching10766 5147Node: Readline Init File12919 5148Node: Readline Init File Syntax14073 5149Node: Conditional Init Constructs34331 5150Node: Sample Init File38528 5151Node: Bindable Readline Commands41653 5152Node: Commands For Moving42708 5153Node: Commands For History44467 5154Node: Commands For Text49230 5155Node: Commands For Killing52933 5156Node: Numeric Arguments55647 5157Node: Commands For Completion56787 5158Node: Keyboard Macros58756 5159Node: Miscellaneous Commands59444 5160Node: Readline vi Mode63366 5161Node: Programming with GNU Readline65183 5162Node: Basic Behavior66169 5163Node: Custom Functions69852 5164Node: Readline Typedefs71335 5165Node: Function Writing72969 5166Node: Readline Variables74283 5167Node: Readline Convenience Functions86955 5168Node: Function Naming88027 5169Node: Keymaps89289 5170Node: Binding Keys92368 5171Node: Associating Function Names and Bindings96916 5172Node: Allowing Undoing99695 5173Node: Redisplay102245 5174Node: Modifying Text106269 5175Node: Character Input107516 5176Node: Terminal Management109414 5177Node: Utility Functions111237 5178Node: Miscellaneous Functions114565 5179Node: Alternate Interface117984 5180Node: A Readline Example120726 5181Node: Alternate Interface Example122665 5182Node: Readline Signal Handling126197 5183Node: Custom Completers135456 5184Node: How Completing Works136176 5185Node: Completion Functions139483 5186Node: Completion Variables143057 5187Node: A Short Completion Example158850 5188Node: GNU Free Documentation License171630 5189Node: Concept Index196804 5190Node: Function and Variable Index198325 5191 5192End Tag Table 5193 5194 5195Local Variables: 5196coding: utf-8 5197End: 5198