1 This is readline.info, produced by makeinfo version 4.7 from
4 This manual describes the GNU Readline Library (version 5.2, 9
5 February 2006), a library which aids in the consistency of user
6 interface across discrete programs which provide a command line
9 Copyright (C) 1988-2004 Free Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
15 Permission is granted to copy, distribute and/or modify this
16 document under the terms of the GNU Free Documentation License,
17 Version 1.1 or any later version published by the Free Software
18 Foundation; with no Invariant Sections, with the Front-Cover texts
19 being "A GNU Manual," and with the Back-Cover Texts as in (a)
20 below. A copy of the license is included in the section entitled
21 "GNU Free Documentation License."
23 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
24 modify this GNU Manual, like GNU software. Copies published by
25 the Free Software Foundation raise funds for GNU development."
27 INFO-DIR-SECTION Libraries
29 * Readline: (readline). The GNU readline library API.
33 File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir)
38 This document describes the GNU Readline Library, a utility which aids
39 in the consistency of user interface across discrete programs which
40 provide a command line interface.
44 * Command Line Editing:: GNU Readline User's Manual.
45 * Programming with GNU Readline:: GNU Readline Programmer's Manual.
46 * Copying This Manual:: Copying this manual.
47 * Concept Index:: Index of concepts described in this manual.
48 * Function and Variable Index:: Index of externally visible functions
52 File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top
54 1 Command Line Editing
55 **********************
57 This chapter describes the basic features of the GNU command line
62 * Introduction and Notation:: Notation used in this text.
63 * Readline Interaction:: The minimum set of commands for editing a line.
64 * Readline Init File:: Customizing Readline from a user's view.
65 * Bindable Readline Commands:: A description of most of the Readline commands
67 * Readline vi Mode:: A short description of how to make Readline
68 behave like the vi editor.
71 File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
73 1.1 Introduction to Line Editing
74 ================================
76 The following paragraphs describe the notation used to represent
79 The text `C-k' is read as `Control-K' and describes the character
80 produced when the <k> key is pressed while the Control key is depressed.
82 The text `M-k' is read as `Meta-K' and describes the character
83 produced when the Meta key (if you have one) is depressed, and the <k>
84 key is pressed. The Meta key is labeled <ALT> on many keyboards. On
85 keyboards with two keys labeled <ALT> (usually to either side of the
86 space bar), the <ALT> on the left side is generally set to work as a
87 Meta key. The <ALT> key on the right may also be configured to work as
88 a Meta key or may be configured as some other modifier, such as a
89 Compose key for typing accented characters.
91 If you do not have a Meta or <ALT> key, or another key working as a
92 Meta key, the identical keystroke can be generated by typing <ESC>
93 _first_, and then typing <k>. Either process is known as "metafying"
96 The text `M-C-k' is read as `Meta-Control-k' and describes the
97 character produced by "metafying" `C-k'.
99 In addition, several keys have their own names. Specifically,
100 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
101 when seen in this text, or in an init file (*note Readline Init File::).
102 If your keyboard lacks a <LFD> key, typing <C-j> will produce the
103 desired character. The <RET> key may be labeled <Return> or <Enter> on
107 File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
109 1.2 Readline Interaction
110 ========================
112 Often during an interactive session you type in a long line of text,
113 only to notice that the first word on the line is misspelled. The
114 Readline library gives you a set of commands for manipulating the text
115 as you type it in, allowing you to just fix your typo, and not forcing
116 you to retype the majority of the line. Using these editing commands,
117 you move the cursor to the place that needs correction, and delete or
118 insert the text of the corrections. Then, when you are satisfied with
119 the line, you simply press <RET>. You do not have to be at the end of
120 the line to press <RET>; the entire line is accepted regardless of the
121 location of the cursor within the line.
125 * Readline Bare Essentials:: The least you need to know about Readline.
126 * Readline Movement Commands:: Moving about the input line.
127 * Readline Killing Commands:: How to delete text, and how to get it back!
128 * Readline Arguments:: Giving numeric arguments to commands.
129 * Searching:: Searching through previous lines.
132 File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
134 1.2.1 Readline Bare Essentials
135 ------------------------------
137 In order to enter characters into the line, simply type them. The typed
138 character appears where the cursor was, and then the cursor moves one
139 space to the right. If you mistype a character, you can use your erase
140 character to back up and delete the mistyped character.
142 Sometimes you may mistype a character, and not notice the error
143 until you have typed several other characters. In that case, you can
144 type `C-b' to move the cursor to the left, and then correct your
145 mistake. Afterwards, you can move the cursor to the right with `C-f'.
147 When you add text in the middle of a line, you will notice that
148 characters to the right of the cursor are `pushed over' to make room
149 for the text that you have inserted. Likewise, when you delete text
150 behind the cursor, characters to the right of the cursor are `pulled
151 back' to fill in the blank space created by the removal of the text. A
152 list of the bare essentials for editing the text of an input line
156 Move back one character.
159 Move forward one character.
162 Delete the character to the left of the cursor.
165 Delete the character underneath the cursor.
168 Insert the character into the line at the cursor.
171 Undo the last editing command. You can undo all the way back to an
174 (Depending on your configuration, the <Backspace> key be set to delete
175 the character to the left of the cursor and the <DEL> key set to delete
176 the character underneath the cursor, like `C-d', rather than the
177 character to the left of the cursor.)
180 File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
182 1.2.2 Readline Movement Commands
183 --------------------------------
185 The above table describes the most basic keystrokes that you need in
186 order to do editing of the input line. For your convenience, many
187 other commands have been added in addition to `C-b', `C-f', `C-d', and
188 <DEL>. Here are some commands for moving more rapidly about the line.
191 Move to the start of the line.
194 Move to the end of the line.
197 Move forward a word, where a word is composed of letters and
201 Move backward a word.
204 Clear the screen, reprinting the current line at the top.
206 Notice how `C-f' moves forward a character, while `M-f' moves
207 forward a word. It is a loose convention that control keystrokes
208 operate on characters while meta keystrokes operate on words.
211 File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
213 1.2.3 Readline Killing Commands
214 -------------------------------
216 "Killing" text means to delete the text from the line, but to save it
217 away for later use, usually by "yanking" (re-inserting) it back into
218 the line. (`Cut' and `paste' are more recent jargon for `kill' and
221 If the description for a command says that it `kills' text, then you
222 can be sure that you can get the text back in a different (or the same)
225 When you use a kill command, the text is saved in a "kill-ring".
226 Any number of consecutive kills save all of the killed text together, so
227 that when you yank it back, you get it all. The kill ring is not line
228 specific; the text that you killed on a previously typed line is
229 available to be yanked back later, when you are typing another line.
231 Here is the list of commands for killing text.
234 Kill the text from the current cursor position to the end of the
238 Kill from the cursor to the end of the current word, or, if between
239 words, to the end of the next word. Word boundaries are the same
240 as those used by `M-f'.
243 Kill from the cursor the start of the current word, or, if between
244 words, to the start of the previous word. Word boundaries are the
245 same as those used by `M-b'.
248 Kill from the cursor to the previous whitespace. This is
249 different than `M-<DEL>' because the word boundaries differ.
252 Here is how to "yank" the text back into the line. Yanking means to
253 copy the most-recently-killed text from the kill buffer.
256 Yank the most recently killed text back into the buffer at the
260 Rotate the kill-ring, and yank the new top. You can only do this
261 if the prior command is `C-y' or `M-y'.
264 File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
266 1.2.4 Readline Arguments
267 ------------------------
269 You can pass numeric arguments to Readline commands. Sometimes the
270 argument acts as a repeat count, other times it is the sign of the
271 argument that is significant. If you pass a negative argument to a
272 command which normally acts in a forward direction, that command will
273 act in a backward direction. For example, to kill text back to the
274 start of the line, you might type `M-- C-k'.
276 The general way to pass numeric arguments to a command is to type
277 meta digits before the command. If the first `digit' typed is a minus
278 sign (`-'), then the sign of the argument will be negative. Once you
279 have typed one meta digit to get the argument started, you can type the
280 remainder of the digits, and then the command. For example, to give
281 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
282 will delete the next ten characters on the input line.
285 File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
287 1.2.5 Searching for Commands in the History
288 -------------------------------------------
290 Readline provides commands for searching through the command history
291 for lines containing a specified string. There are two search modes:
292 "incremental" and "non-incremental".
294 Incremental searches begin before the user has finished typing the
295 search string. As each character of the search string is typed,
296 Readline displays the next entry from the history matching the string
297 typed so far. An incremental search requires only as many characters
298 as needed to find the desired history entry. To search backward in the
299 history for a particular string, type `C-r'. Typing `C-s' searches
300 forward through the history. The characters present in the value of
301 the `isearch-terminators' variable are used to terminate an incremental
302 search. If that variable has not been assigned a value, the <ESC> and
303 `C-J' characters will terminate an incremental search. `C-g' will
304 abort an incremental search and restore the original line. When the
305 search is terminated, the history entry containing the search string
306 becomes the current line.
308 To find other matching entries in the history list, type `C-r' or
309 `C-s' as appropriate. This will search backward or forward in the
310 history for the next entry matching the search string typed so far.
311 Any other key sequence bound to a Readline command will terminate the
312 search and execute that command. For instance, a <RET> will terminate
313 the search and accept the line, thereby executing the command from the
314 history list. A movement command will terminate the search, make the
315 last line found the current line, and begin editing.
317 Readline remembers the last incremental search string. If two
318 `C-r's are typed without any intervening characters defining a new
319 search string, any remembered search string is used.
321 Non-incremental searches read the entire search string before
322 starting to search for matching history lines. The search string may be
323 typed by the user or be part of the contents of the current line.
326 File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
328 1.3 Readline Init File
329 ======================
331 Although the Readline library comes with a set of Emacs-like
332 keybindings installed by default, it is possible to use a different set
333 of keybindings. Any user can customize programs that use Readline by
334 putting commands in an "inputrc" file, conventionally in his home
335 directory. The name of this file is taken from the value of the
336 environment variable `INPUTRC'. If that variable is unset, the default
337 is `~/.inputrc'. If that file does not exist or cannot be read, the
338 ultimate default is `/etc/inputrc'.
340 When a program which uses the Readline library starts up, the init
341 file is read, and the key bindings are set.
343 In addition, the `C-x C-r' command re-reads this init file, thus
344 incorporating any changes that you might have made to it.
348 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
350 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
352 * Sample Init File:: An example inputrc file.
355 File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
357 1.3.1 Readline Init File Syntax
358 -------------------------------
360 There are only a few basic constructs allowed in the Readline init
361 file. Blank lines are ignored. Lines beginning with a `#' are
362 comments. Lines beginning with a `$' indicate conditional constructs
363 (*note Conditional Init Constructs::). Other lines denote variable
364 settings and key bindings.
367 You can modify the run-time behavior of Readline by altering the
368 values of variables in Readline using the `set' command within the
369 init file. The syntax is simple:
373 Here, for example, is how to change from the default Emacs-like
374 key binding to use `vi' line editing commands:
378 Variable names and values, where appropriate, are recognized
379 without regard to case. Unrecognized variable names are ignored.
381 Boolean variables (those that can be set to on or off) are set to
382 on if the value is null or empty, ON (case-insensitive), or 1.
383 Any other value results in the variable being set to off.
385 A great deal of run-time behavior is changeable with the following
389 Controls what happens when Readline wants to ring the
390 terminal bell. If set to `none', Readline never rings the
391 bell. If set to `visible', Readline uses a visible bell if
392 one is available. If set to `audible' (the default),
393 Readline attempts to ring the terminal's bell.
395 `bind-tty-special-chars'
396 If set to `on', Readline attempts to bind the control
397 characters treated specially by the kernel's terminal driver
398 to their Readline equivalents.
401 The string to insert at the beginning of the line when the
402 `insert-comment' command is executed. The default value is
405 `completion-ignore-case'
406 If set to `on', Readline performs filename matching and
407 completion in a case-insensitive fashion. The default value
410 `completion-query-items'
411 The number of possible completions that determines when the
412 user is asked whether the list of possibilities should be
413 displayed. If the number of possible completions is greater
414 than this value, Readline will ask the user whether or not he
415 wishes to view them; otherwise, they are simply listed. This
416 variable must be set to an integer value greater than or
417 equal to 0. A negative value means Readline should never ask.
418 The default limit is `100'.
421 If set to `on', Readline will convert characters with the
422 eighth bit set to an ASCII key sequence by stripping the
423 eighth bit and prefixing an <ESC> character, converting them
424 to a meta-prefixed key sequence. The default value is `on'.
427 If set to `On', Readline will inhibit word completion.
428 Completion characters will be inserted into the line as if
429 they had been mapped to `self-insert'. The default is `off'.
432 The `editing-mode' variable controls which default set of key
433 bindings is used. By default, Readline starts up in Emacs
434 editing mode, where the keystrokes are most similar to Emacs.
435 This variable can be set to either `emacs' or `vi'.
438 When set to `on', Readline will try to enable the application
439 keypad when it is called. Some systems need this to enable
440 the arrow keys. The default is `off'.
443 If set to `on', tilde expansion is performed when Readline
444 attempts word completion. The default is `off'.
446 `history-preserve-point'
447 If set to `on', the history code attempts to place point at
448 the same location on each history line retrieved with
449 `previous-history' or `next-history'. The default is `off'.
451 `horizontal-scroll-mode'
452 This variable can be set to either `on' or `off'. Setting it
453 to `on' means that the text of the lines being edited will
454 scroll horizontally on a single screen line when they are
455 longer than the width of the screen, instead of wrapping onto
456 a new screen line. By default, this variable is set to `off'.
459 If set to `on', Readline will enable eight-bit input (it will
460 not clear the eighth bit in the characters it reads),
461 regardless of what the terminal claims it can support. The
462 default value is `off'. The name `meta-flag' is a synonym
465 `isearch-terminators'
466 The string of characters that should terminate an incremental
467 search without subsequently executing the character as a
468 command (*note Searching::). If this variable has not been
469 given a value, the characters <ESC> and `C-J' will terminate
470 an incremental search.
473 Sets Readline's idea of the current keymap for key binding
474 commands. Acceptable `keymap' names are `emacs',
475 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
476 `vi-command', and `vi-insert'. `vi' is equivalent to
477 `vi-command'; `emacs' is equivalent to `emacs-standard'. The
478 default value is `emacs'. The value of the `editing-mode'
479 variable also affects the default keymap.
482 If set to `on', completed directory names have a slash
483 appended. The default is `on'.
485 `mark-modified-lines'
486 This variable, when set to `on', causes Readline to display an
487 asterisk (`*') at the start of history lines which have been
488 modified. This variable is `off' by default.
490 `mark-symlinked-directories'
491 If set to `on', completed names which are symbolic links to
492 directories have a slash appended (subject to the value of
493 `mark-directories'). The default is `off'.
496 This variable, when set to `on', causes Readline to match
497 files whose names begin with a `.' (hidden files) when
498 performing filename completion, unless the leading `.' is
499 supplied by the user in the filename to be completed. This
500 variable is `on' by default.
503 If set to `on', Readline will display characters with the
504 eighth bit set directly rather than as a meta-prefixed escape
505 sequence. The default is `off'.
508 If set to `on', Readline uses an internal `more'-like pager
509 to display a screenful of possible completions at a time.
510 This variable is `on' by default.
512 `print-completions-horizontally'
513 If set to `on', Readline will display completions with matches
514 sorted horizontally in alphabetical order, rather than down
515 the screen. The default is `off'.
517 `show-all-if-ambiguous'
518 This alters the default behavior of the completion functions.
519 If set to `on', words which have more than one possible
520 completion cause the matches to be listed immediately instead
521 of ringing the bell. The default value is `off'.
523 `show-all-if-unmodified'
524 This alters the default behavior of the completion functions
525 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
526 `on', words which have more than one possible completion
527 without any possible partial completion (the possible
528 completions don't share a common prefix) cause the matches to
529 be listed immediately instead of ringing the bell. The
530 default value is `off'.
533 If set to `on', a character denoting a file's type is
534 appended to the filename when listing possible completions.
535 The default is `off'.
539 The syntax for controlling key bindings in the init file is
540 simple. First you need to find the name of the command that you
541 want to change. The following sections contain tables of the
542 command name, the default keybinding, if any, and a short
543 description of what the command does.
545 Once you know the name of the command, simply place on a line in
546 the init file the name of the key you wish to bind the command to,
547 a colon, and then the name of the command. The name of the key
548 can be expressed in different ways, depending on what you find most
551 In addition to command names, readline allows keys to be bound to
552 a string that is inserted when the key is pressed (a MACRO).
554 KEYNAME: FUNCTION-NAME or MACRO
555 KEYNAME is the name of a key spelled out in English. For
557 Control-u: universal-argument
558 Meta-Rubout: backward-kill-word
559 Control-o: "> output"
561 In the above example, `C-u' is bound to the function
562 `universal-argument', `M-DEL' is bound to the function
563 `backward-kill-word', and `C-o' is bound to run the macro
564 expressed on the right hand side (that is, to insert the text
565 `> output' into the line).
567 A number of symbolic character names are recognized while
568 processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
569 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
571 "KEYSEQ": FUNCTION-NAME or MACRO
572 KEYSEQ differs from KEYNAME above in that strings denoting an
573 entire key sequence can be specified, by placing the key
574 sequence in double quotes. Some GNU Emacs style key escapes
575 can be used, as in the following example, but the special
576 character names are not recognized.
578 "\C-u": universal-argument
579 "\C-x\C-r": re-read-init-file
580 "\e[11~": "Function Key 1"
582 In the above example, `C-u' is again bound to the function
583 `universal-argument' (just as it was in the first example),
584 `C-x C-r' is bound to the function `re-read-init-file', and
585 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
589 The following GNU Emacs style escape sequences are available when
590 specifying key sequences:
605 <">, a double quotation mark
608 <'>, a single quote or apostrophe
610 In addition to the GNU Emacs style escape sequences, a second set
611 of backslash escapes is available:
638 the eight-bit character whose value is the octal value NNN
639 (one to three digits)
642 the eight-bit character whose value is the hexadecimal value
643 HH (one or two hex digits)
645 When entering the text of a macro, single or double quotes must be
646 used to indicate a macro definition. Unquoted text is assumed to
647 be a function name. In the macro body, the backslash escapes
648 described above are expanded. Backslash will quote any other
649 character in the macro text, including `"' and `''. For example,
650 the following binding will make `C-x \' insert a single `\' into
656 File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
658 1.3.2 Conditional Init Constructs
659 ---------------------------------
661 Readline implements a facility similar in spirit to the conditional
662 compilation features of the C preprocessor which allows key bindings
663 and variable settings to be performed as the result of tests. There
664 are four parser directives used.
667 The `$if' construct allows bindings to be made based on the
668 editing mode, the terminal being used, or the application using
669 Readline. The text of the test extends to the end of the line; no
670 characters are required to isolate it.
673 The `mode=' form of the `$if' directive is used to test
674 whether Readline is in `emacs' or `vi' mode. This may be
675 used in conjunction with the `set keymap' command, for
676 instance, to set bindings in the `emacs-standard' and
677 `emacs-ctlx' keymaps only if Readline is starting out in
681 The `term=' form may be used to include terminal-specific key
682 bindings, perhaps to bind the key sequences output by the
683 terminal's function keys. The word on the right side of the
684 `=' is tested against both the full name of the terminal and
685 the portion of the terminal name before the first `-'. This
686 allows `sun' to match both `sun' and `sun-cmd', for instance.
689 The APPLICATION construct is used to include
690 application-specific settings. Each program using the
691 Readline library sets the APPLICATION NAME, and you can test
692 for a particular value. This could be used to bind key
693 sequences to functions useful for a specific program. For
694 instance, the following command adds a key sequence that
695 quotes the current or previous word in Bash:
697 # Quote the current or previous word
698 "\C-xq": "\eb\"\ef\""
702 This command, as seen in the previous example, terminates an `$if'
706 Commands in this branch of the `$if' directive are executed if the
710 This directive takes a single filename as an argument and reads
711 commands and bindings from that file. For example, the following
712 directive reads from `/etc/inputrc':
713 $include /etc/inputrc
716 File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
718 1.3.3 Sample Init File
719 ----------------------
721 Here is an example of an INPUTRC file. This illustrates key binding,
722 variable assignment, and conditional syntax.
725 # This file controls the behaviour of line input editing for
726 # programs that use the GNU Readline library. Existing
727 # programs include FTP, Bash, and GDB.
729 # You can re-read the inputrc file with C-x C-r.
730 # Lines beginning with '#' are comments.
732 # First, include any systemwide bindings and variable
733 # assignments from /etc/Inputrc
734 $include /etc/Inputrc
737 # Set various bindings for emacs mode.
739 set editing-mode emacs
743 Meta-Control-h: backward-kill-word Text after the function name is ignored
746 # Arrow keys in keypad mode
748 #"\M-OD": backward-char
749 #"\M-OC": forward-char
750 #"\M-OA": previous-history
751 #"\M-OB": next-history
753 # Arrow keys in ANSI mode
755 "\M-[D": backward-char
756 "\M-[C": forward-char
757 "\M-[A": previous-history
758 "\M-[B": next-history
760 # Arrow keys in 8 bit keypad mode
762 #"\M-\C-OD": backward-char
763 #"\M-\C-OC": forward-char
764 #"\M-\C-OA": previous-history
765 #"\M-\C-OB": next-history
767 # Arrow keys in 8 bit ANSI mode
769 #"\M-\C-[D": backward-char
770 #"\M-\C-[C": forward-char
771 #"\M-\C-[A": previous-history
772 #"\M-\C-[B": next-history
778 # An old-style binding. This happens to be the default.
781 # Macros that are convenient for shell interaction
784 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
785 # prepare to type a quoted word --
786 # insert open and close double quotes
787 # and move to just after the open quote
789 # insert a backslash (testing backslash escapes
790 # in sequences and macros)
792 # Quote the current or previous word
793 "\C-xq": "\eb\"\ef\""
794 # Add a binding to refresh the line, which is unbound
795 "\C-xr": redraw-current-line
796 # Edit variable on current line.
797 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
800 # use a visible bell if one is available
801 set bell-style visible
803 # don't strip characters to 7 bits when reading
806 # allow iso-latin1 characters to be inserted rather
807 # than converted to prefix-meta sequences
810 # display characters with the eighth bit set directly
811 # rather than as meta-prefixed characters
814 # if there are more than 150 possible completions for
815 # a word, ask the user if he wants to see all of them
816 set completion-query-items 150
822 "\M-.": yank-last-arg
826 File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
828 1.4 Bindable Readline Commands
829 ==============================
833 * Commands For Moving:: Moving about the line.
834 * Commands For History:: Getting at previous lines.
835 * Commands For Text:: Commands for changing text.
836 * Commands For Killing:: Commands for killing and yanking.
837 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
838 * Commands For Completion:: Getting Readline to do the typing for you.
839 * Keyboard Macros:: Saving and re-executing typed characters
840 * Miscellaneous Commands:: Other miscellaneous commands.
842 This section describes Readline commands that may be bound to key
843 sequences. Command names without an accompanying key sequence are
846 In the following descriptions, "point" refers to the current cursor
847 position, and "mark" refers to a cursor position saved by the
848 `set-mark' command. The text between the point and mark is referred to
852 File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
854 1.4.1 Commands For Moving
855 -------------------------
857 `beginning-of-line (C-a)'
858 Move to the start of the current line.
861 Move to the end of the line.
864 Move forward a character.
866 `backward-char (C-b)'
867 Move back a character.
870 Move forward to the end of the next word. Words are composed of
873 `backward-word (M-b)'
874 Move back to the start of the current or previous word. Words are
875 composed of letters and digits.
878 Clear the screen and redraw the current line, leaving the current
879 line at the top of the screen.
881 `redraw-current-line ()'
882 Refresh the current line. By default, this is unbound.
886 File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
888 1.4.2 Commands For Manipulating The History
889 -------------------------------------------
891 `accept-line (Newline or Return)'
892 Accept the line regardless of where the cursor is. If this line is
893 non-empty, it may be added to the history list for future recall
894 with `add_history()'. If this line is a modified history line,
895 the history line is restored to its original state.
897 `previous-history (C-p)'
898 Move `back' through the history list, fetching the previous
902 Move `forward' through the history list, fetching the next command.
904 `beginning-of-history (M-<)'
905 Move to the first line in the history.
907 `end-of-history (M->)'
908 Move to the end of the input history, i.e., the line currently
911 `reverse-search-history (C-r)'
912 Search backward starting at the current line and moving `up'
913 through the history as necessary. This is an incremental search.
915 `forward-search-history (C-s)'
916 Search forward starting at the current line and moving `down'
917 through the the history as necessary. This is an incremental
920 `non-incremental-reverse-search-history (M-p)'
921 Search backward starting at the current line and moving `up'
922 through the history as necessary using a non-incremental search
923 for a string supplied by the user.
925 `non-incremental-forward-search-history (M-n)'
926 Search forward starting at the current line and moving `down'
927 through the the history as necessary using a non-incremental search
928 for a string supplied by the user.
930 `history-search-forward ()'
931 Search forward through the history for the string of characters
932 between the start of the current line and the point. This is a
933 non-incremental search. By default, this command is unbound.
935 `history-search-backward ()'
936 Search backward through the history for the string of characters
937 between the start of the current line and the point. This is a
938 non-incremental search. By default, this command is unbound.
940 `yank-nth-arg (M-C-y)'
941 Insert the first argument to the previous command (usually the
942 second word on the previous line) at point. With an argument N,
943 insert the Nth word from the previous command (the words in the
944 previous command begin with word 0). A negative argument inserts
945 the Nth word from the end of the previous command. Once the
946 argument N is computed, the argument is extracted as if the `!N'
947 history expansion had been specified.
949 `yank-last-arg (M-. or M-_)'
950 Insert last argument to the previous command (the last word of the
951 previous history entry). With an argument, behave exactly like
952 `yank-nth-arg'. Successive calls to `yank-last-arg' move back
953 through the history list, inserting the last argument of each line
954 in turn. The history expansion facilities are used to extract the
955 last argument, as if the `!$' history expansion had been specified.
959 File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
961 1.4.3 Commands For Changing Text
962 --------------------------------
965 Delete the character at point. If point is at the beginning of
966 the line, there are no characters in the line, and the last
967 character typed was not bound to `delete-char', then return EOF.
969 `backward-delete-char (Rubout)'
970 Delete the character behind the cursor. A numeric argument means
971 to kill the characters instead of deleting them.
973 `forward-backward-delete-char ()'
974 Delete the character under the cursor, unless the cursor is at the
975 end of the line, in which case the character behind the cursor is
976 deleted. By default, this is not bound to a key.
978 `quoted-insert (C-q or C-v)'
979 Add the next character typed to the line verbatim. This is how to
980 insert key sequences like `C-q', for example.
982 `tab-insert (M-<TAB>)'
983 Insert a tab character.
985 `self-insert (a, b, A, 1, !, ...)'
988 `transpose-chars (C-t)'
989 Drag the character before the cursor forward over the character at
990 the cursor, moving the cursor forward as well. If the insertion
991 point is at the end of the line, then this transposes the last two
992 characters of the line. Negative arguments have no effect.
994 `transpose-words (M-t)'
995 Drag the word before point past the word after point, moving point
996 past that word as well. If the insertion point is at the end of
997 the line, this transposes the last two words on the line.
1000 Uppercase the current (or following) word. With a negative
1001 argument, uppercase the previous word, but do not move the cursor.
1003 `downcase-word (M-l)'
1004 Lowercase the current (or following) word. With a negative
1005 argument, lowercase the previous word, but do not move the cursor.
1007 `capitalize-word (M-c)'
1008 Capitalize the current (or following) word. With a negative
1009 argument, capitalize the previous word, but do not move the cursor.
1012 Toggle overwrite mode. With an explicit positive numeric argument,
1013 switches to overwrite mode. With an explicit non-positive numeric
1014 argument, switches to insert mode. This command affects only
1015 `emacs' mode; `vi' mode does overwrite differently. Each call to
1016 `readline()' starts in insert mode.
1018 In overwrite mode, characters bound to `self-insert' replace the
1019 text at point rather than pushing the text to the right.
1020 Characters bound to `backward-delete-char' replace the character
1021 before point with a space.
1023 By default, this command is unbound.
1027 File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
1029 1.4.4 Killing And Yanking
1030 -------------------------
1033 Kill the text from point to the end of the line.
1035 `backward-kill-line (C-x Rubout)'
1036 Kill backward to the beginning of the line.
1038 `unix-line-discard (C-u)'
1039 Kill backward from the cursor to the beginning of the current line.
1041 `kill-whole-line ()'
1042 Kill all characters on the current line, no matter where point is.
1043 By default, this is unbound.
1046 Kill from point to the end of the current word, or if between
1047 words, to the end of the next word. Word boundaries are the same
1050 `backward-kill-word (M-<DEL>)'
1051 Kill the word behind point. Word boundaries are the same as
1054 `unix-word-rubout (C-w)'
1055 Kill the word behind point, using white space as a word boundary.
1056 The killed text is saved on the kill-ring.
1058 `unix-filename-rubout ()'
1059 Kill the word behind point, using white space and the slash
1060 character as the word boundaries. The killed text is saved on the
1063 `delete-horizontal-space ()'
1064 Delete all spaces and tabs around point. By default, this is
1068 Kill the text in the current region. By default, this command is
1071 `copy-region-as-kill ()'
1072 Copy the text in the region to the kill buffer, so it can be yanked
1073 right away. By default, this command is unbound.
1075 `copy-backward-word ()'
1076 Copy the word before point to the kill buffer. The word
1077 boundaries are the same as `backward-word'. By default, this
1080 `copy-forward-word ()'
1081 Copy the word following point to the kill buffer. The word
1082 boundaries are the same as `forward-word'. By default, this
1086 Yank the top of the kill ring into the buffer at point.
1089 Rotate the kill-ring, and yank the new top. You can only do this
1090 if the prior command is `yank' or `yank-pop'.
1093 File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
1095 1.4.5 Specifying Numeric Arguments
1096 ----------------------------------
1098 `digit-argument (M-0, M-1, ... M--)'
1099 Add this digit to the argument already accumulating, or start a new
1100 argument. `M--' starts a negative argument.
1102 `universal-argument ()'
1103 This is another way to specify an argument. If this command is
1104 followed by one or more digits, optionally with a leading minus
1105 sign, those digits define the argument. If the command is
1106 followed by digits, executing `universal-argument' again ends the
1107 numeric argument, but is otherwise ignored. As a special case, if
1108 this command is immediately followed by a character that is
1109 neither a digit or minus sign, the argument count for the next
1110 command is multiplied by four. The argument count is initially
1111 one, so executing this function the first time makes the argument
1112 count four, a second time makes the argument count sixteen, and so
1113 on. By default, this is not bound to a key.
1116 File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
1118 1.4.6 Letting Readline Type For You
1119 -----------------------------------
1122 Attempt to perform completion on the text before point. The
1123 actual completion performed is application-specific. The default
1124 is filename completion.
1126 `possible-completions (M-?)'
1127 List the possible completions of the text before point.
1129 `insert-completions (M-*)'
1130 Insert all completions of the text before point that would have
1131 been generated by `possible-completions'.
1134 Similar to `complete', but replaces the word to be completed with
1135 a single match from the list of possible completions. Repeated
1136 execution of `menu-complete' steps through the list of possible
1137 completions, inserting each match in turn. At the end of the list
1138 of completions, the bell is rung (subject to the setting of
1139 `bell-style') and the original text is restored. An argument of N
1140 moves N positions forward in the list of matches; a negative
1141 argument may be used to move backward through the list. This
1142 command is intended to be bound to <TAB>, but is unbound by
1145 `delete-char-or-list ()'
1146 Deletes the character under the cursor if not at the beginning or
1147 end of the line (like `delete-char'). If at the end of the line,
1148 behaves identically to `possible-completions'. This command is
1153 File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
1155 1.4.7 Keyboard Macros
1156 ---------------------
1158 `start-kbd-macro (C-x ()'
1159 Begin saving the characters typed into the current keyboard macro.
1161 `end-kbd-macro (C-x ))'
1162 Stop saving the characters typed into the current keyboard macro
1163 and save the definition.
1165 `call-last-kbd-macro (C-x e)'
1166 Re-execute the last keyboard macro defined, by making the
1167 characters in the macro appear as if typed at the keyboard.
1171 File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
1173 1.4.8 Some Miscellaneous Commands
1174 ---------------------------------
1176 `re-read-init-file (C-x C-r)'
1177 Read in the contents of the INPUTRC file, and incorporate any
1178 bindings or variable assignments found there.
1181 Abort the current editing command and ring the terminal's bell
1182 (subject to the setting of `bell-style').
1184 `do-uppercase-version (M-a, M-b, M-X, ...)'
1185 If the metafied character X is lowercase, run the command that is
1186 bound to the corresponding uppercase character.
1188 `prefix-meta (<ESC>)'
1189 Metafy the next character typed. This is for keyboards without a
1190 meta key. Typing `<ESC> f' is equivalent to typing `M-f'.
1192 `undo (C-_ or C-x C-u)'
1193 Incremental undo, separately remembered for each line.
1196 Undo all changes made to this line. This is like executing the
1197 `undo' command enough times to get back to the beginning.
1199 `tilde-expand (M-~)'
1200 Perform tilde expansion on the current word.
1203 Set the mark to the point. If a numeric argument is supplied, the
1204 mark is set to that position.
1206 `exchange-point-and-mark (C-x C-x)'
1207 Swap the point with the mark. The current cursor position is set
1208 to the saved position, and the old cursor position is saved as the
1211 `character-search (C-])'
1212 A character is read and point is moved to the next occurrence of
1213 that character. A negative count searches for previous
1216 `character-search-backward (M-C-])'
1217 A character is read and point is moved to the previous occurrence
1218 of that character. A negative count searches for subsequent
1221 `insert-comment (M-#)'
1222 Without a numeric argument, the value of the `comment-begin'
1223 variable is inserted at the beginning of the current line. If a
1224 numeric argument is supplied, this command acts as a toggle: if
1225 the characters at the beginning of the line do not match the value
1226 of `comment-begin', the value is inserted, otherwise the
1227 characters in `comment-begin' are deleted from the beginning of
1228 the line. In either case, the line is accepted as if a newline
1232 Print all of the functions and their key bindings to the Readline
1233 output stream. If a numeric argument is supplied, the output is
1234 formatted in such a way that it can be made part of an INPUTRC
1235 file. This command is unbound by default.
1238 Print all of the settable variables and their values to the
1239 Readline output stream. If a numeric argument is supplied, the
1240 output is formatted in such a way that it can be made part of an
1241 INPUTRC file. This command is unbound by default.
1244 Print all of the Readline key sequences bound to macros and the
1245 strings they output. If a numeric argument is supplied, the
1246 output is formatted in such a way that it can be made part of an
1247 INPUTRC file. This command is unbound by default.
1249 `emacs-editing-mode (C-e)'
1250 When in `vi' command mode, this causes a switch to `emacs' editing
1253 `vi-editing-mode (M-C-j)'
1254 When in `emacs' editing mode, this causes a switch to `vi' editing
1259 File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
1261 1.5 Readline vi Mode
1262 ====================
1264 While the Readline library does not have a full set of `vi' editing
1265 functions, it does contain enough to allow simple editing of the line.
1266 The Readline `vi' mode behaves as specified in the POSIX 1003.2
1269 In order to switch interactively between `emacs' and `vi' editing
1270 modes, use the command `M-C-j' (bound to emacs-editing-mode when in
1271 `vi' mode and to vi-editing-mode in `emacs' mode). The Readline
1272 default is `emacs' mode.
1274 When you enter a line in `vi' mode, you are already placed in
1275 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
1276 you into `command' mode, where you can edit the text of the line with
1277 the standard `vi' movement keys, move to previous history lines with
1278 `k' and subsequent lines with `j', and so forth.
1280 This document describes the GNU Readline Library, a utility for
1281 aiding in the consistency of user interface across discrete programs
1282 that need to provide a command line interface.
1284 Copyright (C) 1988-2005 Free Software Foundation, Inc.
1286 Permission is granted to make and distribute verbatim copies of this
1287 manual provided the copyright notice and this permission notice pare
1288 preserved on all copies.
1290 Permission is granted to copy and distribute modified versions of
1291 this manual under the conditions for verbatim copying, provided that
1292 the entire resulting derived work is distributed under the terms of a
1293 permission notice identical to this one.
1295 Permission is granted to copy and distribute translations of this
1296 manual into another language, under the above conditions for modified
1297 versions, except that this permission notice may be stated in a
1298 translation approved by the Foundation.
1301 File: readline.info, Node: Programming with GNU Readline, Next: Copying This Manual, Prev: Command Line Editing, Up: Top
1303 2 Programming with GNU Readline
1304 *******************************
1306 This chapter describes the interface between the GNU Readline Library
1307 and other programs. If you are a programmer, and you wish to include
1308 the features found in GNU Readline such as completion, line editing,
1309 and interactive history manipulation in your own programs, this section
1314 * Basic Behavior:: Using the default behavior of Readline.
1315 * Custom Functions:: Adding your own functions to Readline.
1316 * Readline Variables:: Variables accessible to custom
1318 * Readline Convenience Functions:: Functions which Readline supplies to
1319 aid in writing your own custom
1321 * Readline Signal Handling:: How Readline behaves when it receives signals.
1322 * Custom Completers:: Supplanting or supplementing Readline's
1323 completion functions.
1326 File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline
1331 Many programs provide a command line interface, such as `mail', `ftp',
1332 and `sh'. For such programs, the default behaviour of Readline is
1333 sufficient. This section describes how to use Readline in the simplest
1334 way possible, perhaps to replace calls in your code to `gets()' or
1337 The function `readline()' prints a prompt PROMPT and then reads and
1338 returns a single line of text from the user. If PROMPT is `NULL' or
1339 the empty string, no prompt is displayed. The line `readline' returns
1340 is allocated with `malloc()'; the caller should `free()' the line when
1341 it has finished with it. The declaration for `readline' in ANSI C is
1343 `char *readline (const char *PROMPT);'
1346 `char *line = readline ("Enter a line: ");'
1347 in order to read a line of text from the user. The line returned
1348 has the final newline removed, so only the text remains.
1350 If `readline' encounters an `EOF' while reading the line, and the
1351 line is empty at that point, then `(char *)NULL' is returned.
1352 Otherwise, the line is ended just as if a newline had been typed.
1354 If you want the user to be able to get at the line later, (with
1355 <C-p> for example), you must call `add_history()' to save the line away
1356 in a "history" list of such lines.
1358 `add_history (line)';
1360 For full details on the GNU History Library, see the associated manual.
1362 It is preferable to avoid saving empty lines on the history list,
1363 since users rarely have a burning need to reuse a blank line. Here is
1364 a function which usefully replaces the standard `gets()' library
1365 function, and has the advantage of no static buffer to overflow:
1367 /* A static variable for holding the line. */
1368 static char *line_read = (char *)NULL;
1370 /* Read a string, and return a pointer to it.
1371 Returns NULL on EOF. */
1375 /* If the buffer has already been allocated,
1376 return the memory to the free pool. */
1380 line_read = (char *)NULL;
1383 /* Get a line from the user. */
1384 line_read = readline ("");
1386 /* If the line has any text in it,
1387 save it on the history. */
1388 if (line_read && *line_read)
1389 add_history (line_read);
1394 This function gives the user the default behaviour of <TAB>
1395 completion: completion on file names. If you do not want Readline to
1396 complete on filenames, you can change the binding of the <TAB> key with
1399 `int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);'
1401 `rl_bind_key()' takes two arguments: KEY is the character that you
1402 want to bind, and FUNCTION is the address of the function to call when
1403 KEY is pressed. Binding <TAB> to `rl_insert()' makes <TAB> insert
1404 itself. `rl_bind_key()' returns non-zero if KEY is not a valid ASCII
1405 character code (between 0 and 255).
1407 Thus, to disable the default <TAB> behavior, the following suffices:
1408 `rl_bind_key ('\t', rl_insert);'
1410 This code should be executed once at the start of your program; you
1411 might write a function called `initialize_readline()' which performs
1412 this and other desired initializations, such as installing custom
1413 completers (*note Custom Completers::).
1416 File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline
1418 2.2 Custom Functions
1419 ====================
1421 Readline provides many functions for manipulating the text of the line,
1422 but it isn't possible to anticipate the needs of all programs. This
1423 section describes the various functions and variables defined within
1424 the Readline library which allow a user program to add customized
1425 functionality to Readline.
1427 Before declaring any functions that customize Readline's behavior, or
1428 using any functionality Readline provides in other code, an application
1429 writer should include the file `<readline/readline.h>' in any file that
1430 uses Readline's features. Since some of the definitions in
1431 `readline.h' use the `stdio' library, the file `<stdio.h>' should be
1432 included before `readline.h'.
1434 `readline.h' defines a C preprocessor variable that should be
1435 treated as an integer, `RL_READLINE_VERSION', which may be used to
1436 conditionally compile application code depending on the installed
1437 Readline version. The value is a hexadecimal encoding of the major and
1438 minor version numbers of the library, of the form 0xMMMM. MM is the
1439 two-digit major version number; MM is the two-digit minor version
1440 number. For Readline 4.2, for example, the value of
1441 `RL_READLINE_VERSION' would be `0x0402'.
1445 * Readline Typedefs:: C declarations to make code readable.
1446 * Function Writing:: Variables and calling conventions.
1449 File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions
1451 2.2.1 Readline Typedefs
1452 -----------------------
1454 For readabilty, we declare a number of new object types, all pointers
1457 The reason for declaring these new types is to make it easier to
1458 write code describing pointers to C functions with appropriately
1459 prototyped arguments and return values.
1461 For instance, say we want to declare a variable FUNC as a pointer to
1462 a function which takes two `int' arguments and returns an `int' (this
1463 is the type of all of the Readline bindable functions). Instead of the
1464 classic C declaration
1468 or the ANSI-C style declaration
1470 `int (*func)(int, int);'
1474 `rl_command_func_t *func;'
1476 The full list of function pointer types available is
1478 `typedef int rl_command_func_t (int, int);'
1480 `typedef char *rl_compentry_func_t (const char *, int);'
1482 `typedef char **rl_completion_func_t (const char *, int, int);'
1484 `typedef char *rl_quote_func_t (char *, int, char *);'
1486 `typedef char *rl_dequote_func_t (char *, int);'
1488 `typedef int rl_compignore_func_t (char **);'
1490 `typedef void rl_compdisp_func_t (char **, int, int);'
1492 `typedef int rl_hook_func_t (void);'
1494 `typedef int rl_getc_func_t (FILE *);'
1496 `typedef int rl_linebuf_func_t (char *, int);'
1498 `typedef int rl_intfunc_t (int);'
1500 `#define rl_ivoidfunc_t rl_hook_func_t'
1502 `typedef int rl_icpfunc_t (char *);'
1504 `typedef int rl_icppfunc_t (char **);'
1506 `typedef void rl_voidfunc_t (void);'
1508 `typedef void rl_vintfunc_t (int);'
1510 `typedef void rl_vcpfunc_t (char *);'
1512 `typedef void rl_vcppfunc_t (char **);'
1515 File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions
1517 2.2.2 Writing a New Function
1518 ----------------------------
1520 In order to write new functions for Readline, you need to know the
1521 calling conventions for keyboard-invoked functions, and the names of the
1522 variables that describe the current state of the line read so far.
1524 The calling sequence for a command `foo' looks like
1526 `int foo (int count, int key)'
1528 where COUNT is the numeric argument (or 1 if defaulted) and KEY is the
1529 key that invoked this function.
1531 It is completely up to the function as to what should be done with
1532 the numeric argument. Some functions use it as a repeat count, some as
1533 a flag, and others to choose alternate behavior (refreshing the current
1534 line as opposed to refreshing the screen, for example). Some choose to
1535 ignore it. In general, if a function uses the numeric argument as a
1536 repeat count, it should be able to do something useful with both
1537 negative and positive arguments. At the very least, it should be aware
1538 that it can be passed a negative argument.
1540 A command function should return 0 if its action completes
1541 successfully, and a non-zero value if some error occurs. This is the
1542 convention obeyed by all of the builtin Readline bindable command
1546 File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline
1548 2.3 Readline Variables
1549 ======================
1551 These variables are available to function writers.
1553 -- Variable: char * rl_line_buffer
1554 This is the line gathered so far. You are welcome to modify the
1555 contents of the line, but see *Note Allowing Undoing::. The
1556 function `rl_extend_line_buffer' is available to increase the
1557 memory allocated to `rl_line_buffer'.
1559 -- Variable: int rl_point
1560 The offset of the current cursor position in `rl_line_buffer' (the
1563 -- Variable: int rl_end
1564 The number of characters present in `rl_line_buffer'. When
1565 `rl_point' is at the end of the line, `rl_point' and `rl_end' are
1568 -- Variable: int rl_mark
1569 The MARK (saved position) in the current line. If set, the mark
1570 and point define a _region_.
1572 -- Variable: int rl_done
1573 Setting this to a non-zero value causes Readline to return the
1574 current line immediately.
1576 -- Variable: int rl_num_chars_to_read
1577 Setting this to a positive value before calling `readline()' causes
1578 Readline to return after accepting that many characters, rather
1579 than reading up to a character bound to `accept-line'.
1581 -- Variable: int rl_pending_input
1582 Setting this to a value makes it the next keystroke read. This is
1583 a way to stuff a single character into the input stream.
1585 -- Variable: int rl_dispatching
1586 Set to a non-zero value if a function is being called from a key
1587 binding; zero otherwise. Application functions can test this to
1588 discover whether they were called directly or by Readline's
1589 dispatching mechanism.
1591 -- Variable: int rl_erase_empty_line
1592 Setting this to a non-zero value causes Readline to completely
1593 erase the current line, including any prompt, any time a newline
1594 is typed as the only character on an otherwise-empty line. The
1595 cursor is moved to the beginning of the newly-blank line.
1597 -- Variable: char * rl_prompt
1598 The prompt Readline uses. This is set from the argument to
1599 `readline()', and should not be assigned to directly. The
1600 `rl_set_prompt()' function (*note Redisplay::) may be used to
1601 modify the prompt string after calling `readline()'.
1603 -- Variable: int rl_already_prompted
1604 If an application wishes to display the prompt itself, rather than
1605 have Readline do it the first time `readline()' is called, it
1606 should set this variable to a non-zero value after displaying the
1607 prompt. The prompt must also be passed as the argument to
1608 `readline()' so the redisplay functions can update the display
1609 properly. The calling application is responsible for managing the
1610 value; Readline never sets it.
1612 -- Variable: const char * rl_library_version
1613 The version number of this revision of the library.
1615 -- Variable: int rl_readline_version
1616 An integer encoding the current version of the library. The
1617 encoding is of the form 0xMMMM, where MM is the two-digit major
1618 version number, and MM is the two-digit minor version number. For
1619 example, for Readline-4.2, `rl_readline_version' would have the
1622 -- Variable: int rl_gnu_readline_p
1623 Always set to 1, denoting that this is GNU readline rather than
1626 -- Variable: const char * rl_terminal_name
1627 The terminal type, used for initialization. If not set by the
1628 application, Readline sets this to the value of the `TERM'
1629 environment variable the first time it is called.
1631 -- Variable: const char * rl_readline_name
1632 This variable is set to a unique name by each application using
1633 Readline. The value allows conditional parsing of the inputrc file
1634 (*note Conditional Init Constructs::).
1636 -- Variable: FILE * rl_instream
1637 The stdio stream from which Readline reads input. If `NULL',
1638 Readline defaults to STDIN.
1640 -- Variable: FILE * rl_outstream
1641 The stdio stream to which Readline performs output. If `NULL',
1642 Readline defaults to STDOUT.
1644 -- Variable: int rl_prefer_env_winsize
1645 If non-zero, Readline gives values found in the `LINES' and
1646 `COLUMNS' environment variables greater precedence than values
1647 fetched from the kernel when computing the screen dimensions.
1649 -- Variable: rl_command_func_t * rl_last_func
1650 The address of the last command function Readline executed. May
1651 be used to test whether or not a function is being executed twice
1652 in succession, for example.
1654 -- Variable: rl_hook_func_t * rl_startup_hook
1655 If non-zero, this is the address of a function to call just before
1656 `readline' prints the first prompt.
1658 -- Variable: rl_hook_func_t * rl_pre_input_hook
1659 If non-zero, this is the address of a function to call after the
1660 first prompt has been printed and just before `readline' starts
1661 reading input characters.
1663 -- Variable: rl_hook_func_t * rl_event_hook
1664 If non-zero, this is the address of a function to call periodically
1665 when Readline is waiting for terminal input. By default, this
1666 will be called at most ten times a second if there is no keyboard
1669 -- Variable: rl_getc_func_t * rl_getc_function
1670 If non-zero, Readline will call indirectly through this pointer to
1671 get a character from the input stream. By default, it is set to
1672 `rl_getc', the default Readline character input function (*note
1675 -- Variable: rl_voidfunc_t * rl_redisplay_function
1676 If non-zero, Readline will call indirectly through this pointer to
1677 update the display with the current contents of the editing buffer.
1678 By default, it is set to `rl_redisplay', the default Readline
1679 redisplay function (*note Redisplay::).
1681 -- Variable: rl_vintfunc_t * rl_prep_term_function
1682 If non-zero, Readline will call indirectly through this pointer to
1683 initialize the terminal. The function takes a single argument, an
1684 `int' flag that says whether or not to use eight-bit characters.
1685 By default, this is set to `rl_prep_terminal' (*note Terminal
1688 -- Variable: rl_voidfunc_t * rl_deprep_term_function
1689 If non-zero, Readline will call indirectly through this pointer to
1690 reset the terminal. This function should undo the effects of
1691 `rl_prep_term_function'. By default, this is set to
1692 `rl_deprep_terminal' (*note Terminal Management::).
1694 -- Variable: Keymap rl_executing_keymap
1695 This variable is set to the keymap (*note Keymaps::) in which the
1696 currently executing readline function was found.
1698 -- Variable: Keymap rl_binding_keymap
1699 This variable is set to the keymap (*note Keymaps::) in which the
1700 last key binding occurred.
1702 -- Variable: char * rl_executing_macro
1703 This variable is set to the text of any currently-executing macro.
1705 -- Variable: int rl_readline_state
1706 A variable with bit values that encapsulate the current Readline
1707 state. A bit is set with the `RL_SETSTATE' macro, and unset with
1708 the `RL_UNSETSTATE' macro. Use the `RL_ISSTATE' macro to test
1709 whether a particular state bit is set. Current state bits include:
1712 Readline has not yet been called, nor has it begun to
1715 `RL_STATE_INITIALIZING'
1716 Readline is initializing its internal data structures.
1718 `RL_STATE_INITIALIZED'
1719 Readline has completed its initialization.
1721 `RL_STATE_TERMPREPPED'
1722 Readline has modified the terminal modes to do its own input
1726 Readline is reading a command from the keyboard.
1729 Readline is reading more input after reading the meta-prefix
1732 `RL_STATE_DISPATCHING'
1733 Readline is dispatching to a command.
1735 `RL_STATE_MOREINPUT'
1736 Readline is reading more input while executing an editing
1740 Readline is performing an incremental history search.
1743 Readline is performing a non-incremental history search.
1746 Readline is searching backward or forward through the history
1749 `RL_STATE_NUMERICARG'
1750 Readline is reading a numeric argument.
1752 `RL_STATE_MACROINPUT'
1753 Readline is currently getting its input from a
1754 previously-defined keyboard macro.
1757 Readline is currently reading characters defining a keyboard
1760 `RL_STATE_OVERWRITE'
1761 Readline is in overwrite mode.
1763 `RL_STATE_COMPLETING'
1764 Readline is performing word completion.
1766 `RL_STATE_SIGHANDLER'
1767 Readline is currently executing the readline signal handler.
1770 Readline is performing an undo.
1773 Readline has read a key sequence bound to `accept-line' and
1774 is about to return the line to the caller.
1777 -- Variable: int rl_explicit_arg
1778 Set to a non-zero value if an explicit numeric argument was
1779 specified by the user. Only valid in a bindable command function.
1781 -- Variable: int rl_numeric_arg
1782 Set to the value of any numeric argument explicitly specified by
1783 the user before executing the current Readline function. Only
1784 valid in a bindable command function.
1786 -- Variable: int rl_editing_mode
1787 Set to a value denoting Readline's current editing mode. A value
1788 of 1 means Readline is currently in emacs mode; 0 means that vi
1792 File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline
1794 2.4 Readline Convenience Functions
1795 ==================================
1799 * Function Naming:: How to give a function you write a name.
1800 * Keymaps:: Making keymaps.
1801 * Binding Keys:: Changing Keymaps.
1802 * Associating Function Names and Bindings:: Translate function names to
1804 * Allowing Undoing:: How to make your functions undoable.
1805 * Redisplay:: Functions to control line display.
1806 * Modifying Text:: Functions to modify `rl_line_buffer'.
1807 * Character Input:: Functions to read keyboard input.
1808 * Terminal Management:: Functions to manage terminal settings.
1809 * Utility Functions:: Generally useful functions and hooks.
1810 * Miscellaneous Functions:: Functions that don't fall into any category.
1811 * Alternate Interface:: Using Readline in a `callback' fashion.
1812 * A Readline Example:: An example Readline function.
1815 File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions
1817 2.4.1 Naming a Function
1818 -----------------------
1820 The user can dynamically change the bindings of keys while using
1821 Readline. This is done by representing the function with a descriptive
1822 name. The user is able to type the descriptive name when referring to
1823 the function. Thus, in an init file, one might find
1825 Meta-Rubout: backward-kill-word
1827 This binds the keystroke <Meta-Rubout> to the function
1828 _descriptively_ named `backward-kill-word'. You, as the programmer,
1829 should bind the functions you write to descriptive names as well.
1830 Readline provides a function for doing that:
1832 -- Function: int rl_add_defun (const char *name, rl_command_func_t
1834 Add NAME to the list of named functions. Make FUNCTION be the
1835 function that gets called. If KEY is not -1, then bind it to
1836 FUNCTION using `rl_bind_key()'.
1838 Using this function alone is sufficient for most applications. It
1839 is the recommended way to add a few functions to the default functions
1840 that Readline has built in. If you need to do something other than
1841 adding a function to Readline, you may need to use the underlying
1842 functions described below.
1845 File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions
1847 2.4.2 Selecting a Keymap
1848 ------------------------
1850 Key bindings take place on a "keymap". The keymap is the association
1851 between the keys that the user types and the functions that get run.
1852 You can make your own keymaps, copy existing keymaps, and tell Readline
1853 which keymap to use.
1855 -- Function: Keymap rl_make_bare_keymap (void)
1856 Returns a new, empty keymap. The space for the keymap is
1857 allocated with `malloc()'; the caller should free it by calling
1858 `rl_discard_keymap()' when done.
1860 -- Function: Keymap rl_copy_keymap (Keymap map)
1861 Return a new keymap which is a copy of MAP.
1863 -- Function: Keymap rl_make_keymap (void)
1864 Return a new keymap with the printing characters bound to
1865 rl_insert, the lowercase Meta characters bound to run their
1866 equivalents, and the Meta digits bound to produce numeric
1869 -- Function: void rl_discard_keymap (Keymap keymap)
1870 Free the storage associated with KEYMAP.
1872 Readline has several internal keymaps. These functions allow you to
1873 change which keymap is active.
1875 -- Function: Keymap rl_get_keymap (void)
1876 Returns the currently active keymap.
1878 -- Function: void rl_set_keymap (Keymap keymap)
1879 Makes KEYMAP the currently active keymap.
1881 -- Function: Keymap rl_get_keymap_by_name (const char *name)
1882 Return the keymap matching NAME. NAME is one which would be
1883 supplied in a `set keymap' inputrc line (*note Readline Init
1886 -- Function: char * rl_get_keymap_name (Keymap keymap)
1887 Return the name matching KEYMAP. NAME is one which would be
1888 supplied in a `set keymap' inputrc line (*note Readline Init
1892 File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions
1897 Key sequences are associate with functions through the keymap.
1898 Readline has several internal keymaps: `emacs_standard_keymap',
1899 `emacs_meta_keymap', `emacs_ctlx_keymap', `vi_movement_keymap', and
1900 `vi_insertion_keymap'. `emacs_standard_keymap' is the default, and the
1901 examples in this manual assume that.
1903 Since `readline()' installs a set of default key bindings the first
1904 time it is called, there is always the danger that a custom binding
1905 installed before the first call to `readline()' will be overridden. An
1906 alternate mechanism is to install custom key bindings in an
1907 initialization function assigned to the `rl_startup_hook' variable
1908 (*note Readline Variables::).
1910 These functions manage key bindings.
1912 -- Function: int rl_bind_key (int key, rl_command_func_t *function)
1913 Binds KEY to FUNCTION in the currently active keymap. Returns
1914 non-zero in the case of an invalid KEY.
1916 -- Function: int rl_bind_key_in_map (int key, rl_command_func_t
1917 *function, Keymap map)
1918 Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an
1921 -- Function: int rl_bind_key_if_unbound (int key, rl_command_func_t
1923 Binds KEY to FUNCTION if it is not already bound in the currently
1924 active keymap. Returns non-zero in the case of an invalid KEY or
1925 if KEY is already bound.
1927 -- Function: int rl_bind_key_if_unbound_in_map (int key,
1928 rl_command_func_t *function, Keymap map)
1929 Binds KEY to FUNCTION if it is not already bound in MAP. Returns
1930 non-zero in the case of an invalid KEY or if KEY is already bound.
1932 -- Function: int rl_unbind_key (int key)
1933 Bind KEY to the null function in the currently active keymap.
1934 Returns non-zero in case of error.
1936 -- Function: int rl_unbind_key_in_map (int key, Keymap map)
1937 Bind KEY to the null function in MAP. Returns non-zero in case of
1940 -- Function: int rl_unbind_function_in_map (rl_command_func_t
1941 *function, Keymap map)
1942 Unbind all keys that execute FUNCTION in MAP.
1944 -- Function: int rl_unbind_command_in_map (const char *command, Keymap
1946 Unbind all keys that are bound to COMMAND in MAP.
1948 -- Function: int rl_bind_keyseq (const char *keyseq, rl_command_func_t
1950 Bind the key sequence represented by the string KEYSEQ to the
1951 function FUNCTION, beginning in the current keymap. This makes
1952 new keymaps as necessary. The return value is non-zero if KEYSEQ
1955 -- Function: int rl_bind_keyseq_in_map (const char *keyseq,
1956 rl_command_func_t *function, Keymap map)
1957 Bind the key sequence represented by the string KEYSEQ to the
1958 function FUNCTION. This makes new keymaps as necessary. Initial
1959 bindings are performed in MAP. The return value is non-zero if
1962 -- Function: int rl_set_key (const char *keyseq, rl_command_func_t
1963 *function, Keymap map)
1964 Equivalent to `rl_bind_keyseq_in_map'.
1966 -- Function: int rl_bind_keyseq_if_unbound (const char *keyseq,
1967 rl_command_func_t *function)
1968 Binds KEYSEQ to FUNCTION if it is not already bound in the
1969 currently active keymap. Returns non-zero in the case of an
1970 invalid KEYSEQ or if KEYSEQ is already bound.
1972 -- Function: int rl_bind_keyseq_if_unbound_in_map (const char *keyseq,
1973 rl_command_func_t *function, Keymap map)
1974 Binds KEYSEQ to FUNCTION if it is not already bound in MAP.
1975 Returns non-zero in the case of an invalid KEYSEQ or if KEYSEQ is
1978 -- Function: int rl_generic_bind (int type, const char *keyseq, char
1980 Bind the key sequence represented by the string KEYSEQ to the
1981 arbitrary pointer DATA. TYPE says what kind of data is pointed to
1982 by DATA; this can be a function (`ISFUNC'), a macro (`ISMACR'), or
1983 a keymap (`ISKMAP'). This makes new keymaps as necessary. The
1984 initial keymap in which to do bindings is MAP.
1986 -- Function: int rl_parse_and_bind (char *line)
1987 Parse LINE as if it had been read from the `inputrc' file and
1988 perform any key bindings and variable assignments found (*note
1989 Readline Init File::).
1991 -- Function: int rl_read_init_file (const char *filename)
1992 Read keybindings and variable assignments from FILENAME (*note
1993 Readline Init File::).
1996 File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions
1998 2.4.4 Associating Function Names and Bindings
1999 ---------------------------------------------
2001 These functions allow you to find out what keys invoke named functions
2002 and the functions invoked by a particular key sequence. You may also
2003 associate a new function name with an arbitrary function.
2005 -- Function: rl_command_func_t * rl_named_function (const char *name)
2006 Return the function with name NAME.
2008 -- Function: rl_command_func_t * rl_function_of_keyseq (const char
2009 *keyseq, Keymap map, int *type)
2010 Return the function invoked by KEYSEQ in keymap MAP. If MAP is
2011 `NULL', the current keymap is used. If TYPE is not `NULL', the
2012 type of the object is returned in the `int' variable it points to
2013 (one of `ISFUNC', `ISKMAP', or `ISMACR').
2015 -- Function: char ** rl_invoking_keyseqs (rl_command_func_t *function)
2016 Return an array of strings representing the key sequences used to
2017 invoke FUNCTION in the current keymap.
2019 -- Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t
2020 *function, Keymap map)
2021 Return an array of strings representing the key sequences used to
2022 invoke FUNCTION in the keymap MAP.
2024 -- Function: void rl_function_dumper (int readable)
2025 Print the readline function names and the key sequences currently
2026 bound to them to `rl_outstream'. If READABLE is non-zero, the
2027 list is formatted in such a way that it can be made part of an
2028 `inputrc' file and re-read.
2030 -- Function: void rl_list_funmap_names (void)
2031 Print the names of all bindable Readline functions to
2034 -- Function: const char ** rl_funmap_names (void)
2035 Return a NULL terminated array of known function names. The array
2036 is sorted. The array itself is allocated, but not the strings
2037 inside. You should `free()' the array when you are done, but not
2040 -- Function: int rl_add_funmap_entry (const char *name,
2041 rl_command_func_t *function)
2042 Add NAME to the list of bindable Readline command names, and make
2043 FUNCTION the function to be called when NAME is invoked.
2046 File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions
2048 2.4.5 Allowing Undoing
2049 ----------------------
2051 Supporting the undo command is a painless thing, and makes your
2052 functions much more useful. It is certainly easy to try something if
2053 you know you can undo it.
2055 If your function simply inserts text once, or deletes text once, and
2056 uses `rl_insert_text()' or `rl_delete_text()' to do it, then undoing is
2057 already done for you automatically.
2059 If you do multiple insertions or multiple deletions, or any
2060 combination of these operations, you should group them together into
2061 one operation. This is done with `rl_begin_undo_group()' and
2062 `rl_end_undo_group()'.
2064 The types of events that can be undone are:
2066 enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
2068 Notice that `UNDO_DELETE' means to insert some text, and
2069 `UNDO_INSERT' means to delete some text. That is, the undo code tells
2070 what to undo, not how to undo it. `UNDO_BEGIN' and `UNDO_END' are tags
2071 added by `rl_begin_undo_group()' and `rl_end_undo_group()'.
2073 -- Function: int rl_begin_undo_group (void)
2074 Begins saving undo information in a group construct. The undo
2075 information usually comes from calls to `rl_insert_text()' and
2076 `rl_delete_text()', but could be the result of calls to
2079 -- Function: int rl_end_undo_group (void)
2080 Closes the current undo group started with `rl_begin_undo_group
2081 ()'. There should be one call to `rl_end_undo_group()' for each
2082 call to `rl_begin_undo_group()'.
2084 -- Function: void rl_add_undo (enum undo_code what, int start, int
2086 Remember how to undo an event (according to WHAT). The affected
2087 text runs from START to END, and encompasses TEXT.
2089 -- Function: void rl_free_undo_list (void)
2090 Free the existing undo list.
2092 -- Function: int rl_do_undo (void)
2093 Undo the first thing on the undo list. Returns `0' if there was
2094 nothing to undo, non-zero if something was undone.
2096 Finally, if you neither insert nor delete text, but directly modify
2097 the existing text (e.g., change its case), call `rl_modifying()' once,
2098 just before you modify the text. You must supply the indices of the
2099 text range that you are going to modify.
2101 -- Function: int rl_modifying (int start, int end)
2102 Tell Readline to save the text between START and END as a single
2103 undo unit. It is assumed that you will subsequently modify that
2107 File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions
2112 -- Function: void rl_redisplay (void)
2113 Change what's displayed on the screen to reflect the current
2114 contents of `rl_line_buffer'.
2116 -- Function: int rl_forced_update_display (void)
2117 Force the line to be updated and redisplayed, whether or not
2118 Readline thinks the screen display is correct.
2120 -- Function: int rl_on_new_line (void)
2121 Tell the update functions that we have moved onto a new (empty)
2122 line, usually after ouputting a newline.
2124 -- Function: int rl_on_new_line_with_prompt (void)
2125 Tell the update functions that we have moved onto a new line, with
2126 RL_PROMPT already displayed. This could be used by applications
2127 that want to output the prompt string themselves, but still need
2128 Readline to know the prompt string length for redisplay. It
2129 should be used after setting RL_ALREADY_PROMPTED.
2131 -- Function: int rl_reset_line_state (void)
2132 Reset the display state to a clean state and redisplay the current
2133 line starting on a new line.
2135 -- Function: int rl_crlf (void)
2136 Move the cursor to the start of the next screen line.
2138 -- Function: int rl_show_char (int c)
2139 Display character C on `rl_outstream'. If Readline has not been
2140 set to display meta characters directly, this will convert meta
2141 characters to a meta-prefixed key sequence. This is intended for
2142 use by applications which wish to do their own redisplay.
2144 -- Function: int rl_message (const char *, ...)
2145 The arguments are a format string as would be supplied to `printf',
2146 possibly containing conversion specifications such as `%d', and
2147 any additional arguments necessary to satisfy the conversion
2148 specifications. The resulting string is displayed in the "echo
2149 area". The echo area is also used to display numeric arguments
2150 and search strings. You should call `rl_save_prompt' to save the
2151 prompt information before calling this function.
2153 -- Function: int rl_clear_message (void)
2154 Clear the message in the echo area. If the prompt was saved with
2155 a call to `rl_save_prompt' before the last call to `rl_message',
2156 call `rl_restore_prompt' before calling this function.
2158 -- Function: void rl_save_prompt (void)
2159 Save the local Readline prompt display state in preparation for
2160 displaying a new message in the message area with `rl_message()'.
2162 -- Function: void rl_restore_prompt (void)
2163 Restore the local Readline prompt display state saved by the most
2164 recent call to `rl_save_prompt'. if `rl_save_prompt' was called
2165 to save the prompt before a call to `rl_message', this function
2166 should be called before the corresponding call to
2169 -- Function: int rl_expand_prompt (char *prompt)
2170 Expand any special character sequences in PROMPT and set up the
2171 local Readline prompt redisplay variables. This function is
2172 called by `readline()'. It may also be called to expand the
2173 primary prompt if the `rl_on_new_line_with_prompt()' function or
2174 `rl_already_prompted' variable is used. It returns the number of
2175 visible characters on the last line of the (possibly multi-line)
2176 prompt. Applications may indicate that the prompt contains
2177 characters that take up no physical screen space when displayed by
2178 bracketing a sequence of such characters with the special markers
2179 `RL_PROMPT_START_IGNORE' and `RL_PROMPT_END_IGNORE' (declared in
2180 `readline.h'. This may be used to embed terminal-specific escape
2181 sequences in prompts.
2183 -- Function: int rl_set_prompt (const char *prompt)
2184 Make Readline use PROMPT for subsequent redisplay. This calls
2185 `rl_expand_prompt()' to expand the prompt and sets `rl_prompt' to
2189 File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions
2191 2.4.7 Modifying Text
2192 --------------------
2194 -- Function: int rl_insert_text (const char *text)
2195 Insert TEXT into the line at the current cursor position. Returns
2196 the number of characters inserted.
2198 -- Function: int rl_delete_text (int start, int end)
2199 Delete the text between START and END in the current line.
2200 Returns the number of characters deleted.
2202 -- Function: char * rl_copy_text (int start, int end)
2203 Return a copy of the text between START and END in the current
2206 -- Function: int rl_kill_text (int start, int end)
2207 Copy the text between START and END in the current line to the
2208 kill ring, appending or prepending to the last kill if the last
2209 command was a kill command. The text is deleted. If START is
2210 less than END, the text is appended, otherwise prepended. If the
2211 last command was not a kill, a new kill ring slot is used.
2213 -- Function: int rl_push_macro_input (char *macro)
2214 Cause MACRO to be inserted into the line, as if it had been invoked
2215 by a key bound to a macro. Not especially useful; use
2216 `rl_insert_text()' instead.
2219 File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions
2221 2.4.8 Character Input
2222 ---------------------
2224 -- Function: int rl_read_key (void)
2225 Return the next character available from Readline's current input
2226 stream. This handles input inserted into the input stream via
2227 RL_PENDING_INPUT (*note Readline Variables::) and
2228 `rl_stuff_char()', macros, and characters read from the keyboard.
2229 While waiting for input, this function will call any function
2230 assigned to the `rl_event_hook' variable.
2232 -- Function: int rl_getc (FILE *stream)
2233 Return the next character available from STREAM, which is assumed
2236 -- Function: int rl_stuff_char (int c)
2237 Insert C into the Readline input stream. It will be "read" before
2238 Readline attempts to read characters from the terminal with
2239 `rl_read_key()'. Up to 512 characters may be pushed back.
2240 `rl_stuff_char' returns 1 if the character was successfully
2241 inserted; 0 otherwise.
2243 -- Function: int rl_execute_next (int c)
2244 Make C be the next command to be executed when `rl_read_key()' is
2245 called. This sets RL_PENDING_INPUT.
2247 -- Function: int rl_clear_pending_input (void)
2248 Unset RL_PENDING_INPUT, effectively negating the effect of any
2249 previous call to `rl_execute_next()'. This works only if the
2250 pending input has not already been read with `rl_read_key()'.
2252 -- Function: int rl_set_keyboard_input_timeout (int u)
2253 While waiting for keyboard input in `rl_read_key()', Readline will
2254 wait for U microseconds for input before calling any function
2255 assigned to `rl_event_hook'. U must be greater than or equal to
2256 zero (a zero-length timeout is equivalent to a poll). The default
2257 waiting period is one-tenth of a second. Returns the old timeout
2261 File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions
2263 2.4.9 Terminal Management
2264 -------------------------
2266 -- Function: void rl_prep_terminal (int meta_flag)
2267 Modify the terminal settings for Readline's use, so `readline()'
2268 can read a single character at a time from the keyboard. The
2269 META_FLAG argument should be non-zero if Readline should read
2272 -- Function: void rl_deprep_terminal (void)
2273 Undo the effects of `rl_prep_terminal()', leaving the terminal in
2274 the state in which it was before the most recent call to
2275 `rl_prep_terminal()'.
2277 -- Function: void rl_tty_set_default_bindings (Keymap kmap)
2278 Read the operating system's terminal editing characters (as would
2279 be displayed by `stty') to their Readline equivalents. The
2280 bindings are performed in KMAP.
2282 -- Function: void rl_tty_unset_default_bindings (Keymap kmap)
2283 Reset the bindings manipulated by `rl_tty_set_default_bindings' so
2284 that the terminal editing characters are bound to `rl_insert'.
2285 The bindings are performed in KMAP.
2287 -- Function: int rl_reset_terminal (const char *terminal_name)
2288 Reinitialize Readline's idea of the terminal settings using
2289 TERMINAL_NAME as the terminal type (e.g., `vt100'). If
2290 TERMINAL_NAME is `NULL', the value of the `TERM' environment
2294 File: readline.info, Node: Utility Functions, Next: Miscellaneous Functions, Prev: Terminal Management, Up: Readline Convenience Functions
2296 2.4.10 Utility Functions
2297 ------------------------
2299 -- Function: void rl_replace_line (const char *text, int clear_undo)
2300 Replace the contents of `rl_line_buffer' with TEXT. The point and
2301 mark are preserved, if possible. If CLEAR_UNDO is non-zero, the
2302 undo list associated with the current line is cleared.
2304 -- Function: int rl_extend_line_buffer (int len)
2305 Ensure that `rl_line_buffer' has enough space to hold LEN
2306 characters, possibly reallocating it if necessary.
2308 -- Function: int rl_initialize (void)
2309 Initialize or re-initialize Readline's internal state. It's not
2310 strictly necessary to call this; `readline()' calls it before
2313 -- Function: int rl_ding (void)
2314 Ring the terminal bell, obeying the setting of `bell-style'.
2316 -- Function: int rl_alphabetic (int c)
2317 Return 1 if C is an alphabetic character.
2319 -- Function: void rl_display_match_list (char **matches, int len, int
2321 A convenience function for displaying a list of strings in
2322 columnar format on Readline's output stream. `matches' is the list
2323 of strings, in argv format, such as a list of completion matches.
2324 `len' is the number of strings in `matches', and `max' is the
2325 length of the longest string in `matches'. This function uses the
2326 setting of `print-completions-horizontally' to select how the
2327 matches are displayed (*note Readline Init File Syntax::).
2329 The following are implemented as macros, defined in `chardefs.h'.
2330 Applications should refrain from using them.
2332 -- Function: int _rl_uppercase_p (int c)
2333 Return 1 if C is an uppercase alphabetic character.
2335 -- Function: int _rl_lowercase_p (int c)
2336 Return 1 if C is a lowercase alphabetic character.
2338 -- Function: int _rl_digit_p (int c)
2339 Return 1 if C is a numeric character.
2341 -- Function: int _rl_to_upper (int c)
2342 If C is a lowercase alphabetic character, return the corresponding
2343 uppercase character.
2345 -- Function: int _rl_to_lower (int c)
2346 If C is an uppercase alphabetic character, return the corresponding
2347 lowercase character.
2349 -- Function: int _rl_digit_value (int c)
2350 If C is a number, return the value it represents.
2353 File: readline.info, Node: Miscellaneous Functions, Next: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions
2355 2.4.11 Miscellaneous Functions
2356 ------------------------------
2358 -- Function: int rl_macro_bind (const char *keyseq, const char *macro,
2360 Bind the key sequence KEYSEQ to invoke the macro MACRO. The
2361 binding is performed in MAP. When KEYSEQ is invoked, the MACRO
2362 will be inserted into the line. This function is deprecated; use
2363 `rl_generic_bind()' instead.
2365 -- Function: void rl_macro_dumper (int readable)
2366 Print the key sequences bound to macros and their values, using
2367 the current keymap, to `rl_outstream'. If READABLE is non-zero,
2368 the list is formatted in such a way that it can be made part of an
2369 `inputrc' file and re-read.
2371 -- Function: int rl_variable_bind (const char *variable, const char
2373 Make the Readline variable VARIABLE have VALUE. This behaves as
2374 if the readline command `set VARIABLE VALUE' had been executed in
2375 an `inputrc' file (*note Readline Init File Syntax::).
2377 -- Function: char * rl_variable_value (const char *variable)
2378 Return a string representing the value of the Readline variable
2379 VARIABLE. For boolean variables, this string is either `on' or
2382 -- Function: void rl_variable_dumper (int readable)
2383 Print the readline variable names and their current values to
2384 `rl_outstream'. If READABLE is non-zero, the list is formatted in
2385 such a way that it can be made part of an `inputrc' file and
2388 -- Function: int rl_set_paren_blink_timeout (int u)
2389 Set the time interval (in microseconds) that Readline waits when
2390 showing a balancing character when `blink-matching-paren' has been
2393 -- Function: char * rl_get_termcap (const char *cap)
2394 Retrieve the string value of the termcap capability CAP. Readline
2395 fetches the termcap entry for the current terminal name and uses
2396 those capabilities to move around the screen line and perform other
2397 terminal-specific operations, like erasing a line. Readline does
2398 not use all of a terminal's capabilities, and this function will
2399 return values for only those capabilities Readline uses.
2402 File: readline.info, Node: Alternate Interface, Next: A Readline Example, Prev: Miscellaneous Functions, Up: Readline Convenience Functions
2404 2.4.12 Alternate Interface
2405 --------------------------
2407 An alternate interface is available to plain `readline()'. Some
2408 applications need to interleave keyboard I/O with file, device, or
2409 window system I/O, typically by using a main loop to `select()' on
2410 various file descriptors. To accomodate this need, readline can also
2411 be invoked as a `callback' function from an event loop. There are
2412 functions available to make this easy.
2414 -- Function: void rl_callback_handler_install (const char *prompt,
2415 rl_vcpfunc_t *lhandler)
2416 Set up the terminal for readline I/O and display the initial
2417 expanded value of PROMPT. Save the value of LHANDLER to use as a
2418 function to call when a complete line of input has been entered.
2419 The function takes the text of the line as an argument.
2421 -- Function: void rl_callback_read_char (void)
2422 Whenever an application determines that keyboard input is
2423 available, it should call `rl_callback_read_char()', which will
2424 read the next character from the current input source. If that
2425 character completes the line, `rl_callback_read_char' will invoke
2426 the LHANDLER function saved by `rl_callback_handler_install' to
2427 process the line. Before calling the LHANDLER function, the
2428 terminal settings are reset to the values they had before calling
2429 `rl_callback_handler_install'. If the LHANDLER function returns,
2430 the terminal settings are modified for Readline's use again.
2431 `EOF' is indicated by calling LHANDLER with a `NULL' line.
2433 -- Function: void rl_callback_handler_remove (void)
2434 Restore the terminal to its initial state and remove the line
2435 handler. This may be called from within a callback as well as
2436 independently. If the LHANDLER installed by
2437 `rl_callback_handler_install' does not exit the program, either
2438 this function or the function referred to by the value of
2439 `rl_deprep_term_function' should be called before the program
2440 exits to reset the terminal settings.
2443 File: readline.info, Node: A Readline Example, Prev: Alternate Interface, Up: Readline Convenience Functions
2445 2.4.13 A Readline Example
2446 -------------------------
2448 Here is a function which changes lowercase characters to their uppercase
2449 equivalents, and uppercase characters to lowercase. If this function
2450 was bound to `M-c', then typing `M-c' would change the case of the
2451 character under point. Typing `M-1 0 M-c' would change the case of the
2452 following 10 characters, leaving the cursor on the last character
2455 /* Invert the case of the COUNT following characters. */
2457 invert_case_line (count, key)
2460 register int start, end, i;
2464 if (rl_point >= rl_end)
2475 /* Find the end of the range to modify. */
2476 end = start + (count * direction);
2478 /* Force it to be within range. */
2494 /* Tell readline that we are modifying the line,
2495 so it will save the undo information. */
2496 rl_modifying (start, end);
2498 for (i = start; i != end; i++)
2500 if (_rl_uppercase_p (rl_line_buffer[i]))
2501 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
2502 else if (_rl_lowercase_p (rl_line_buffer[i]))
2503 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
2505 /* Move point to on top of the last character changed. */
2506 rl_point = (direction == 1) ? end - 1 : start;
2511 File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline
2513 2.5 Readline Signal Handling
2514 ============================
2516 Signals are asynchronous events sent to a process by the Unix kernel,
2517 sometimes on behalf of another process. They are intended to indicate
2518 exceptional events, like a user pressing the interrupt key on his
2519 terminal, or a network connection being broken. There is a class of
2520 signals that can be sent to the process currently reading input from
2521 the keyboard. Since Readline changes the terminal attributes when it
2522 is called, it needs to perform special processing when such a signal is
2523 received in order to restore the terminal to a sane state, or provide
2524 application writers with functions to do so manually.
2526 Readline contains an internal signal handler that is installed for a
2527 number of signals (`SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM',
2528 `SIGTSTP', `SIGTTIN', and `SIGTTOU'). When one of these signals is
2529 received, the signal handler will reset the terminal attributes to
2530 those that were in effect before `readline()' was called, reset the
2531 signal handling to what it was before `readline()' was called, and
2532 resend the signal to the calling application. If and when the calling
2533 application's signal handler returns, Readline will reinitialize the
2534 terminal and continue to accept input. When a `SIGINT' is received,
2535 the Readline signal handler performs some additional work, which will
2536 cause any partially-entered line to be aborted (see the description of
2537 `rl_free_line_state()' below).
2539 There is an additional Readline signal handler, for `SIGWINCH', which
2540 the kernel sends to a process whenever the terminal's size changes (for
2541 example, if a user resizes an `xterm'). The Readline `SIGWINCH'
2542 handler updates Readline's internal screen size information, and then
2543 calls any `SIGWINCH' signal handler the calling application has
2544 installed. Readline calls the application's `SIGWINCH' signal handler
2545 without resetting the terminal to its original state. If the
2546 application's signal handler does more than update its idea of the
2547 terminal size and return (for example, a `longjmp' back to a main
2548 processing loop), it _must_ call `rl_cleanup_after_signal()' (described
2549 below), to restore the terminal state.
2551 Readline provides two variables that allow application writers to
2552 control whether or not it will catch certain signals and act on them
2553 when they are received. It is important that applications change the
2554 values of these variables only when calling `readline()', not in a
2555 signal handler, so Readline's internal signal state is not corrupted.
2557 -- Variable: int rl_catch_signals
2558 If this variable is non-zero, Readline will install signal
2559 handlers for `SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM', `SIGTSTP',
2560 `SIGTTIN', and `SIGTTOU'.
2562 The default value of `rl_catch_signals' is 1.
2564 -- Variable: int rl_catch_sigwinch
2565 If this variable is non-zero, Readline will install a signal
2566 handler for `SIGWINCH'.
2568 The default value of `rl_catch_sigwinch' is 1.
2570 If an application does not wish to have Readline catch any signals,
2571 or to handle signals other than those Readline catches (`SIGHUP', for
2572 example), Readline provides convenience functions to do the necessary
2573 terminal and internal state cleanup upon receipt of a signal.
2575 -- Function: void rl_cleanup_after_signal (void)
2576 This function will reset the state of the terminal to what it was
2577 before `readline()' was called, and remove the Readline signal
2578 handlers for all signals, depending on the values of
2579 `rl_catch_signals' and `rl_catch_sigwinch'.
2581 -- Function: void rl_free_line_state (void)
2582 This will free any partial state associated with the current input
2583 line (undo information, any partial history entry, any
2584 partially-entered keyboard macro, and any partially-entered
2585 numeric argument). This should be called before
2586 `rl_cleanup_after_signal()'. The Readline signal handler for
2587 `SIGINT' calls this to abort the current input line.
2589 -- Function: void rl_reset_after_signal (void)
2590 This will reinitialize the terminal and reinstall any Readline
2591 signal handlers, depending on the values of `rl_catch_signals' and
2592 `rl_catch_sigwinch'.
2594 If an application does not wish Readline to catch `SIGWINCH', it may
2595 call `rl_resize_terminal()' or `rl_set_screen_size()' to force Readline
2596 to update its idea of the terminal size when a `SIGWINCH' is received.
2598 -- Function: void rl_resize_terminal (void)
2599 Update Readline's internal screen size by reading values from the
2602 -- Function: void rl_set_screen_size (int rows, int cols)
2603 Set Readline's idea of the terminal size to ROWS rows and COLS
2604 columns. If either ROWS or COLUMNS is less than or equal to 0,
2605 Readline's idea of that terminal dimension is unchanged.
2607 If an application does not want to install a `SIGWINCH' handler, but
2608 is still interested in the screen dimensions, Readline's idea of the
2609 screen size may be queried.
2611 -- Function: void rl_get_screen_size (int *rows, int *cols)
2612 Return Readline's idea of the terminal's size in the variables
2613 pointed to by the arguments.
2615 -- Function: void rl_reset_screen_size (void)
2616 Cause Readline to reobtain the screen size and recalculate its
2619 The following functions install and remove Readline's signal
2622 -- Function: int rl_set_signals (void)
2623 Install Readline's signal handler for `SIGINT', `SIGQUIT',
2624 `SIGTERM', `SIGALRM', `SIGTSTP', `SIGTTIN', `SIGTTOU', and
2625 `SIGWINCH', depending on the values of `rl_catch_signals' and
2626 `rl_catch_sigwinch'.
2628 -- Function: int rl_clear_signals (void)
2629 Remove all of the Readline signal handlers installed by
2633 File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline
2635 2.6 Custom Completers
2636 =====================
2638 Typically, a program that reads commands from the user has a way of
2639 disambiguating commands and data. If your program is one of these, then
2640 it can provide completion for commands, data, or both. The following
2641 sections describe how your program and Readline cooperate to provide
2646 * How Completing Works:: The logic used to do completion.
2647 * Completion Functions:: Functions provided by Readline.
2648 * Completion Variables:: Variables which control completion.
2649 * A Short Completion Example:: An example of writing completer subroutines.
2652 File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers
2654 2.6.1 How Completing Works
2655 --------------------------
2657 In order to complete some text, the full list of possible completions
2658 must be available. That is, it is not possible to accurately expand a
2659 partial word without knowing all of the possible words which make sense
2660 in that context. The Readline library provides the user interface to
2661 completion, and two of the most common completion functions: filename
2662 and username. For completing other types of text, you must write your
2663 own completion function. This section describes exactly what such
2664 functions must do, and provides an example.
2666 There are three major functions used to perform completion:
2668 1. The user-interface function `rl_complete()'. This function is
2669 called with the same arguments as other bindable Readline
2670 functions: COUNT and INVOKING_KEY. It isolates the word to be
2671 completed and calls `rl_completion_matches()' to generate a list
2672 of possible completions. It then either lists the possible
2673 completions, inserts the possible completions, or actually
2674 performs the completion, depending on which behavior is desired.
2676 2. The internal function `rl_completion_matches()' uses an
2677 application-supplied "generator" function to generate the list of
2678 possible matches, and then returns the array of these matches.
2679 The caller should place the address of its generator function in
2680 `rl_completion_entry_function'.
2682 3. The generator function is called repeatedly from
2683 `rl_completion_matches()', returning a string each time. The
2684 arguments to the generator function are TEXT and STATE. TEXT is
2685 the partial word to be completed. STATE is zero the first time
2686 the function is called, allowing the generator to perform any
2687 necessary initialization, and a positive non-zero integer for each
2688 subsequent call. The generator function returns `(char *)NULL' to
2689 inform `rl_completion_matches()' that there are no more
2690 possibilities left. Usually the generator function computes the
2691 list of possible completions when STATE is zero, and returns them
2692 one at a time on subsequent calls. Each string the generator
2693 function returns as a match must be allocated with `malloc()';
2694 Readline frees the strings when it has finished with them. Such a
2695 generator function is referred to as an "application-specific
2696 completion function".
2699 -- Function: int rl_complete (int ignore, int invoking_key)
2700 Complete the word at or before point. You have supplied the
2701 function that does the initial simple matching selection algorithm
2702 (see `rl_completion_matches()'). The default is to do filename
2705 -- Variable: rl_compentry_func_t * rl_completion_entry_function
2706 This is a pointer to the generator function for
2707 `rl_completion_matches()'. If the value of
2708 `rl_completion_entry_function' is `NULL' then the default filename
2709 generator function, `rl_filename_completion_function()', is used.
2710 An "application-specific completion function" is a function whose
2711 address is assigned to `rl_completion_entry_function' and whose
2712 return values are used to generate possible completions.
2715 File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers
2717 2.6.2 Completion Functions
2718 --------------------------
2720 Here is the complete list of callable completion functions present in
2723 -- Function: int rl_complete_internal (int what_to_do)
2724 Complete the word at or before point. WHAT_TO_DO says what to do
2725 with the completion. A value of `?' means list the possible
2726 completions. `TAB' means do standard completion. `*' means
2727 insert all of the possible completions. `!' means to display all
2728 of the possible completions, if there is more than one, as well as
2729 performing partial completion. `@' is similar to `!', but
2730 possible completions are not listed if the possible completions
2731 share a common prefix.
2733 -- Function: int rl_complete (int ignore, int invoking_key)
2734 Complete the word at or before point. You have supplied the
2735 function that does the initial simple matching selection algorithm
2736 (see `rl_completion_matches()' and `rl_completion_entry_function').
2737 The default is to do filename completion. This calls
2738 `rl_complete_internal()' with an argument depending on
2741 -- Function: int rl_possible_completions (int count, int invoking_key)
2742 List the possible completions. See description of `rl_complete
2743 ()'. This calls `rl_complete_internal()' with an argument of `?'.
2745 -- Function: int rl_insert_completions (int count, int invoking_key)
2746 Insert the list of possible completions into the line, deleting the
2747 partially-completed word. See description of `rl_complete()'.
2748 This calls `rl_complete_internal()' with an argument of `*'.
2750 -- Function: int rl_completion_mode (rl_command_func_t *cfunc)
2751 Returns the apppriate value to pass to `rl_complete_internal()'
2752 depending on whether CFUNC was called twice in succession and the
2753 values of the `show-all-if-ambiguous' and `show-all-if-unmodified'
2754 variables. Application-specific completion functions may use this
2755 function to present the same interface as `rl_complete()'.
2757 -- Function: char ** rl_completion_matches (const char *text,
2758 rl_compentry_func_t *entry_func)
2759 Returns an array of strings which is a list of completions for
2760 TEXT. If there are no completions, returns `NULL'. The first
2761 entry in the returned array is the substitution for TEXT. The
2762 remaining entries are the possible completions. The array is
2763 terminated with a `NULL' pointer.
2765 ENTRY_FUNC is a function of two args, and returns a `char *'. The
2766 first argument is TEXT. The second is a state argument; it is
2767 zero on the first call, and non-zero on subsequent calls.
2768 ENTRY_FUNC returns a `NULL' pointer to the caller when there are
2771 -- Function: char * rl_filename_completion_function (const char *text,
2773 A generator function for filename completion in the general case.
2774 TEXT is a partial filename. The Bash source is a useful reference
2775 for writing application-specific completion functions (the Bash
2776 completion functions call this and other Readline functions).
2778 -- Function: char * rl_username_completion_function (const char *text,
2780 A completion generator for usernames. TEXT contains a partial
2781 username preceded by a random character (usually `~'). As with all
2782 completion generators, STATE is zero on the first call and non-zero
2783 for subsequent calls.
2786 File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers
2788 2.6.3 Completion Variables
2789 --------------------------
2791 -- Variable: rl_compentry_func_t * rl_completion_entry_function
2792 A pointer to the generator function for `rl_completion_matches()'.
2793 `NULL' means to use `rl_filename_completion_function()', the
2794 default filename completer.
2796 -- Variable: rl_completion_func_t * rl_attempted_completion_function
2797 A pointer to an alternative function to create matches. The
2798 function is called with TEXT, START, and END. START and END are
2799 indices in `rl_line_buffer' defining the boundaries of TEXT, which
2800 is a character string. If this function exists and returns
2801 `NULL', or if this variable is set to `NULL', then `rl_complete()'
2802 will call the value of `rl_completion_entry_function' to generate
2803 matches, otherwise the array of strings returned will be used. If
2804 this function sets the `rl_attempted_completion_over' variable to
2805 a non-zero value, Readline will not perform its default completion
2806 even if this function returns no matches.
2808 -- Variable: rl_quote_func_t * rl_filename_quoting_function
2809 A pointer to a function that will quote a filename in an
2810 application-specific fashion. This is called if filename
2811 completion is being attempted and one of the characters in
2812 `rl_filename_quote_characters' appears in a completed filename.
2813 The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER.
2814 The TEXT is the filename to be quoted. The MATCH_TYPE is either
2815 `SINGLE_MATCH', if there is only one completion match, or
2816 `MULT_MATCH'. Some functions use this to decide whether or not to
2817 insert a closing quote character. The QUOTE_POINTER is a pointer
2818 to any opening quote character the user typed. Some functions
2819 choose to reset this character.
2821 -- Variable: rl_dequote_func_t * rl_filename_dequoting_function
2822 A pointer to a function that will remove application-specific
2823 quoting characters from a filename before completion is attempted,
2824 so those characters do not interfere with matching the text
2825 against names in the filesystem. It is called with TEXT, the text
2826 of the word to be dequoted, and QUOTE_CHAR, which is the quoting
2827 character that delimits the filename (usually `'' or `"'). If
2828 QUOTE_CHAR is zero, the filename was not in an embedded string.
2830 -- Variable: rl_linebuf_func_t * rl_char_is_quoted_p
2831 A pointer to a function to call that determines whether or not a
2832 specific character in the line buffer is quoted, according to
2833 whatever quoting mechanism the program calling Readline uses. The
2834 function is called with two arguments: TEXT, the text of the line,
2835 and INDEX, the index of the character in the line. It is used to
2836 decide whether a character found in
2837 `rl_completer_word_break_characters' should be used to break words
2840 -- Variable: rl_compignore_func_t * rl_ignore_some_completions_function
2841 This function, if defined, is called by the completer when real
2842 filename completion is done, after all the matching names have
2843 been generated. It is passed a `NULL' terminated array of matches.
2844 The first element (`matches[0]') is the maximal substring common
2845 to all matches. This function can re-arrange the list of matches
2846 as required, but each element deleted from the array must be freed.
2848 -- Variable: rl_icppfunc_t * rl_directory_completion_hook
2849 This function, if defined, is allowed to modify the directory
2850 portion of filenames Readline completes. It is called with the
2851 address of a string (the current directory name) as an argument,
2852 and may modify that string. If the string is replaced with a new
2853 string, the old value should be freed. Any modified directory
2854 name should have a trailing slash. The modified value will be
2855 displayed as part of the completion, replacing the directory
2856 portion of the pathname the user typed. It returns an integer
2857 that should be non-zero if the function modifies its directory
2858 argument. It could be used to expand symbolic links or shell
2859 variables in pathnames. At the least, even if no other expansion
2860 is performed, this function should remove any quote characters
2861 from the directory name, because its result will be passed
2862 directly to `opendir()'.
2864 -- Variable: rl_compdisp_func_t * rl_completion_display_matches_hook
2865 If non-zero, then this is the address of a function to call when
2866 completing a word would normally display the list of possible
2867 matches. This function is called in lieu of Readline displaying
2868 the list. It takes three arguments: (`char **'MATCHES, `int'
2869 NUM_MATCHES, `int' MAX_LENGTH) where MATCHES is the array of
2870 matching strings, NUM_MATCHES is the number of strings in that
2871 array, and MAX_LENGTH is the length of the longest string in that
2872 array. Readline provides a convenience function,
2873 `rl_display_match_list', that takes care of doing the display to
2874 Readline's output stream. That function may be called from this
2877 -- Variable: const char * rl_basic_word_break_characters
2878 The basic list of characters that signal a break between words for
2879 the completer routine. The default value of this variable is the
2880 characters which break words for completion in Bash: `"
2881 \t\n\"\\'`@$><=;|&{("'.
2883 -- Variable: const char * rl_basic_quote_characters
2884 A list of quote characters which can cause a word break.
2886 -- Variable: const char * rl_completer_word_break_characters
2887 The list of characters that signal a break between words for
2888 `rl_complete_internal()'. The default list is the value of
2889 `rl_basic_word_break_characters'.
2891 -- Variable: rl_cpvfunc_t * rl_completion_word_break_hook
2892 If non-zero, this is the address of a function to call when
2893 Readline is deciding where to separate words for word completion.
2894 It should return a character string like
2895 `rl_completer_word_break_characters' to be used to perform the
2896 current completion. The function may choose to set
2897 `rl_completer_word_break_characters' itself. If the function
2898 returns `NULL', `rl_completer_word_break_characters' is used.
2900 -- Variable: const char * rl_completer_quote_characters
2901 A list of characters which can be used to quote a substring of the
2902 line. Completion occurs on the entire substring, and within the
2903 substring `rl_completer_word_break_characters' are treated as any
2904 other character, unless they also appear within this list.
2906 -- Variable: const char * rl_filename_quote_characters
2907 A list of characters that cause a filename to be quoted by the
2908 completer when they appear in a completed filename. The default
2911 -- Variable: const char * rl_special_prefixes
2912 The list of characters that are word break characters, but should
2913 be left in TEXT when it is passed to the completion function.
2914 Programs can use this to help determine what kind of completing to
2915 do. For instance, Bash sets this variable to "$@" so that it can
2916 complete shell variables and hostnames.
2918 -- Variable: int rl_completion_query_items
2919 Up to this many items will be displayed in response to a
2920 possible-completions call. After that, readline asks the user if
2921 she is sure she wants to see them all. The default value is 100.
2922 A negative value indicates that Readline should never ask the user.
2924 -- Variable: int rl_completion_append_character
2925 When a single completion alternative matches at the end of the
2926 command line, this character is appended to the inserted
2927 completion text. The default is a space character (` '). Setting
2928 this to the null character (`\0') prevents anything being appended
2929 automatically. This can be changed in application-specific
2930 completion functions to provide the "most sensible word separator
2931 character" according to an application-specific command line
2932 syntax specification.
2934 -- Variable: int rl_completion_suppress_append
2935 If non-zero, RL_COMPLETION_APPEND_CHARACTER is not appended to
2936 matches at the end of the command line, as described above. It is
2937 set to 0 before any application-specific completion function is
2938 called, and may only be changed within such a function.
2940 -- Variable: int rl_completion_quote_character
2941 When Readline is completing quoted text, as delimited by one of the
2942 characters in RL_COMPLETER_QUOTE_CHARACTERS, it sets this variable
2943 to the quoting character found. This is set before any
2944 application-specific completion function is called.
2946 -- Variable: int rl_completion_suppress_quote
2947 If non-zero, Readline does not append a matching quote character
2948 when performing completion on a quoted string. It is set to 0
2949 before any application-specific completion function is called, and
2950 may only be changed within such a function.
2952 -- Variable: int rl_completion_found_quote
2953 When Readline is completing quoted text, it sets this variable to
2954 a non-zero value if the word being completed contains or is
2955 delimited by any quoting characters, including backslashes. This
2956 is set before any application-specific completion function is
2959 -- Variable: int rl_completion_mark_symlink_dirs
2960 If non-zero, a slash will be appended to completed filenames that
2961 are symbolic links to directory names, subject to the value of the
2962 user-settable MARK-DIRECTORIES variable. This variable exists so
2963 that application-specific completion functions can override the
2964 user's global preference (set via the MARK-SYMLINKED-DIRECTORIES
2965 Readline variable) if appropriate. This variable is set to the
2966 user's preference before any application-specific completion
2967 function is called, so unless that function modifies the value,
2968 the user's preferences are honored.
2970 -- Variable: int rl_ignore_completion_duplicates
2971 If non-zero, then duplicates in the matches are removed. The
2974 -- Variable: int rl_filename_completion_desired
2975 Non-zero means that the results of the matches are to be treated as
2976 filenames. This is _always_ zero when completion is attempted,
2977 and can only be changed within an application-specific completion
2978 function. If it is set to a non-zero value by such a function,
2979 directory names have a slash appended and Readline attempts to
2980 quote completed filenames if they contain any characters in
2981 `rl_filename_quote_characters' and `rl_filename_quoting_desired'
2982 is set to a non-zero value.
2984 -- Variable: int rl_filename_quoting_desired
2985 Non-zero means that the results of the matches are to be quoted
2986 using double quotes (or an application-specific quoting mechanism)
2987 if the completed filename contains any characters in
2988 `rl_filename_quote_chars'. This is _always_ non-zero when
2989 completion is attempted, and can only be changed within an
2990 application-specific completion function. The quoting is effected
2991 via a call to the function pointed to by
2992 `rl_filename_quoting_function'.
2994 -- Variable: int rl_attempted_completion_over
2995 If an application-specific completion function assigned to
2996 `rl_attempted_completion_function' sets this variable to a non-zero
2997 value, Readline will not perform its default filename completion
2998 even if the application's completion function returns no matches.
2999 It should be set only by an application's completion function.
3001 -- Variable: int rl_completion_type
3002 Set to a character describing the type of completion Readline is
3003 currently attempting; see the description of
3004 `rl_complete_internal()' (*note Completion Functions::) for the
3005 list of characters. This is set to the appropriate value before
3006 any application-specific completion function is called, allowing
3007 such functions to present the same interface as `rl_complete()'.
3009 -- Variable: int rl_inhibit_completion
3010 If this variable is non-zero, completion is inhibited. The
3011 completion character will be inserted as any other bound to
3015 File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers
3017 2.6.4 A Short Completion Example
3018 --------------------------------
3020 Here is a small application demonstrating the use of the GNU Readline
3021 library. It is called `fileman', and the source code resides in
3022 `examples/fileman.c'. This sample application provides completion of
3023 command names, line editing features, and access to the history list.
3025 /* fileman.c -- A tiny application which demonstrates how to use the
3026 GNU Readline library. This application interactively allows users
3027 to manipulate files and their modes. */
3030 #include <sys/types.h>
3031 #include <sys/file.h>
3032 #include <sys/stat.h>
3033 #include <sys/errno.h>
3035 #include <readline/readline.h>
3036 #include <readline/history.h>
3038 extern char *xmalloc ();
3040 /* The names of functions that actually do the manipulation. */
3041 int com_list __P((char *));
3042 int com_view __P((char *));
3043 int com_rename __P((char *));
3044 int com_stat __P((char *));
3045 int com_pwd __P((char *));
3046 int com_delete __P((char *));
3047 int com_help __P((char *));
3048 int com_cd __P((char *));
3049 int com_quit __P((char *));
3051 /* A structure which contains information on the commands this program
3055 char *name; /* User printable name of the function. */
3056 rl_icpfunc_t *func; /* Function to call to do the job. */
3057 char *doc; /* Documentation for this function. */
3060 COMMAND commands[] = {
3061 { "cd", com_cd, "Change to directory DIR" },
3062 { "delete", com_delete, "Delete FILE" },
3063 { "help", com_help, "Display this text" },
3064 { "?", com_help, "Synonym for `help'" },
3065 { "list", com_list, "List files in DIR" },
3066 { "ls", com_list, "Synonym for `list'" },
3067 { "pwd", com_pwd, "Print the current working directory" },
3068 { "quit", com_quit, "Quit using Fileman" },
3069 { "rename", com_rename, "Rename FILE to NEWNAME" },
3070 { "stat", com_stat, "Print out statistics on FILE" },
3071 { "view", com_view, "View the contents of FILE" },
3072 { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL }
3075 /* Forward declarations. */
3076 char *stripwhite ();
3077 COMMAND *find_command ();
3079 /* The name of this program, as taken from argv[0]. */
3082 /* When non-zero, this means the user is done using this program. */
3091 r = xmalloc (strlen (s) + 1);
3104 initialize_readline (); /* Bind our completer. */
3106 /* Loop reading and executing lines until the user quits. */
3107 for ( ; done == 0; )
3109 line = readline ("FileMan: ");
3114 /* Remove leading and trailing whitespace from the line.
3115 Then, if there is anything left, add it to the history list
3117 s = stripwhite (line);
3130 /* Execute a command line. */
3139 /* Isolate the command word. */
3141 while (line[i] && whitespace (line[i]))
3145 while (line[i] && !whitespace (line[i]))
3151 command = find_command (word);
3155 fprintf (stderr, "%s: No such command for FileMan.\n", word);
3159 /* Get argument to command, if any. */
3160 while (whitespace (line[i]))
3165 /* Call the function. */
3166 return ((*(command->func)) (word));
3169 /* Look up NAME as the name of a command, and return a pointer to that
3170 command. Return a NULL pointer if NAME isn't a command name. */
3177 for (i = 0; commands[i].name; i++)
3178 if (strcmp (name, commands[i].name) == 0)
3179 return (&commands[i]);
3181 return ((COMMAND *)NULL);
3184 /* Strip whitespace from the start and end of STRING. Return a pointer
3190 register char *s, *t;
3192 for (s = string; whitespace (*s); s++)
3198 t = s + strlen (s) - 1;
3199 while (t > s && whitespace (*t))
3206 /* **************************************************************** */
3208 /* Interface to Readline Completion */
3210 /* **************************************************************** */
3212 char *command_generator __P((const char *, int));
3213 char **fileman_completion __P((const char *, int, int));
3215 /* Tell the GNU Readline library how to complete. We want to try to
3216 complete on command names if this is the first word in the line, or
3217 on filenames if not. */
3218 initialize_readline ()
3220 /* Allow conditional parsing of the ~/.inputrc file. */
3221 rl_readline_name = "FileMan";
3223 /* Tell the completer that we want a crack first. */
3224 rl_attempted_completion_function = fileman_completion;
3227 /* Attempt to complete on the contents of TEXT. START and END
3228 bound the region of rl_line_buffer that contains the word to
3229 complete. TEXT is the word to complete. We can use the entire
3230 contents of rl_line_buffer in case we want to do some simple
3231 parsing. Returnthe array of matches, or NULL if there aren't any. */
3233 fileman_completion (text, start, end)
3239 matches = (char **)NULL;
3241 /* If this word is at the start of the line, then it is a command
3242 to complete. Otherwise it is the name of a file in the current
3245 matches = rl_completion_matches (text, command_generator);
3250 /* Generator function for command completion. STATE lets us
3251 know whether to start from scratch; without any state
3252 (i.e. STATE == 0), then we start at the top of the list. */
3254 command_generator (text, state)
3258 static int list_index, len;
3261 /* If this is a new word to complete, initialize now. This
3262 includes saving the length of TEXT for efficiency, and
3263 initializing the index variable to 0. */
3267 len = strlen (text);
3270 /* Return the next name which partially matches from the
3272 while (name = commands[list_index].name)
3276 if (strncmp (name, text, len) == 0)
3277 return (dupstr(name));
3280 /* If no names matched, then return NULL. */
3281 return ((char *)NULL);
3284 /* **************************************************************** */
3286 /* FileMan Commands */
3288 /* **************************************************************** */
3290 /* String to pass to system (). This is for the LIST, VIEW and RENAME
3292 static char syscom[1024];
3294 /* List the file(s) named in arg. */
3301 sprintf (syscom, "ls -FClg %s", arg);
3302 return (system (syscom));
3308 if (!valid_argument ("view", arg))
3311 sprintf (syscom, "more %s", arg);
3312 return (system (syscom));
3318 too_dangerous ("rename");
3327 if (!valid_argument ("stat", arg))
3330 if (stat (arg, &finfo) == -1)
3336 printf ("Statistics for `%s':\n", arg);
3338 printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
3340 (finfo.st_nlink == 1) ? "" : "s",
3342 (finfo.st_size == 1) ? "" : "s");
3343 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
3344 printf (" Last access at: %s", ctime (&finfo.st_atime));
3345 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
3352 too_dangerous ("delete");
3356 /* Print out help for ARG, or for all of the commands if ARG is
3364 for (i = 0; commands[i].name; i++)
3366 if (!*arg || (strcmp (arg, commands[i].name) == 0))
3368 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
3375 printf ("No commands match `%s'. Possibilties are:\n", arg);
3377 for (i = 0; commands[i].name; i++)
3379 /* Print in six columns. */
3386 printf ("%s\t", commands[i].name);
3396 /* Change to the directory ARG. */
3400 if (chdir (arg) == -1)
3410 /* Print out the current working directory. */
3416 s = getcwd (dir, sizeof(dir) - 1);
3419 printf ("Error getting pwd: %s\n", dir);
3423 printf ("Current directory is %s\n", dir);
3427 /* The user wishes to quit using this program. Just set DONE
3436 /* Function which tells you that you can't do this. */
3437 too_dangerous (caller)
3441 "%s: Too dangerous for me to distribute.\n",
3443 fprintf (stderr, "Write it yourself.\n");
3446 /* Return non-zero if ARG is a valid argument for CALLER,
3447 else print an error message and return zero. */
3449 valid_argument (caller, arg)
3454 fprintf (stderr, "%s: Argument required.\n", caller);
3462 File: readline.info, Node: Copying This Manual, Next: Concept Index, Prev: Programming with GNU Readline, Up: Top
3464 Appendix A Copying This Manual
3465 ******************************
3469 * GNU Free Documentation License:: License for copying this manual.
3472 File: readline.info, Node: GNU Free Documentation License, Up: Copying This Manual
3474 A.1 GNU Free Documentation License
3475 ==================================
3477 Version 1.2, November 2002
3479 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
3480 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
3482 Everyone is permitted to copy and distribute verbatim copies
3483 of this license document, but changing it is not allowed.
3487 The purpose of this License is to make a manual, textbook, or other
3488 functional and useful document "free" in the sense of freedom: to
3489 assure everyone the effective freedom to copy and redistribute it,
3490 with or without modifying it, either commercially or
3491 noncommercially. Secondarily, this License preserves for the
3492 author and publisher a way to get credit for their work, while not
3493 being considered responsible for modifications made by others.
3495 This License is a kind of "copyleft", which means that derivative
3496 works of the document must themselves be free in the same sense.
3497 It complements the GNU General Public License, which is a copyleft
3498 license designed for free software.
3500 We have designed this License in order to use it for manuals for
3501 free software, because free software needs free documentation: a
3502 free program should come with manuals providing the same freedoms
3503 that the software does. But this License is not limited to
3504 software manuals; it can be used for any textual work, regardless
3505 of subject matter or whether it is published as a printed book.
3506 We recommend this License principally for works whose purpose is
3507 instruction or reference.
3509 1. APPLICABILITY AND DEFINITIONS
3511 This License applies to any manual or other work, in any medium,
3512 that contains a notice placed by the copyright holder saying it
3513 can be distributed under the terms of this License. Such a notice
3514 grants a world-wide, royalty-free license, unlimited in duration,
3515 to use that work under the conditions stated herein. The
3516 "Document", below, refers to any such manual or work. Any member
3517 of the public is a licensee, and is addressed as "you". You
3518 accept the license if you copy, modify or distribute the work in a
3519 way requiring permission under copyright law.
3521 A "Modified Version" of the Document means any work containing the
3522 Document or a portion of it, either copied verbatim, or with
3523 modifications and/or translated into another language.
3525 A "Secondary Section" is a named appendix or a front-matter section
3526 of the Document that deals exclusively with the relationship of the
3527 publishers or authors of the Document to the Document's overall
3528 subject (or to related matters) and contains nothing that could
3529 fall directly within that overall subject. (Thus, if the Document
3530 is in part a textbook of mathematics, a Secondary Section may not
3531 explain any mathematics.) The relationship could be a matter of
3532 historical connection with the subject or with related matters, or
3533 of legal, commercial, philosophical, ethical or political position
3536 The "Invariant Sections" are certain Secondary Sections whose
3537 titles are designated, as being those of Invariant Sections, in
3538 the notice that says that the Document is released under this
3539 License. If a section does not fit the above definition of
3540 Secondary then it is not allowed to be designated as Invariant.
3541 The Document may contain zero Invariant Sections. If the Document
3542 does not identify any Invariant Sections then there are none.
3544 The "Cover Texts" are certain short passages of text that are
3545 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
3546 that says that the Document is released under this License. A
3547 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
3548 be at most 25 words.
3550 A "Transparent" copy of the Document means a machine-readable copy,
3551 represented in a format whose specification is available to the
3552 general public, that is suitable for revising the document
3553 straightforwardly with generic text editors or (for images
3554 composed of pixels) generic paint programs or (for drawings) some
3555 widely available drawing editor, and that is suitable for input to
3556 text formatters or for automatic translation to a variety of
3557 formats suitable for input to text formatters. A copy made in an
3558 otherwise Transparent file format whose markup, or absence of
3559 markup, has been arranged to thwart or discourage subsequent
3560 modification by readers is not Transparent. An image format is
3561 not Transparent if used for any substantial amount of text. A
3562 copy that is not "Transparent" is called "Opaque".
3564 Examples of suitable formats for Transparent copies include plain
3565 ASCII without markup, Texinfo input format, LaTeX input format,
3566 SGML or XML using a publicly available DTD, and
3567 standard-conforming simple HTML, PostScript or PDF designed for
3568 human modification. Examples of transparent image formats include
3569 PNG, XCF and JPG. Opaque formats include proprietary formats that
3570 can be read and edited only by proprietary word processors, SGML or
3571 XML for which the DTD and/or processing tools are not generally
3572 available, and the machine-generated HTML, PostScript or PDF
3573 produced by some word processors for output purposes only.
3575 The "Title Page" means, for a printed book, the title page itself,
3576 plus such following pages as are needed to hold, legibly, the
3577 material this License requires to appear in the title page. For
3578 works in formats which do not have any title page as such, "Title
3579 Page" means the text near the most prominent appearance of the
3580 work's title, preceding the beginning of the body of the text.
3582 A section "Entitled XYZ" means a named subunit of the Document
3583 whose title either is precisely XYZ or contains XYZ in parentheses
3584 following text that translates XYZ in another language. (Here XYZ
3585 stands for a specific section name mentioned below, such as
3586 "Acknowledgements", "Dedications", "Endorsements", or "History".)
3587 To "Preserve the Title" of such a section when you modify the
3588 Document means that it remains a section "Entitled XYZ" according
3591 The Document may include Warranty Disclaimers next to the notice
3592 which states that this License applies to the Document. These
3593 Warranty Disclaimers are considered to be included by reference in
3594 this License, but only as regards disclaiming warranties: any other
3595 implication that these Warranty Disclaimers may have is void and
3596 has no effect on the meaning of this License.
3600 You may copy and distribute the Document in any medium, either
3601 commercially or noncommercially, provided that this License, the
3602 copyright notices, and the license notice saying this License
3603 applies to the Document are reproduced in all copies, and that you
3604 add no other conditions whatsoever to those of this License. You
3605 may not use technical measures to obstruct or control the reading
3606 or further copying of the copies you make or distribute. However,
3607 you may accept compensation in exchange for copies. If you
3608 distribute a large enough number of copies you must also follow
3609 the conditions in section 3.
3611 You may also lend copies, under the same conditions stated above,
3612 and you may publicly display copies.
3614 3. COPYING IN QUANTITY
3616 If you publish printed copies (or copies in media that commonly
3617 have printed covers) of the Document, numbering more than 100, and
3618 the Document's license notice requires Cover Texts, you must
3619 enclose the copies in covers that carry, clearly and legibly, all
3620 these Cover Texts: Front-Cover Texts on the front cover, and
3621 Back-Cover Texts on the back cover. Both covers must also clearly
3622 and legibly identify you as the publisher of these copies. The
3623 front cover must present the full title with all words of the
3624 title equally prominent and visible. You may add other material
3625 on the covers in addition. Copying with changes limited to the
3626 covers, as long as they preserve the title of the Document and
3627 satisfy these conditions, can be treated as verbatim copying in
3630 If the required texts for either cover are too voluminous to fit
3631 legibly, you should put the first ones listed (as many as fit
3632 reasonably) on the actual cover, and continue the rest onto
3635 If you publish or distribute Opaque copies of the Document
3636 numbering more than 100, you must either include a
3637 machine-readable Transparent copy along with each Opaque copy, or
3638 state in or with each Opaque copy a computer-network location from
3639 which the general network-using public has access to download
3640 using public-standard network protocols a complete Transparent
3641 copy of the Document, free of added material. If you use the
3642 latter option, you must take reasonably prudent steps, when you
3643 begin distribution of Opaque copies in quantity, to ensure that
3644 this Transparent copy will remain thus accessible at the stated
3645 location until at least one year after the last time you
3646 distribute an Opaque copy (directly or through your agents or
3647 retailers) of that edition to the public.
3649 It is requested, but not required, that you contact the authors of
3650 the Document well before redistributing any large number of
3651 copies, to give them a chance to provide you with an updated
3652 version of the Document.
3656 You may copy and distribute a Modified Version of the Document
3657 under the conditions of sections 2 and 3 above, provided that you
3658 release the Modified Version under precisely this License, with
3659 the Modified Version filling the role of the Document, thus
3660 licensing distribution and modification of the Modified Version to
3661 whoever possesses a copy of it. In addition, you must do these
3662 things in the Modified Version:
3664 A. Use in the Title Page (and on the covers, if any) a title
3665 distinct from that of the Document, and from those of
3666 previous versions (which should, if there were any, be listed
3667 in the History section of the Document). You may use the
3668 same title as a previous version if the original publisher of
3669 that version gives permission.
3671 B. List on the Title Page, as authors, one or more persons or
3672 entities responsible for authorship of the modifications in
3673 the Modified Version, together with at least five of the
3674 principal authors of the Document (all of its principal
3675 authors, if it has fewer than five), unless they release you
3676 from this requirement.
3678 C. State on the Title page the name of the publisher of the
3679 Modified Version, as the publisher.
3681 D. Preserve all the copyright notices of the Document.
3683 E. Add an appropriate copyright notice for your modifications
3684 adjacent to the other copyright notices.
3686 F. Include, immediately after the copyright notices, a license
3687 notice giving the public permission to use the Modified
3688 Version under the terms of this License, in the form shown in
3691 G. Preserve in that license notice the full lists of Invariant
3692 Sections and required Cover Texts given in the Document's
3695 H. Include an unaltered copy of this License.
3697 I. Preserve the section Entitled "History", Preserve its Title,
3698 and add to it an item stating at least the title, year, new
3699 authors, and publisher of the Modified Version as given on
3700 the Title Page. If there is no section Entitled "History" in
3701 the Document, create one stating the title, year, authors,
3702 and publisher of the Document as given on its Title Page,
3703 then add an item describing the Modified Version as stated in
3704 the previous sentence.
3706 J. Preserve the network location, if any, given in the Document
3707 for public access to a Transparent copy of the Document, and
3708 likewise the network locations given in the Document for
3709 previous versions it was based on. These may be placed in
3710 the "History" section. You may omit a network location for a
3711 work that was published at least four years before the
3712 Document itself, or if the original publisher of the version
3713 it refers to gives permission.
3715 K. For any section Entitled "Acknowledgements" or "Dedications",
3716 Preserve the Title of the section, and preserve in the
3717 section all the substance and tone of each of the contributor
3718 acknowledgements and/or dedications given therein.
3720 L. Preserve all the Invariant Sections of the Document,
3721 unaltered in their text and in their titles. Section numbers
3722 or the equivalent are not considered part of the section
3725 M. Delete any section Entitled "Endorsements". Such a section
3726 may not be included in the Modified Version.
3728 N. Do not retitle any existing section to be Entitled
3729 "Endorsements" or to conflict in title with any Invariant
3732 O. Preserve any Warranty Disclaimers.
3734 If the Modified Version includes new front-matter sections or
3735 appendices that qualify as Secondary Sections and contain no
3736 material copied from the Document, you may at your option
3737 designate some or all of these sections as invariant. To do this,
3738 add their titles to the list of Invariant Sections in the Modified
3739 Version's license notice. These titles must be distinct from any
3740 other section titles.
3742 You may add a section Entitled "Endorsements", provided it contains
3743 nothing but endorsements of your Modified Version by various
3744 parties--for example, statements of peer review or that the text
3745 has been approved by an organization as the authoritative
3746 definition of a standard.
3748 You may add a passage of up to five words as a Front-Cover Text,
3749 and a passage of up to 25 words as a Back-Cover Text, to the end
3750 of the list of Cover Texts in the Modified Version. Only one
3751 passage of Front-Cover Text and one of Back-Cover Text may be
3752 added by (or through arrangements made by) any one entity. If the
3753 Document already includes a cover text for the same cover,
3754 previously added by you or by arrangement made by the same entity
3755 you are acting on behalf of, you may not add another; but you may
3756 replace the old one, on explicit permission from the previous
3757 publisher that added the old one.
3759 The author(s) and publisher(s) of the Document do not by this
3760 License give permission to use their names for publicity for or to
3761 assert or imply endorsement of any Modified Version.
3763 5. COMBINING DOCUMENTS
3765 You may combine the Document with other documents released under
3766 this License, under the terms defined in section 4 above for
3767 modified versions, provided that you include in the combination
3768 all of the Invariant Sections of all of the original documents,
3769 unmodified, and list them all as Invariant Sections of your
3770 combined work in its license notice, and that you preserve all
3771 their Warranty Disclaimers.
3773 The combined work need only contain one copy of this License, and
3774 multiple identical Invariant Sections may be replaced with a single
3775 copy. If there are multiple Invariant Sections with the same name
3776 but different contents, make the title of each such section unique
3777 by adding at the end of it, in parentheses, the name of the
3778 original author or publisher of that section if known, or else a
3779 unique number. Make the same adjustment to the section titles in
3780 the list of Invariant Sections in the license notice of the
3783 In the combination, you must combine any sections Entitled
3784 "History" in the various original documents, forming one section
3785 Entitled "History"; likewise combine any sections Entitled
3786 "Acknowledgements", and any sections Entitled "Dedications". You
3787 must delete all sections Entitled "Endorsements."
3789 6. COLLECTIONS OF DOCUMENTS
3791 You may make a collection consisting of the Document and other
3792 documents released under this License, and replace the individual
3793 copies of this License in the various documents with a single copy
3794 that is included in the collection, provided that you follow the
3795 rules of this License for verbatim copying of each of the
3796 documents in all other respects.
3798 You may extract a single document from such a collection, and
3799 distribute it individually under this License, provided you insert
3800 a copy of this License into the extracted document, and follow
3801 this License in all other respects regarding verbatim copying of
3804 7. AGGREGATION WITH INDEPENDENT WORKS
3806 A compilation of the Document or its derivatives with other
3807 separate and independent documents or works, in or on a volume of
3808 a storage or distribution medium, is called an "aggregate" if the
3809 copyright resulting from the compilation is not used to limit the
3810 legal rights of the compilation's users beyond what the individual
3811 works permit. When the Document is included an aggregate, this
3812 License does not apply to the other works in the aggregate which
3813 are not themselves derivative works of the Document.
3815 If the Cover Text requirement of section 3 is applicable to these
3816 copies of the Document, then if the Document is less than one half
3817 of the entire aggregate, the Document's Cover Texts may be placed
3818 on covers that bracket the Document within the aggregate, or the
3819 electronic equivalent of covers if the Document is in electronic
3820 form. Otherwise they must appear on printed covers that bracket
3821 the whole aggregate.
3825 Translation is considered a kind of modification, so you may
3826 distribute translations of the Document under the terms of section
3827 4. Replacing Invariant Sections with translations requires special
3828 permission from their copyright holders, but you may include
3829 translations of some or all Invariant Sections in addition to the
3830 original versions of these Invariant Sections. You may include a
3831 translation of this License, and all the license notices in the
3832 Document, and any Warranty Disclaimers, provided that you also
3833 include the original English version of this License and the
3834 original versions of those notices and disclaimers. In case of a
3835 disagreement between the translation and the original version of
3836 this License or a notice or disclaimer, the original version will
3839 If a section in the Document is Entitled "Acknowledgements",
3840 "Dedications", or "History", the requirement (section 4) to
3841 Preserve its Title (section 1) will typically require changing the
3846 You may not copy, modify, sublicense, or distribute the Document
3847 except as expressly provided for under this License. Any other
3848 attempt to copy, modify, sublicense or distribute the Document is
3849 void, and will automatically terminate your rights under this
3850 License. However, parties who have received copies, or rights,
3851 from you under this License will not have their licenses
3852 terminated so long as such parties remain in full compliance.
3854 10. FUTURE REVISIONS OF THIS LICENSE
3856 The Free Software Foundation may publish new, revised versions of
3857 the GNU Free Documentation License from time to time. Such new
3858 versions will be similar in spirit to the present version, but may
3859 differ in detail to address new problems or concerns. See
3860 `http://www.gnu.org/copyleft/'.
3862 Each version of the License is given a distinguishing version
3863 number. If the Document specifies that a particular numbered
3864 version of this License "or any later version" applies to it, you
3865 have the option of following the terms and conditions either of
3866 that specified version or of any later version that has been
3867 published (not as a draft) by the Free Software Foundation. If
3868 the Document does not specify a version number of this License,
3869 you may choose any version ever published (not as a draft) by the
3870 Free Software Foundation.
3872 A.1.1 ADDENDUM: How to use this License for your documents
3873 ----------------------------------------------------------
3875 To use this License in a document you have written, include a copy of
3876 the License in the document and put the following copyright and license
3877 notices just after the title page:
3879 Copyright (C) YEAR YOUR NAME.
3880 Permission is granted to copy, distribute and/or modify this document
3881 under the terms of the GNU Free Documentation License, Version 1.2
3882 or any later version published by the Free Software Foundation;
3883 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
3884 A copy of the license is included in the section entitled ``GNU
3885 Free Documentation License''.
3887 If you have Invariant Sections, Front-Cover Texts and Back-Cover
3888 Texts, replace the "with...Texts." line with this:
3890 with the Invariant Sections being LIST THEIR TITLES, with
3891 the Front-Cover Texts being LIST, and with the Back-Cover Texts
3894 If you have Invariant Sections without Cover Texts, or some other
3895 combination of the three, merge those two alternatives to suit the
3898 If your document contains nontrivial examples of program code, we
3899 recommend releasing these examples in parallel under your choice of
3900 free software license, such as the GNU General Public License, to
3901 permit their use in free software.
3904 File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: Copying This Manual, Up: Top