1 This is readline.info, produced by makeinfo version 4.7 from
2 /Users/chet/src/bash/readline-src/doc/rlman.texi.
4 This manual describes the GNU Readline Library (version 5.1-beta1,
5 11 November 2005), 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
339 When a program which uses the Readline library starts up, the init
340 file is read, and the key bindings are set.
342 In addition, the `C-x C-r' command re-reads this init file, thus
343 incorporating any changes that you might have made to it.
347 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
349 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
351 * Sample Init File:: An example inputrc file.
354 File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
356 1.3.1 Readline Init File Syntax
357 -------------------------------
359 There are only a few basic constructs allowed in the Readline init
360 file. Blank lines are ignored. Lines beginning with a `#' are
361 comments. Lines beginning with a `$' indicate conditional constructs
362 (*note Conditional Init Constructs::). Other lines denote variable
363 settings and key bindings.
366 You can modify the run-time behavior of Readline by altering the
367 values of variables in Readline using the `set' command within the
368 init file. The syntax is simple:
372 Here, for example, is how to change from the default Emacs-like
373 key binding to use `vi' line editing commands:
377 Variable names and values, where appropriate, are recognized
378 without regard to case. Unrecognized variable names are ignored.
380 Boolean variables (those that can be set to on or off) are set to
381 on if the value is null or empty, ON (case-insensitive), or 1.
382 Any other value results in the variable being set to off.
384 A great deal of run-time behavior is changeable with the following
388 Controls what happens when Readline wants to ring the
389 terminal bell. If set to `none', Readline never rings the
390 bell. If set to `visible', Readline uses a visible bell if
391 one is available. If set to `audible' (the default),
392 Readline attempts to ring the terminal's bell.
394 `bind-tty-special-chars'
395 If set to `on', Readline attempts to bind the control
396 characters treated specially by the kernel's terminal driver
397 to their Readline equivalents.
400 The string to insert at the beginning of the line when the
401 `insert-comment' command is executed. The default value is
404 `completion-ignore-case'
405 If set to `on', Readline performs filename matching and
406 completion in a case-insensitive fashion. The default value
409 `completion-query-items'
410 The number of possible completions that determines when the
411 user is asked whether the list of possibilities should be
412 displayed. If the number of possible completions is greater
413 than this value, Readline will ask the user whether or not he
414 wishes to view them; otherwise, they are simply listed. This
415 variable must be set to an integer value greater than or
416 equal to 0. A negative value means Readline should never ask.
417 The default limit is `100'.
420 If set to `on', Readline will convert characters with the
421 eighth bit set to an ASCII key sequence by stripping the
422 eighth bit and prefixing an <ESC> character, converting them
423 to a meta-prefixed key sequence. The default value is `on'.
426 If set to `On', Readline will inhibit word completion.
427 Completion characters will be inserted into the line as if
428 they had been mapped to `self-insert'. The default is `off'.
431 The `editing-mode' variable controls which default set of key
432 bindings is used. By default, Readline starts up in Emacs
433 editing mode, where the keystrokes are most similar to Emacs.
434 This variable can be set to either `emacs' or `vi'.
437 When set to `on', Readline will try to enable the application
438 keypad when it is called. Some systems need this to enable
439 the arrow keys. The default is `off'.
442 If set to `on', tilde expansion is performed when Readline
443 attempts word completion. The default is `off'.
445 `history-preserve-point'
446 If set to `on', the history code attempts to place point at
447 the same location on each history line retrieved with
448 `previous-history' or `next-history'. The default is `off'.
450 `horizontal-scroll-mode'
451 This variable can be set to either `on' or `off'. Setting it
452 to `on' means that the text of the lines being edited will
453 scroll horizontally on a single screen line when they are
454 longer than the width of the screen, instead of wrapping onto
455 a new screen line. By default, this variable is set to `off'.
458 If set to `on', Readline will enable eight-bit input (it will
459 not clear the eighth bit in the characters it reads),
460 regardless of what the terminal claims it can support. The
461 default value is `off'. The name `meta-flag' is a synonym
464 `isearch-terminators'
465 The string of characters that should terminate an incremental
466 search without subsequently executing the character as a
467 command (*note Searching::). If this variable has not been
468 given a value, the characters <ESC> and `C-J' will terminate
469 an incremental search.
472 Sets Readline's idea of the current keymap for key binding
473 commands. Acceptable `keymap' names are `emacs',
474 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
475 `vi-command', and `vi-insert'. `vi' is equivalent to
476 `vi-command'; `emacs' is equivalent to `emacs-standard'. The
477 default value is `emacs'. The value of the `editing-mode'
478 variable also affects the default keymap.
481 If set to `on', completed directory names have a slash
482 appended. The default is `on'.
484 `mark-modified-lines'
485 This variable, when set to `on', causes Readline to display an
486 asterisk (`*') at the start of history lines which have been
487 modified. This variable is `off' by default.
489 `mark-symlinked-directories'
490 If set to `on', completed names which are symbolic links to
491 directories have a slash appended (subject to the value of
492 `mark-directories'). The default is `off'.
495 This variable, when set to `on', causes Readline to match
496 files whose names begin with a `.' (hidden files) when
497 performing filename completion, unless the leading `.' is
498 supplied by the user in the filename to be completed. This
499 variable is `on' by default.
502 If set to `on', Readline will display characters with the
503 eighth bit set directly rather than as a meta-prefixed escape
504 sequence. The default is `off'.
507 If set to `on', Readline uses an internal `more'-like pager
508 to display a screenful of possible completions at a time.
509 This variable is `on' by default.
511 `print-completions-horizontally'
512 If set to `on', Readline will display completions with matches
513 sorted horizontally in alphabetical order, rather than down
514 the screen. The default is `off'.
516 `show-all-if-ambiguous'
517 This alters the default behavior of the completion functions.
518 If set to `on', words which have more than one possible
519 completion cause the matches to be listed immediately instead
520 of ringing the bell. The default value is `off'.
522 `show-all-if-unmodified'
523 This alters the default behavior of the completion functions
524 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
525 `on', words which have more than one possible completion
526 without any possible partial completion (the possible
527 completions don't share a common prefix) cause the matches to
528 be listed immediately instead of ringing the bell. The
529 default value is `off'.
532 If set to `on', a character denoting a file's type is
533 appended to the filename when listing possible completions.
534 The default is `off'.
538 The syntax for controlling key bindings in the init file is
539 simple. First you need to find the name of the command that you
540 want to change. The following sections contain tables of the
541 command name, the default keybinding, if any, and a short
542 description of what the command does.
544 Once you know the name of the command, simply place on a line in
545 the init file the name of the key you wish to bind the command to,
546 a colon, and then the name of the command. The name of the key
547 can be expressed in different ways, depending on what you find most
550 In addition to command names, readline allows keys to be bound to
551 a string that is inserted when the key is pressed (a MACRO).
553 KEYNAME: FUNCTION-NAME or MACRO
554 KEYNAME is the name of a key spelled out in English. For
556 Control-u: universal-argument
557 Meta-Rubout: backward-kill-word
558 Control-o: "> output"
560 In the above example, `C-u' is bound to the function
561 `universal-argument', `M-DEL' is bound to the function
562 `backward-kill-word', and `C-o' is bound to run the macro
563 expressed on the right hand side (that is, to insert the text
564 `> output' into the line).
566 A number of symbolic character names are recognized while
567 processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
568 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
570 "KEYSEQ": FUNCTION-NAME or MACRO
571 KEYSEQ differs from KEYNAME above in that strings denoting an
572 entire key sequence can be specified, by placing the key
573 sequence in double quotes. Some GNU Emacs style key escapes
574 can be used, as in the following example, but the special
575 character names are not recognized.
577 "\C-u": universal-argument
578 "\C-x\C-r": re-read-init-file
579 "\e[11~": "Function Key 1"
581 In the above example, `C-u' is again bound to the function
582 `universal-argument' (just as it was in the first example),
583 `C-x C-r' is bound to the function `re-read-init-file', and
584 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
588 The following GNU Emacs style escape sequences are available when
589 specifying key sequences:
604 <">, a double quotation mark
607 <'>, a single quote or apostrophe
609 In addition to the GNU Emacs style escape sequences, a second set
610 of backslash escapes is available:
637 the eight-bit character whose value is the octal value NNN
638 (one to three digits)
641 the eight-bit character whose value is the hexadecimal value
642 HH (one or two hex digits)
644 When entering the text of a macro, single or double quotes must be
645 used to indicate a macro definition. Unquoted text is assumed to
646 be a function name. In the macro body, the backslash escapes
647 described above are expanded. Backslash will quote any other
648 character in the macro text, including `"' and `''. For example,
649 the following binding will make `C-x \' insert a single `\' into
655 File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
657 1.3.2 Conditional Init Constructs
658 ---------------------------------
660 Readline implements a facility similar in spirit to the conditional
661 compilation features of the C preprocessor which allows key bindings
662 and variable settings to be performed as the result of tests. There
663 are four parser directives used.
666 The `$if' construct allows bindings to be made based on the
667 editing mode, the terminal being used, or the application using
668 Readline. The text of the test extends to the end of the line; no
669 characters are required to isolate it.
672 The `mode=' form of the `$if' directive is used to test
673 whether Readline is in `emacs' or `vi' mode. This may be
674 used in conjunction with the `set keymap' command, for
675 instance, to set bindings in the `emacs-standard' and
676 `emacs-ctlx' keymaps only if Readline is starting out in
680 The `term=' form may be used to include terminal-specific key
681 bindings, perhaps to bind the key sequences output by the
682 terminal's function keys. The word on the right side of the
683 `=' is tested against both the full name of the terminal and
684 the portion of the terminal name before the first `-'. This
685 allows `sun' to match both `sun' and `sun-cmd', for instance.
688 The APPLICATION construct is used to include
689 application-specific settings. Each program using the
690 Readline library sets the APPLICATION NAME, and you can test
691 for a particular value. This could be used to bind key
692 sequences to functions useful for a specific program. For
693 instance, the following command adds a key sequence that
694 quotes the current or previous word in Bash:
696 # Quote the current or previous word
697 "\C-xq": "\eb\"\ef\""
701 This command, as seen in the previous example, terminates an `$if'
705 Commands in this branch of the `$if' directive are executed if the
709 This directive takes a single filename as an argument and reads
710 commands and bindings from that file. For example, the following
711 directive reads from `/etc/inputrc':
712 $include /etc/inputrc
715 File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
717 1.3.3 Sample Init File
718 ----------------------
720 Here is an example of an INPUTRC file. This illustrates key binding,
721 variable assignment, and conditional syntax.
724 # This file controls the behaviour of line input editing for
725 # programs that use the GNU Readline library. Existing
726 # programs include FTP, Bash, and GDB.
728 # You can re-read the inputrc file with C-x C-r.
729 # Lines beginning with '#' are comments.
731 # First, include any systemwide bindings and variable
732 # assignments from /etc/Inputrc
733 $include /etc/Inputrc
736 # Set various bindings for emacs mode.
738 set editing-mode emacs
742 Meta-Control-h: backward-kill-word Text after the function name is ignored
745 # Arrow keys in keypad mode
747 #"\M-OD": backward-char
748 #"\M-OC": forward-char
749 #"\M-OA": previous-history
750 #"\M-OB": next-history
752 # Arrow keys in ANSI mode
754 "\M-[D": backward-char
755 "\M-[C": forward-char
756 "\M-[A": previous-history
757 "\M-[B": next-history
759 # Arrow keys in 8 bit keypad mode
761 #"\M-\C-OD": backward-char
762 #"\M-\C-OC": forward-char
763 #"\M-\C-OA": previous-history
764 #"\M-\C-OB": next-history
766 # Arrow keys in 8 bit ANSI mode
768 #"\M-\C-[D": backward-char
769 #"\M-\C-[C": forward-char
770 #"\M-\C-[A": previous-history
771 #"\M-\C-[B": next-history
777 # An old-style binding. This happens to be the default.
780 # Macros that are convenient for shell interaction
783 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
784 # prepare to type a quoted word --
785 # insert open and close double quotes
786 # and move to just after the open quote
788 # insert a backslash (testing backslash escapes
789 # in sequences and macros)
791 # Quote the current or previous word
792 "\C-xq": "\eb\"\ef\""
793 # Add a binding to refresh the line, which is unbound
794 "\C-xr": redraw-current-line
795 # Edit variable on current line.
796 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
799 # use a visible bell if one is available
800 set bell-style visible
802 # don't strip characters to 7 bits when reading
805 # allow iso-latin1 characters to be inserted rather
806 # than converted to prefix-meta sequences
809 # display characters with the eighth bit set directly
810 # rather than as meta-prefixed characters
813 # if there are more than 150 possible completions for
814 # a word, ask the user if he wants to see all of them
815 set completion-query-items 150
821 "\M-.": yank-last-arg
825 File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
827 1.4 Bindable Readline Commands
828 ==============================
832 * Commands For Moving:: Moving about the line.
833 * Commands For History:: Getting at previous lines.
834 * Commands For Text:: Commands for changing text.
835 * Commands For Killing:: Commands for killing and yanking.
836 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
837 * Commands For Completion:: Getting Readline to do the typing for you.
838 * Keyboard Macros:: Saving and re-executing typed characters
839 * Miscellaneous Commands:: Other miscellaneous commands.
841 This section describes Readline commands that may be bound to key
842 sequences. Command names without an accompanying key sequence are
845 In the following descriptions, "point" refers to the current cursor
846 position, and "mark" refers to a cursor position saved by the
847 `set-mark' command. The text between the point and mark is referred to
851 File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
853 1.4.1 Commands For Moving
854 -------------------------
856 `beginning-of-line (C-a)'
857 Move to the start of the current line.
860 Move to the end of the line.
863 Move forward a character.
865 `backward-char (C-b)'
866 Move back a character.
869 Move forward to the end of the next word. Words are composed of
872 `backward-word (M-b)'
873 Move back to the start of the current or previous word. Words are
874 composed of letters and digits.
877 Clear the screen and redraw the current line, leaving the current
878 line at the top of the screen.
880 `redraw-current-line ()'
881 Refresh the current line. By default, this is unbound.
885 File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
887 1.4.2 Commands For Manipulating The History
888 -------------------------------------------
890 `accept-line (Newline or Return)'
891 Accept the line regardless of where the cursor is. If this line is
892 non-empty, it may be added to the history list for future recall
893 with `add_history()'. If this line is a modified history line,
894 the history line is restored to its original state.
896 `previous-history (C-p)'
897 Move `back' through the history list, fetching the previous
901 Move `forward' through the history list, fetching the next command.
903 `beginning-of-history (M-<)'
904 Move to the first line in the history.
906 `end-of-history (M->)'
907 Move to the end of the input history, i.e., the line currently
910 `reverse-search-history (C-r)'
911 Search backward starting at the current line and moving `up'
912 through the history as necessary. This is an incremental search.
914 `forward-search-history (C-s)'
915 Search forward starting at the current line and moving `down'
916 through the the history as necessary. This is an incremental
919 `non-incremental-reverse-search-history (M-p)'
920 Search backward starting at the current line and moving `up'
921 through the history as necessary using a non-incremental search
922 for a string supplied by the user.
924 `non-incremental-forward-search-history (M-n)'
925 Search forward starting at the current line and moving `down'
926 through the the history as necessary using a non-incremental search
927 for a string supplied by the user.
929 `history-search-forward ()'
930 Search forward through the history for the string of characters
931 between the start of the current line and the point. This is a
932 non-incremental search. By default, this command is unbound.
934 `history-search-backward ()'
935 Search backward through the history for the string of characters
936 between the start of the current line and the point. This is a
937 non-incremental search. By default, this command is unbound.
939 `yank-nth-arg (M-C-y)'
940 Insert the first argument to the previous command (usually the
941 second word on the previous line) at point. With an argument N,
942 insert the Nth word from the previous command (the words in the
943 previous command begin with word 0). A negative argument inserts
944 the Nth word from the end of the previous command. Once the
945 argument N is computed, the argument is extracted as if the `!N'
946 history expansion had been specified.
948 `yank-last-arg (M-. or M-_)'
949 Insert last argument to the previous command (the last word of the
950 previous history entry). With an argument, behave exactly like
951 `yank-nth-arg'. Successive calls to `yank-last-arg' move back
952 through the history list, inserting the last argument of each line
953 in turn. The history expansion facilities are used to extract the
954 last argument, as if the `!$' history expansion had been specified.
958 File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
960 1.4.3 Commands For Changing Text
961 --------------------------------
964 Delete the character at point. If point is at the beginning of
965 the line, there are no characters in the line, and the last
966 character typed was not bound to `delete-char', then return EOF.
968 `backward-delete-char (Rubout)'
969 Delete the character behind the cursor. A numeric argument means
970 to kill the characters instead of deleting them.
972 `forward-backward-delete-char ()'
973 Delete the character under the cursor, unless the cursor is at the
974 end of the line, in which case the character behind the cursor is
975 deleted. By default, this is not bound to a key.
977 `quoted-insert (C-q or C-v)'
978 Add the next character typed to the line verbatim. This is how to
979 insert key sequences like `C-q', for example.
981 `tab-insert (M-<TAB>)'
982 Insert a tab character.
984 `self-insert (a, b, A, 1, !, ...)'
987 `transpose-chars (C-t)'
988 Drag the character before the cursor forward over the character at
989 the cursor, moving the cursor forward as well. If the insertion
990 point is at the end of the line, then this transposes the last two
991 characters of the line. Negative arguments have no effect.
993 `transpose-words (M-t)'
994 Drag the word before point past the word after point, moving point
995 past that word as well. If the insertion point is at the end of
996 the line, this transposes the last two words on the line.
999 Uppercase the current (or following) word. With a negative
1000 argument, uppercase the previous word, but do not move the cursor.
1002 `downcase-word (M-l)'
1003 Lowercase the current (or following) word. With a negative
1004 argument, lowercase the previous word, but do not move the cursor.
1006 `capitalize-word (M-c)'
1007 Capitalize the current (or following) word. With a negative
1008 argument, capitalize the previous word, but do not move the cursor.
1011 Toggle overwrite mode. With an explicit positive numeric argument,
1012 switches to overwrite mode. With an explicit non-positive numeric
1013 argument, switches to insert mode. This command affects only
1014 `emacs' mode; `vi' mode does overwrite differently. Each call to
1015 `readline()' starts in insert mode.
1017 In overwrite mode, characters bound to `self-insert' replace the
1018 text at point rather than pushing the text to the right.
1019 Characters bound to `backward-delete-char' replace the character
1020 before point with a space.
1022 By default, this command is unbound.
1026 File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
1028 1.4.4 Killing And Yanking
1029 -------------------------
1032 Kill the text from point to the end of the line.
1034 `backward-kill-line (C-x Rubout)'
1035 Kill backward to the beginning of the line.
1037 `unix-line-discard (C-u)'
1038 Kill backward from the cursor to the beginning of the current line.
1040 `kill-whole-line ()'
1041 Kill all characters on the current line, no matter where point is.
1042 By default, this is unbound.
1045 Kill from point to the end of the current word, or if between
1046 words, to the end of the next word. Word boundaries are the same
1049 `backward-kill-word (M-<DEL>)'
1050 Kill the word behind point. Word boundaries are the same as
1053 `unix-word-rubout (C-w)'
1054 Kill the word behind point, using white space as a word boundary.
1055 The killed text is saved on the kill-ring.
1057 `unix-filename-rubout ()'
1058 Kill the word behind point, using white space and the slash
1059 character as the word boundaries. The killed text is saved on the
1062 `delete-horizontal-space ()'
1063 Delete all spaces and tabs around point. By default, this is
1067 Kill the text in the current region. By default, this command is
1070 `copy-region-as-kill ()'
1071 Copy the text in the region to the kill buffer, so it can be yanked
1072 right away. By default, this command is unbound.
1074 `copy-backward-word ()'
1075 Copy the word before point to the kill buffer. The word
1076 boundaries are the same as `backward-word'. By default, this
1079 `copy-forward-word ()'
1080 Copy the word following point to the kill buffer. The word
1081 boundaries are the same as `forward-word'. By default, this
1085 Yank the top of the kill ring into the buffer at point.
1088 Rotate the kill-ring, and yank the new top. You can only do this
1089 if the prior command is `yank' or `yank-pop'.
1092 File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
1094 1.4.5 Specifying Numeric Arguments
1095 ----------------------------------
1097 `digit-argument (M-0, M-1, ... M--)'
1098 Add this digit to the argument already accumulating, or start a new
1099 argument. `M--' starts a negative argument.
1101 `universal-argument ()'
1102 This is another way to specify an argument. If this command is
1103 followed by one or more digits, optionally with a leading minus
1104 sign, those digits define the argument. If the command is
1105 followed by digits, executing `universal-argument' again ends the
1106 numeric argument, but is otherwise ignored. As a special case, if
1107 this command is immediately followed by a character that is
1108 neither a digit or minus sign, the argument count for the next
1109 command is multiplied by four. The argument count is initially
1110 one, so executing this function the first time makes the argument
1111 count four, a second time makes the argument count sixteen, and so
1112 on. By default, this is not bound to a key.
1115 File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
1117 1.4.6 Letting Readline Type For You
1118 -----------------------------------
1121 Attempt to perform completion on the text before point. The
1122 actual completion performed is application-specific. The default
1123 is filename completion.
1125 `possible-completions (M-?)'
1126 List the possible completions of the text before point.
1128 `insert-completions (M-*)'
1129 Insert all completions of the text before point that would have
1130 been generated by `possible-completions'.
1133 Similar to `complete', but replaces the word to be completed with
1134 a single match from the list of possible completions. Repeated
1135 execution of `menu-complete' steps through the list of possible
1136 completions, inserting each match in turn. At the end of the list
1137 of completions, the bell is rung (subject to the setting of
1138 `bell-style') and the original text is restored. An argument of N
1139 moves N positions forward in the list of matches; a negative
1140 argument may be used to move backward through the list. This
1141 command is intended to be bound to <TAB>, but is unbound by
1144 `delete-char-or-list ()'
1145 Deletes the character under the cursor if not at the beginning or
1146 end of the line (like `delete-char'). If at the end of the line,
1147 behaves identically to `possible-completions'. This command is
1152 File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
1154 1.4.7 Keyboard Macros
1155 ---------------------
1157 `start-kbd-macro (C-x ()'
1158 Begin saving the characters typed into the current keyboard macro.
1160 `end-kbd-macro (C-x ))'
1161 Stop saving the characters typed into the current keyboard macro
1162 and save the definition.
1164 `call-last-kbd-macro (C-x e)'
1165 Re-execute the last keyboard macro defined, by making the
1166 characters in the macro appear as if typed at the keyboard.
1170 File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
1172 1.4.8 Some Miscellaneous Commands
1173 ---------------------------------
1175 `re-read-init-file (C-x C-r)'
1176 Read in the contents of the INPUTRC file, and incorporate any
1177 bindings or variable assignments found there.
1180 Abort the current editing command and ring the terminal's bell
1181 (subject to the setting of `bell-style').
1183 `do-uppercase-version (M-a, M-b, M-X, ...)'
1184 If the metafied character X is lowercase, run the command that is
1185 bound to the corresponding uppercase character.
1187 `prefix-meta (<ESC>)'
1188 Metafy the next character typed. This is for keyboards without a
1189 meta key. Typing `<ESC> f' is equivalent to typing `M-f'.
1191 `undo (C-_ or C-x C-u)'
1192 Incremental undo, separately remembered for each line.
1195 Undo all changes made to this line. This is like executing the
1196 `undo' command enough times to get back to the beginning.
1198 `tilde-expand (M-~)'
1199 Perform tilde expansion on the current word.
1202 Set the mark to the point. If a numeric argument is supplied, the
1203 mark is set to that position.
1205 `exchange-point-and-mark (C-x C-x)'
1206 Swap the point with the mark. The current cursor position is set
1207 to the saved position, and the old cursor position is saved as the
1210 `character-search (C-])'
1211 A character is read and point is moved to the next occurrence of
1212 that character. A negative count searches for previous
1215 `character-search-backward (M-C-])'
1216 A character is read and point is moved to the previous occurrence
1217 of that character. A negative count searches for subsequent
1220 `insert-comment (M-#)'
1221 Without a numeric argument, the value of the `comment-begin'
1222 variable is inserted at the beginning of the current line. If a
1223 numeric argument is supplied, this command acts as a toggle: if
1224 the characters at the beginning of the line do not match the value
1225 of `comment-begin', the value is inserted, otherwise the
1226 characters in `comment-begin' are deleted from the beginning of
1227 the line. In either case, the line is accepted as if a newline
1231 Print all of the functions and their key bindings to the Readline
1232 output stream. If a numeric argument is supplied, the output is
1233 formatted in such a way that it can be made part of an INPUTRC
1234 file. This command is unbound by default.
1237 Print all of the settable variables and their values to the
1238 Readline output stream. If a numeric argument is supplied, the
1239 output is formatted in such a way that it can be made part of an
1240 INPUTRC file. This command is unbound by default.
1243 Print all of the Readline key sequences bound to macros and the
1244 strings they output. If a numeric argument is supplied, the
1245 output is formatted in such a way that it can be made part of an
1246 INPUTRC file. This command is unbound by default.
1248 `emacs-editing-mode (C-e)'
1249 When in `vi' command mode, this causes a switch to `emacs' editing
1252 `vi-editing-mode (M-C-j)'
1253 When in `emacs' editing mode, this causes a switch to `vi' editing
1258 File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
1260 1.5 Readline vi Mode
1261 ====================
1263 While the Readline library does not have a full set of `vi' editing
1264 functions, it does contain enough to allow simple editing of the line.
1265 The Readline `vi' mode behaves as specified in the POSIX 1003.2
1268 In order to switch interactively between `emacs' and `vi' editing
1269 modes, use the command `M-C-j' (bound to emacs-editing-mode when in
1270 `vi' mode and to vi-editing-mode in `emacs' mode). The Readline
1271 default is `emacs' mode.
1273 When you enter a line in `vi' mode, you are already placed in
1274 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
1275 you into `command' mode, where you can edit the text of the line with
1276 the standard `vi' movement keys, move to previous history lines with
1277 `k' and subsequent lines with `j', and so forth.
1279 This document describes the GNU Readline Library, a utility for
1280 aiding in the consistency of user interface across discrete programs
1281 that need to provide a command line interface.
1283 Copyright (C) 1988-2005 Free Software Foundation, Inc.
1285 Permission is granted to make and distribute verbatim copies of this
1286 manual provided the copyright notice and this permission notice pare
1287 preserved on all copies.
1289 Permission is granted to copy and distribute modified versions of
1290 this manual under the conditions for verbatim copying, provided that
1291 the entire resulting derived work is distributed under the terms of a
1292 permission notice identical to this one.
1294 Permission is granted to copy and distribute translations of this
1295 manual into another language, under the above conditions for modified
1296 versions, except that this permission notice may be stated in a
1297 translation approved by the Foundation.
1300 File: readline.info, Node: Programming with GNU Readline, Next: Copying This Manual, Prev: Command Line Editing, Up: Top
1302 2 Programming with GNU Readline
1303 *******************************
1305 This chapter describes the interface between the GNU Readline Library
1306 and other programs. If you are a programmer, and you wish to include
1307 the features found in GNU Readline such as completion, line editing,
1308 and interactive history manipulation in your own programs, this section
1313 * Basic Behavior:: Using the default behavior of Readline.
1314 * Custom Functions:: Adding your own functions to Readline.
1315 * Readline Variables:: Variables accessible to custom
1317 * Readline Convenience Functions:: Functions which Readline supplies to
1318 aid in writing your own custom
1320 * Readline Signal Handling:: How Readline behaves when it receives signals.
1321 * Custom Completers:: Supplanting or supplementing Readline's
1322 completion functions.
1325 File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline
1330 Many programs provide a command line interface, such as `mail', `ftp',
1331 and `sh'. For such programs, the default behaviour of Readline is
1332 sufficient. This section describes how to use Readline in the simplest
1333 way possible, perhaps to replace calls in your code to `gets()' or
1336 The function `readline()' prints a prompt PROMPT and then reads and
1337 returns a single line of text from the user. If PROMPT is `NULL' or
1338 the empty string, no prompt is displayed. The line `readline' returns
1339 is allocated with `malloc()'; the caller should `free()' the line when
1340 it has finished with it. The declaration for `readline' in ANSI C is
1342 `char *readline (const char *PROMPT);'
1345 `char *line = readline ("Enter a line: ");'
1346 in order to read a line of text from the user. The line returned
1347 has the final newline removed, so only the text remains.
1349 If `readline' encounters an `EOF' while reading the line, and the
1350 line is empty at that point, then `(char *)NULL' is returned.
1351 Otherwise, the line is ended just as if a newline had been typed.
1353 If you want the user to be able to get at the line later, (with
1354 <C-p> for example), you must call `add_history()' to save the line away
1355 in a "history" list of such lines.
1357 `add_history (line)';
1359 For full details on the GNU History Library, see the associated manual.
1361 It is preferable to avoid saving empty lines on the history list,
1362 since users rarely have a burning need to reuse a blank line. Here is
1363 a function which usefully replaces the standard `gets()' library
1364 function, and has the advantage of no static buffer to overflow:
1366 /* A static variable for holding the line. */
1367 static char *line_read = (char *)NULL;
1369 /* Read a string, and return a pointer to it.
1370 Returns NULL on EOF. */
1374 /* If the buffer has already been allocated,
1375 return the memory to the free pool. */
1379 line_read = (char *)NULL;
1382 /* Get a line from the user. */
1383 line_read = readline ("");
1385 /* If the line has any text in it,
1386 save it on the history. */
1387 if (line_read && *line_read)
1388 add_history (line_read);
1393 This function gives the user the default behaviour of <TAB>
1394 completion: completion on file names. If you do not want Readline to
1395 complete on filenames, you can change the binding of the <TAB> key with
1398 `int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);'
1400 `rl_bind_key()' takes two arguments: KEY is the character that you
1401 want to bind, and FUNCTION is the address of the function to call when
1402 KEY is pressed. Binding <TAB> to `rl_insert()' makes <TAB> insert
1403 itself. `rl_bind_key()' returns non-zero if KEY is not a valid ASCII
1404 character code (between 0 and 255).
1406 Thus, to disable the default <TAB> behavior, the following suffices:
1407 `rl_bind_key ('\t', rl_insert);'
1409 This code should be executed once at the start of your program; you
1410 might write a function called `initialize_readline()' which performs
1411 this and other desired initializations, such as installing custom
1412 completers (*note Custom Completers::).
1415 File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline
1417 2.2 Custom Functions
1418 ====================
1420 Readline provides many functions for manipulating the text of the line,
1421 but it isn't possible to anticipate the needs of all programs. This
1422 section describes the various functions and variables defined within
1423 the Readline library which allow a user program to add customized
1424 functionality to Readline.
1426 Before declaring any functions that customize Readline's behavior, or
1427 using any functionality Readline provides in other code, an application
1428 writer should include the file `<readline/readline.h>' in any file that
1429 uses Readline's features. Since some of the definitions in
1430 `readline.h' use the `stdio' library, the file `<stdio.h>' should be
1431 included before `readline.h'.
1433 `readline.h' defines a C preprocessor variable that should be
1434 treated as an integer, `RL_READLINE_VERSION', which may be used to
1435 conditionally compile application code depending on the installed
1436 Readline version. The value is a hexadecimal encoding of the major and
1437 minor version numbers of the library, of the form 0xMMMM. MM is the
1438 two-digit major version number; MM is the two-digit minor version
1439 number. For Readline 4.2, for example, the value of
1440 `RL_READLINE_VERSION' would be `0x0402'.
1444 * Readline Typedefs:: C declarations to make code readable.
1445 * Function Writing:: Variables and calling conventions.
1448 File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions
1450 2.2.1 Readline Typedefs
1451 -----------------------
1453 For readabilty, we declare a number of new object types, all pointers
1456 The reason for declaring these new types is to make it easier to
1457 write code describing pointers to C functions with appropriately
1458 prototyped arguments and return values.
1460 For instance, say we want to declare a variable FUNC as a pointer to
1461 a function which takes two `int' arguments and returns an `int' (this
1462 is the type of all of the Readline bindable functions). Instead of the
1463 classic C declaration
1467 or the ANSI-C style declaration
1469 `int (*func)(int, int);'
1473 `rl_command_func_t *func;'
1475 The full list of function pointer types available is
1477 `typedef int rl_command_func_t (int, int);'
1479 `typedef char *rl_compentry_func_t (const char *, int);'
1481 `typedef char **rl_completion_func_t (const char *, int, int);'
1483 `typedef char *rl_quote_func_t (char *, int, char *);'
1485 `typedef char *rl_dequote_func_t (char *, int);'
1487 `typedef int rl_compignore_func_t (char **);'
1489 `typedef void rl_compdisp_func_t (char **, int, int);'
1491 `typedef int rl_hook_func_t (void);'
1493 `typedef int rl_getc_func_t (FILE *);'
1495 `typedef int rl_linebuf_func_t (char *, int);'
1497 `typedef int rl_intfunc_t (int);'
1499 `#define rl_ivoidfunc_t rl_hook_func_t'
1501 `typedef int rl_icpfunc_t (char *);'
1503 `typedef int rl_icppfunc_t (char **);'
1505 `typedef void rl_voidfunc_t (void);'
1507 `typedef void rl_vintfunc_t (int);'
1509 `typedef void rl_vcpfunc_t (char *);'
1511 `typedef void rl_vcppfunc_t (char **);'
1514 File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions
1516 2.2.2 Writing a New Function
1517 ----------------------------
1519 In order to write new functions for Readline, you need to know the
1520 calling conventions for keyboard-invoked functions, and the names of the
1521 variables that describe the current state of the line read so far.
1523 The calling sequence for a command `foo' looks like
1525 `int foo (int count, int key)'
1527 where COUNT is the numeric argument (or 1 if defaulted) and KEY is the
1528 key that invoked this function.
1530 It is completely up to the function as to what should be done with
1531 the numeric argument. Some functions use it as a repeat count, some as
1532 a flag, and others to choose alternate behavior (refreshing the current
1533 line as opposed to refreshing the screen, for example). Some choose to
1534 ignore it. In general, if a function uses the numeric argument as a
1535 repeat count, it should be able to do something useful with both
1536 negative and positive arguments. At the very least, it should be aware
1537 that it can be passed a negative argument.
1539 A command function should return 0 if its action completes
1540 successfully, and a non-zero value if some error occurs. This is the
1541 convention obeyed by all of the builtin Readline bindable command
1545 File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline
1547 2.3 Readline Variables
1548 ======================
1550 These variables are available to function writers.
1552 -- Variable: char * rl_line_buffer
1553 This is the line gathered so far. You are welcome to modify the
1554 contents of the line, but see *Note Allowing Undoing::. The
1555 function `rl_extend_line_buffer' is available to increase the
1556 memory allocated to `rl_line_buffer'.
1558 -- Variable: int rl_point
1559 The offset of the current cursor position in `rl_line_buffer' (the
1562 -- Variable: int rl_end
1563 The number of characters present in `rl_line_buffer'. When
1564 `rl_point' is at the end of the line, `rl_point' and `rl_end' are
1567 -- Variable: int rl_mark
1568 The MARK (saved position) in the current line. If set, the mark
1569 and point define a _region_.
1571 -- Variable: int rl_done
1572 Setting this to a non-zero value causes Readline to return the
1573 current line immediately.
1575 -- Variable: int rl_num_chars_to_read
1576 Setting this to a positive value before calling `readline()' causes
1577 Readline to return after accepting that many characters, rather
1578 than reading up to a character bound to `accept-line'.
1580 -- Variable: int rl_pending_input
1581 Setting this to a value makes it the next keystroke read. This is
1582 a way to stuff a single character into the input stream.
1584 -- Variable: int rl_dispatching
1585 Set to a non-zero value if a function is being called from a key
1586 binding; zero otherwise. Application functions can test this to
1587 discover whether they were called directly or by Readline's
1588 dispatching mechanism.
1590 -- Variable: int rl_erase_empty_line
1591 Setting this to a non-zero value causes Readline to completely
1592 erase the current line, including any prompt, any time a newline
1593 is typed as the only character on an otherwise-empty line. The
1594 cursor is moved to the beginning of the newly-blank line.
1596 -- Variable: char * rl_prompt
1597 The prompt Readline uses. This is set from the argument to
1598 `readline()', and should not be assigned to directly. The
1599 `rl_set_prompt()' function (*note Redisplay::) may be used to
1600 modify the prompt string after calling `readline()'.
1602 -- Variable: int rl_already_prompted
1603 If an application wishes to display the prompt itself, rather than
1604 have Readline do it the first time `readline()' is called, it
1605 should set this variable to a non-zero value after displaying the
1606 prompt. The prompt must also be passed as the argument to
1607 `readline()' so the redisplay functions can update the display
1608 properly. The calling application is responsible for managing the
1609 value; Readline never sets it.
1611 -- Variable: const char * rl_library_version
1612 The version number of this revision of the library.
1614 -- Variable: int rl_readline_version
1615 An integer encoding the current version of the library. The
1616 encoding is of the form 0xMMMM, where MM is the two-digit major
1617 version number, and MM is the two-digit minor version number. For
1618 example, for Readline-4.2, `rl_readline_version' would have the
1621 -- Variable: int rl_gnu_readline_p
1622 Always set to 1, denoting that this is GNU readline rather than
1625 -- Variable: const char * rl_terminal_name
1626 The terminal type, used for initialization. If not set by the
1627 application, Readline sets this to the value of the `TERM'
1628 environment variable the first time it is called.
1630 -- Variable: const char * rl_readline_name
1631 This variable is set to a unique name by each application using
1632 Readline. The value allows conditional parsing of the inputrc file
1633 (*note Conditional Init Constructs::).
1635 -- Variable: FILE * rl_instream
1636 The stdio stream from which Readline reads input. If `NULL',
1637 Readline defaults to STDIN.
1639 -- Variable: FILE * rl_outstream
1640 The stdio stream to which Readline performs output. If `NULL',
1641 Readline defaults to STDOUT.
1643 -- Variable: int rl_prefer_env_winsize
1644 If non-zero, Readline gives values found in the `LINES' and
1645 `COLUMNS' environment variables greater precedence than values
1646 fetched from the kernel when computing the screen dimensions.
1648 -- Variable: rl_command_func_t * rl_last_func
1649 The address of the last command function Readline executed. May
1650 be used to test whether or not a function is being executed twice
1651 in succession, for example.
1653 -- Variable: rl_hook_func_t * rl_startup_hook
1654 If non-zero, this is the address of a function to call just before
1655 `readline' prints the first prompt.
1657 -- Variable: rl_hook_func_t * rl_pre_input_hook
1658 If non-zero, this is the address of a function to call after the
1659 first prompt has been printed and just before `readline' starts
1660 reading input characters.
1662 -- Variable: rl_hook_func_t * rl_event_hook
1663 If non-zero, this is the address of a function to call periodically
1664 when Readline is waiting for terminal input. By default, this
1665 will be called at most ten times a second if there is no keyboard
1668 -- Variable: rl_getc_func_t * rl_getc_function
1669 If non-zero, Readline will call indirectly through this pointer to
1670 get a character from the input stream. By default, it is set to
1671 `rl_getc', the default Readline character input function (*note
1674 -- Variable: rl_voidfunc_t * rl_redisplay_function
1675 If non-zero, Readline will call indirectly through this pointer to
1676 update the display with the current contents of the editing buffer.
1677 By default, it is set to `rl_redisplay', the default Readline
1678 redisplay function (*note Redisplay::).
1680 -- Variable: rl_vintfunc_t * rl_prep_term_function
1681 If non-zero, Readline will call indirectly through this pointer to
1682 initialize the terminal. The function takes a single argument, an
1683 `int' flag that says whether or not to use eight-bit characters.
1684 By default, this is set to `rl_prep_terminal' (*note Terminal
1687 -- Variable: rl_voidfunc_t * rl_deprep_term_function
1688 If non-zero, Readline will call indirectly through this pointer to
1689 reset the terminal. This function should undo the effects of
1690 `rl_prep_term_function'. By default, this is set to
1691 `rl_deprep_terminal' (*note Terminal Management::).
1693 -- Variable: Keymap rl_executing_keymap
1694 This variable is set to the keymap (*note Keymaps::) in which the
1695 currently executing readline function was found.
1697 -- Variable: Keymap rl_binding_keymap
1698 This variable is set to the keymap (*note Keymaps::) in which the
1699 last key binding occurred.
1701 -- Variable: char * rl_executing_macro
1702 This variable is set to the text of any currently-executing macro.
1704 -- Variable: int rl_readline_state
1705 A variable with bit values that encapsulate the current Readline
1706 state. A bit is set with the `RL_SETSTATE' macro, and unset with
1707 the `RL_UNSETSTATE' macro. Use the `RL_ISSTATE' macro to test
1708 whether a particular state bit is set. Current state bits include:
1711 Readline has not yet been called, nor has it begun to
1714 `RL_STATE_INITIALIZING'
1715 Readline is initializing its internal data structures.
1717 `RL_STATE_INITIALIZED'
1718 Readline has completed its initialization.
1720 `RL_STATE_TERMPREPPED'
1721 Readline has modified the terminal modes to do its own input
1725 Readline is reading a command from the keyboard.
1728 Readline is reading more input after reading the meta-prefix
1731 `RL_STATE_DISPATCHING'
1732 Readline is dispatching to a command.
1734 `RL_STATE_MOREINPUT'
1735 Readline is reading more input while executing an editing
1739 Readline is performing an incremental history search.
1742 Readline is performing a non-incremental history search.
1745 Readline is searching backward or forward through the history
1748 `RL_STATE_NUMERICARG'
1749 Readline is reading a numeric argument.
1751 `RL_STATE_MACROINPUT'
1752 Readline is currently getting its input from a
1753 previously-defined keyboard macro.
1756 Readline is currently reading characters defining a keyboard
1759 `RL_STATE_OVERWRITE'
1760 Readline is in overwrite mode.
1762 `RL_STATE_COMPLETING'
1763 Readline is performing word completion.
1765 `RL_STATE_SIGHANDLER'
1766 Readline is currently executing the readline signal handler.
1769 Readline is performing an undo.
1772 Readline has read a key sequence bound to `accept-line' and
1773 is about to return the line to the caller.
1776 -- Variable: int rl_explicit_arg
1777 Set to a non-zero value if an explicit numeric argument was
1778 specified by the user. Only valid in a bindable command function.
1780 -- Variable: int rl_numeric_arg
1781 Set to the value of any numeric argument explicitly specified by
1782 the user before executing the current Readline function. Only
1783 valid in a bindable command function.
1785 -- Variable: int rl_editing_mode
1786 Set to a value denoting Readline's current editing mode. A value
1787 of 1 means Readline is currently in emacs mode; 0 means that vi
1791 File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline
1793 2.4 Readline Convenience Functions
1794 ==================================
1798 * Function Naming:: How to give a function you write a name.
1799 * Keymaps:: Making keymaps.
1800 * Binding Keys:: Changing Keymaps.
1801 * Associating Function Names and Bindings:: Translate function names to
1803 * Allowing Undoing:: How to make your functions undoable.
1804 * Redisplay:: Functions to control line display.
1805 * Modifying Text:: Functions to modify `rl_line_buffer'.
1806 * Character Input:: Functions to read keyboard input.
1807 * Terminal Management:: Functions to manage terminal settings.
1808 * Utility Functions:: Generally useful functions and hooks.
1809 * Miscellaneous Functions:: Functions that don't fall into any category.
1810 * Alternate Interface:: Using Readline in a `callback' fashion.
1811 * A Readline Example:: An example Readline function.
1814 File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions
1816 2.4.1 Naming a Function
1817 -----------------------
1819 The user can dynamically change the bindings of keys while using
1820 Readline. This is done by representing the function with a descriptive
1821 name. The user is able to type the descriptive name when referring to
1822 the function. Thus, in an init file, one might find
1824 Meta-Rubout: backward-kill-word
1826 This binds the keystroke <Meta-Rubout> to the function
1827 _descriptively_ named `backward-kill-word'. You, as the programmer,
1828 should bind the functions you write to descriptive names as well.
1829 Readline provides a function for doing that:
1831 -- Function: int rl_add_defun (const char *name, rl_command_func_t
1833 Add NAME to the list of named functions. Make FUNCTION be the
1834 function that gets called. If KEY is not -1, then bind it to
1835 FUNCTION using `rl_bind_key()'.
1837 Using this function alone is sufficient for most applications. It
1838 is the recommended way to add a few functions to the default functions
1839 that Readline has built in. If you need to do something other than
1840 adding a function to Readline, you may need to use the underlying
1841 functions described below.
1844 File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions
1846 2.4.2 Selecting a Keymap
1847 ------------------------
1849 Key bindings take place on a "keymap". The keymap is the association
1850 between the keys that the user types and the functions that get run.
1851 You can make your own keymaps, copy existing keymaps, and tell Readline
1852 which keymap to use.
1854 -- Function: Keymap rl_make_bare_keymap (void)
1855 Returns a new, empty keymap. The space for the keymap is
1856 allocated with `malloc()'; the caller should free it by calling
1857 `rl_discard_keymap()' when done.
1859 -- Function: Keymap rl_copy_keymap (Keymap map)
1860 Return a new keymap which is a copy of MAP.
1862 -- Function: Keymap rl_make_keymap (void)
1863 Return a new keymap with the printing characters bound to
1864 rl_insert, the lowercase Meta characters bound to run their
1865 equivalents, and the Meta digits bound to produce numeric
1868 -- Function: void rl_discard_keymap (Keymap keymap)
1869 Free the storage associated with KEYMAP.
1871 Readline has several internal keymaps. These functions allow you to
1872 change which keymap is active.
1874 -- Function: Keymap rl_get_keymap (void)
1875 Returns the currently active keymap.
1877 -- Function: void rl_set_keymap (Keymap keymap)
1878 Makes KEYMAP the currently active keymap.
1880 -- Function: Keymap rl_get_keymap_by_name (const char *name)
1881 Return the keymap matching NAME. NAME is one which would be
1882 supplied in a `set keymap' inputrc line (*note Readline Init
1885 -- Function: char * rl_get_keymap_name (Keymap keymap)
1886 Return the name matching KEYMAP. NAME is one which would be
1887 supplied in a `set keymap' inputrc line (*note Readline Init
1891 File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions
1896 Key sequences are associate with functions through the keymap.
1897 Readline has several internal keymaps: `emacs_standard_keymap',
1898 `emacs_meta_keymap', `emacs_ctlx_keymap', `vi_movement_keymap', and
1899 `vi_insertion_keymap'. `emacs_standard_keymap' is the default, and the
1900 examples in this manual assume that.
1902 Since `readline()' installs a set of default key bindings the first
1903 time it is called, there is always the danger that a custom binding
1904 installed before the first call to `readline()' will be overridden. An
1905 alternate mechanism is to install custom key bindings in an
1906 initialization function assigned to the `rl_startup_hook' variable
1907 (*note Readline Variables::).
1909 These functions manage key bindings.
1911 -- Function: int rl_bind_key (int key, rl_command_func_t *function)
1912 Binds KEY to FUNCTION in the currently active keymap. Returns
1913 non-zero in the case of an invalid KEY.
1915 -- Function: int rl_bind_key_in_map (int key, rl_command_func_t
1916 *function, Keymap map)
1917 Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an
1920 -- Function: int rl_bind_key_if_unbound (int key, rl_command_func_t
1922 Binds KEY to FUNCTION if it is not already bound in the currently
1923 active keymap. Returns non-zero in the case of an invalid KEY or
1924 if KEY is already bound.
1926 -- Function: int rl_bind_key_if_unbound_in_map (int key,
1927 rl_command_func_t *function, Keymap map)
1928 Binds KEY to FUNCTION if it is not already bound in MAP. Returns
1929 non-zero in the case of an invalid KEY or if KEY is already bound.
1931 -- Function: int rl_unbind_key (int key)
1932 Bind KEY to the null function in the currently active keymap.
1933 Returns non-zero in case of error.
1935 -- Function: int rl_unbind_key_in_map (int key, Keymap map)
1936 Bind KEY to the null function in MAP. Returns non-zero in case of
1939 -- Function: int rl_unbind_function_in_map (rl_command_func_t
1940 *function, Keymap map)
1941 Unbind all keys that execute FUNCTION in MAP.
1943 -- Function: int rl_unbind_command_in_map (const char *command, Keymap
1945 Unbind all keys that are bound to COMMAND in MAP.
1947 -- Function: int rl_bind_keyseq (const char *keyseq, rl_command_func_t
1949 Bind the key sequence represented by the string KEYSEQ to the
1950 function FUNCTION, beginning in the current keymap. This makes
1951 new keymaps as necessary. The return value is non-zero if KEYSEQ
1954 -- Function: int rl_bind_keyseq_in_map (const char *keyseq,
1955 rl_command_func_t *function, Keymap map)
1956 Bind the key sequence represented by the string KEYSEQ to the
1957 function FUNCTION. This makes new keymaps as necessary. Initial
1958 bindings are performed in MAP. The return value is non-zero if
1961 -- Function: int rl_set_key (const char *keyseq, rl_command_func_t
1962 *function, Keymap map)
1963 Equivalent to `rl_bind_keyseq_in_map'.
1965 -- Function: int rl_bind_keyseq_if_unbound (const char *keyseq,
1966 rl_command_func_t *function)
1967 Binds KEYSEQ to FUNCTION if it is not already bound in the
1968 currently active keymap. Returns non-zero in the case of an
1969 invalid KEYSEQ or if KEYSEQ is already bound.
1971 -- Function: int rl_bind_keyseq_if_unbound_in_map (const char *keyseq,
1972 rl_command_func_t *function, Keymap map)
1973 Binds KEYSEQ to FUNCTION if it is not already bound in MAP.
1974 Returns non-zero in the case of an invalid KEYSEQ or if KEYSEQ is
1977 -- Function: int rl_generic_bind (int type, const char *keyseq, char
1979 Bind the key sequence represented by the string KEYSEQ to the
1980 arbitrary pointer DATA. TYPE says what kind of data is pointed to
1981 by DATA; this can be a function (`ISFUNC'), a macro (`ISMACR'), or
1982 a keymap (`ISKMAP'). This makes new keymaps as necessary. The
1983 initial keymap in which to do bindings is MAP.
1985 -- Function: int rl_parse_and_bind (char *line)
1986 Parse LINE as if it had been read from the `inputrc' file and
1987 perform any key bindings and variable assignments found (*note
1988 Readline Init File::).
1990 -- Function: int rl_read_init_file (const char *filename)
1991 Read keybindings and variable assignments from FILENAME (*note
1992 Readline Init File::).
1995 File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions
1997 2.4.4 Associating Function Names and Bindings
1998 ---------------------------------------------
2000 These functions allow you to find out what keys invoke named functions
2001 and the functions invoked by a particular key sequence. You may also
2002 associate a new function name with an arbitrary function.
2004 -- Function: rl_command_func_t * rl_named_function (const char *name)
2005 Return the function with name NAME.
2007 -- Function: rl_command_func_t * rl_function_of_keyseq (const char
2008 *keyseq, Keymap map, int *type)
2009 Return the function invoked by KEYSEQ in keymap MAP. If MAP is
2010 `NULL', the current keymap is used. If TYPE is not `NULL', the
2011 type of the object is returned in the `int' variable it points to
2012 (one of `ISFUNC', `ISKMAP', or `ISMACR').
2014 -- Function: char ** rl_invoking_keyseqs (rl_command_func_t *function)
2015 Return an array of strings representing the key sequences used to
2016 invoke FUNCTION in the current keymap.
2018 -- Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t
2019 *function, Keymap map)
2020 Return an array of strings representing the key sequences used to
2021 invoke FUNCTION in the keymap MAP.
2023 -- Function: void rl_function_dumper (int readable)
2024 Print the readline function names and the key sequences currently
2025 bound to them to `rl_outstream'. If READABLE is non-zero, the
2026 list is formatted in such a way that it can be made part of an
2027 `inputrc' file and re-read.
2029 -- Function: void rl_list_funmap_names (void)
2030 Print the names of all bindable Readline functions to
2033 -- Function: const char ** rl_funmap_names (void)
2034 Return a NULL terminated array of known function names. The array
2035 is sorted. The array itself is allocated, but not the strings
2036 inside. You should `free()' the array when you are done, but not
2039 -- Function: int rl_add_funmap_entry (const char *name,
2040 rl_command_func_t *function)
2041 Add NAME to the list of bindable Readline command names, and make
2042 FUNCTION the function to be called when NAME is invoked.
2045 File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions
2047 2.4.5 Allowing Undoing
2048 ----------------------
2050 Supporting the undo command is a painless thing, and makes your
2051 functions much more useful. It is certainly easy to try something if
2052 you know you can undo it.
2054 If your function simply inserts text once, or deletes text once, and
2055 uses `rl_insert_text()' or `rl_delete_text()' to do it, then undoing is
2056 already done for you automatically.
2058 If you do multiple insertions or multiple deletions, or any
2059 combination of these operations, you should group them together into
2060 one operation. This is done with `rl_begin_undo_group()' and
2061 `rl_end_undo_group()'.
2063 The types of events that can be undone are:
2065 enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
2067 Notice that `UNDO_DELETE' means to insert some text, and
2068 `UNDO_INSERT' means to delete some text. That is, the undo code tells
2069 what to undo, not how to undo it. `UNDO_BEGIN' and `UNDO_END' are tags
2070 added by `rl_begin_undo_group()' and `rl_end_undo_group()'.
2072 -- Function: int rl_begin_undo_group (void)
2073 Begins saving undo information in a group construct. The undo
2074 information usually comes from calls to `rl_insert_text()' and
2075 `rl_delete_text()', but could be the result of calls to
2078 -- Function: int rl_end_undo_group (void)
2079 Closes the current undo group started with `rl_begin_undo_group
2080 ()'. There should be one call to `rl_end_undo_group()' for each
2081 call to `rl_begin_undo_group()'.
2083 -- Function: void rl_add_undo (enum undo_code what, int start, int
2085 Remember how to undo an event (according to WHAT). The affected
2086 text runs from START to END, and encompasses TEXT.
2088 -- Function: void rl_free_undo_list (void)
2089 Free the existing undo list.
2091 -- Function: int rl_do_undo (void)
2092 Undo the first thing on the undo list. Returns `0' if there was
2093 nothing to undo, non-zero if something was undone.
2095 Finally, if you neither insert nor delete text, but directly modify
2096 the existing text (e.g., change its case), call `rl_modifying()' once,
2097 just before you modify the text. You must supply the indices of the
2098 text range that you are going to modify.
2100 -- Function: int rl_modifying (int start, int end)
2101 Tell Readline to save the text between START and END as a single
2102 undo unit. It is assumed that you will subsequently modify that
2106 File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions
2111 -- Function: void rl_redisplay (void)
2112 Change what's displayed on the screen to reflect the current
2113 contents of `rl_line_buffer'.
2115 -- Function: int rl_forced_update_display (void)
2116 Force the line to be updated and redisplayed, whether or not
2117 Readline thinks the screen display is correct.
2119 -- Function: int rl_on_new_line (void)
2120 Tell the update functions that we have moved onto a new (empty)
2121 line, usually after ouputting a newline.
2123 -- Function: int rl_on_new_line_with_prompt (void)
2124 Tell the update functions that we have moved onto a new line, with
2125 RL_PROMPT already displayed. This could be used by applications
2126 that want to output the prompt string themselves, but still need
2127 Readline to know the prompt string length for redisplay. It
2128 should be used after setting RL_ALREADY_PROMPTED.
2130 -- Function: int rl_reset_line_state (void)
2131 Reset the display state to a clean state and redisplay the current
2132 line starting on a new line.
2134 -- Function: int rl_crlf (void)
2135 Move the cursor to the start of the next screen line.
2137 -- Function: int rl_show_char (int c)
2138 Display character C on `rl_outstream'. If Readline has not been
2139 set to display meta characters directly, this will convert meta
2140 characters to a meta-prefixed key sequence. This is intended for
2141 use by applications which wish to do their own redisplay.
2143 -- Function: int rl_message (const char *, ...)
2144 The arguments are a format string as would be supplied to `printf',
2145 possibly containing conversion specifications such as `%d', and
2146 any additional arguments necessary to satisfy the conversion
2147 specifications. The resulting string is displayed in the "echo
2148 area". The echo area is also used to display numeric arguments
2149 and search strings. You should call `rl_save_prompt' to save the
2150 prompt information before calling this function.
2152 -- Function: int rl_clear_message (void)
2153 Clear the message in the echo area. If the prompt was saved with
2154 a call to `rl_save_prompt' before the last call to `rl_message',
2155 call `rl_restore_prompt' before calling this function.
2157 -- Function: void rl_save_prompt (void)
2158 Save the local Readline prompt display state in preparation for
2159 displaying a new message in the message area with `rl_message()'.
2161 -- Function: void rl_restore_prompt (void)
2162 Restore the local Readline prompt display state saved by the most
2163 recent call to `rl_save_prompt'. if `rl_save_prompt' was called
2164 to save the prompt before a call to `rl_message', this function
2165 should be called before the corresponding call to
2168 -- Function: int rl_expand_prompt (char *prompt)
2169 Expand any special character sequences in PROMPT and set up the
2170 local Readline prompt redisplay variables. This function is
2171 called by `readline()'. It may also be called to expand the
2172 primary prompt if the `rl_on_new_line_with_prompt()' function or
2173 `rl_already_prompted' variable is used. It returns the number of
2174 visible characters on the last line of the (possibly multi-line)
2175 prompt. Applications may indicate that the prompt contains
2176 characters that take up no physical screen space when displayed by
2177 bracketing a sequence of such characters with the special markers
2178 `RL_PROMPT_START_IGNORE' and `RL_PROMPT_END_IGNORE' (declared in
2179 `readline.h'. This may be used to embed terminal-specific escape
2180 sequences in prompts.
2182 -- Function: int rl_set_prompt (const char *prompt)
2183 Make Readline use PROMPT for subsequent redisplay. This calls
2184 `rl_expand_prompt()' to expand the prompt and sets `rl_prompt' to
2188 File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions
2190 2.4.7 Modifying Text
2191 --------------------
2193 -- Function: int rl_insert_text (const char *text)
2194 Insert TEXT into the line at the current cursor position. Returns
2195 the number of characters inserted.
2197 -- Function: int rl_delete_text (int start, int end)
2198 Delete the text between START and END in the current line.
2199 Returns the number of characters deleted.
2201 -- Function: char * rl_copy_text (int start, int end)
2202 Return a copy of the text between START and END in the current
2205 -- Function: int rl_kill_text (int start, int end)
2206 Copy the text between START and END in the current line to the
2207 kill ring, appending or prepending to the last kill if the last
2208 command was a kill command. The text is deleted. If START is
2209 less than END, the text is appended, otherwise prepended. If the
2210 last command was not a kill, a new kill ring slot is used.
2212 -- Function: int rl_push_macro_input (char *macro)
2213 Cause MACRO to be inserted into the line, as if it had been invoked
2214 by a key bound to a macro. Not especially useful; use
2215 `rl_insert_text()' instead.
2218 File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions
2220 2.4.8 Character Input
2221 ---------------------
2223 -- Function: int rl_read_key (void)
2224 Return the next character available from Readline's current input
2225 stream. This handles input inserted into the input stream via
2226 RL_PENDING_INPUT (*note Readline Variables::) and
2227 `rl_stuff_char()', macros, and characters read from the keyboard.
2228 While waiting for input, this function will call any function
2229 assigned to the `rl_event_hook' variable.
2231 -- Function: int rl_getc (FILE *stream)
2232 Return the next character available from STREAM, which is assumed
2235 -- Function: int rl_stuff_char (int c)
2236 Insert C into the Readline input stream. It will be "read" before
2237 Readline attempts to read characters from the terminal with
2238 `rl_read_key()'. Up to 512 characters may be pushed back.
2239 `rl_stuff_char' returns 1 if the character was successfully
2240 inserted; 0 otherwise.
2242 -- Function: int rl_execute_next (int c)
2243 Make C be the next command to be executed when `rl_read_key()' is
2244 called. This sets RL_PENDING_INPUT.
2246 -- Function: int rl_clear_pending_input (void)
2247 Unset RL_PENDING_INPUT, effectively negating the effect of any
2248 previous call to `rl_execute_next()'. This works only if the
2249 pending input has not already been read with `rl_read_key()'.
2251 -- Function: int rl_set_keyboard_input_timeout (int u)
2252 While waiting for keyboard input in `rl_read_key()', Readline will
2253 wait for U microseconds for input before calling any function
2254 assigned to `rl_event_hook'. The default waiting period is
2255 one-tenth of a second. Returns the old timeout value.
2258 File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions
2260 2.4.9 Terminal Management
2261 -------------------------
2263 -- Function: void rl_prep_terminal (int meta_flag)
2264 Modify the terminal settings for Readline's use, so `readline()'
2265 can read a single character at a time from the keyboard. The
2266 META_FLAG argument should be non-zero if Readline should read
2269 -- Function: void rl_deprep_terminal (void)
2270 Undo the effects of `rl_prep_terminal()', leaving the terminal in
2271 the state in which it was before the most recent call to
2272 `rl_prep_terminal()'.
2274 -- Function: void rl_tty_set_default_bindings (Keymap kmap)
2275 Read the operating system's terminal editing characters (as would
2276 be displayed by `stty') to their Readline equivalents. The
2277 bindings are performed in KMAP.
2279 -- Function: void rl_tty_unset_default_bindings (Keymap kmap)
2280 Reset the bindings manipulated by `rl_tty_set_default_bindings' so
2281 that the terminal editing characters are bound to `rl_insert'.
2282 The bindings are performed in KMAP.
2284 -- Function: int rl_reset_terminal (const char *terminal_name)
2285 Reinitialize Readline's idea of the terminal settings using
2286 TERMINAL_NAME as the terminal type (e.g., `vt100'). If
2287 TERMINAL_NAME is `NULL', the value of the `TERM' environment
2291 File: readline.info, Node: Utility Functions, Next: Miscellaneous Functions, Prev: Terminal Management, Up: Readline Convenience Functions
2293 2.4.10 Utility Functions
2294 ------------------------
2296 -- Function: void rl_replace_line (const char *text, int clear_undo)
2297 Replace the contents of `rl_line_buffer' with TEXT. The point and
2298 mark are preserved, if possible. If CLEAR_UNDO is non-zero, the
2299 undo list associated with the current line is cleared.
2301 -- Function: int rl_extend_line_buffer (int len)
2302 Ensure that `rl_line_buffer' has enough space to hold LEN
2303 characters, possibly reallocating it if necessary.
2305 -- Function: int rl_initialize (void)
2306 Initialize or re-initialize Readline's internal state. It's not
2307 strictly necessary to call this; `readline()' calls it before
2310 -- Function: int rl_ding (void)
2311 Ring the terminal bell, obeying the setting of `bell-style'.
2313 -- Function: int rl_alphabetic (int c)
2314 Return 1 if C is an alphabetic character.
2316 -- Function: void rl_display_match_list (char **matches, int len, int
2318 A convenience function for displaying a list of strings in
2319 columnar format on Readline's output stream. `matches' is the list
2320 of strings, in argv format, such as a list of completion matches.
2321 `len' is the number of strings in `matches', and `max' is the
2322 length of the longest string in `matches'. This function uses the
2323 setting of `print-completions-horizontally' to select how the
2324 matches are displayed (*note Readline Init File Syntax::).
2326 The following are implemented as macros, defined in `chardefs.h'.
2327 Applications should refrain from using them.
2329 -- Function: int _rl_uppercase_p (int c)
2330 Return 1 if C is an uppercase alphabetic character.
2332 -- Function: int _rl_lowercase_p (int c)
2333 Return 1 if C is a lowercase alphabetic character.
2335 -- Function: int _rl_digit_p (int c)
2336 Return 1 if C is a numeric character.
2338 -- Function: int _rl_to_upper (int c)
2339 If C is a lowercase alphabetic character, return the corresponding
2340 uppercase character.
2342 -- Function: int _rl_to_lower (int c)
2343 If C is an uppercase alphabetic character, return the corresponding
2344 lowercase character.
2346 -- Function: int _rl_digit_value (int c)
2347 If C is a number, return the value it represents.
2350 File: readline.info, Node: Miscellaneous Functions, Next: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions
2352 2.4.11 Miscellaneous Functions
2353 ------------------------------
2355 -- Function: int rl_macro_bind (const char *keyseq, const char *macro,
2357 Bind the key sequence KEYSEQ to invoke the macro MACRO. The
2358 binding is performed in MAP. When KEYSEQ is invoked, the MACRO
2359 will be inserted into the line. This function is deprecated; use
2360 `rl_generic_bind()' instead.
2362 -- Function: void rl_macro_dumper (int readable)
2363 Print the key sequences bound to macros and their values, using
2364 the current keymap, to `rl_outstream'. If READABLE is non-zero,
2365 the list is formatted in such a way that it can be made part of an
2366 `inputrc' file and re-read.
2368 -- Function: int rl_variable_bind (const char *variable, const char
2370 Make the Readline variable VARIABLE have VALUE. This behaves as
2371 if the readline command `set VARIABLE VALUE' had been executed in
2372 an `inputrc' file (*note Readline Init File Syntax::).
2374 -- Function: char * rl_variable_value (const char *variable)
2375 Return a string representing the value of the Readline variable
2376 VARIABLE. For boolean variables, this string is either `on' or
2379 -- Function: void rl_variable_dumper (int readable)
2380 Print the readline variable names and their current values to
2381 `rl_outstream'. If READABLE is non-zero, the list is formatted in
2382 such a way that it can be made part of an `inputrc' file and
2385 -- Function: int rl_set_paren_blink_timeout (int u)
2386 Set the time interval (in microseconds) that Readline waits when
2387 showing a balancing character when `blink-matching-paren' has been
2390 -- Function: char * rl_get_termcap (const char *cap)
2391 Retrieve the string value of the termcap capability CAP. Readline
2392 fetches the termcap entry for the current terminal name and uses
2393 those capabilities to move around the screen line and perform other
2394 terminal-specific operations, like erasing a line. Readline does
2395 not use all of a terminal's capabilities, and this function will
2396 return values for only those capabilities Readline uses.
2399 File: readline.info, Node: Alternate Interface, Next: A Readline Example, Prev: Miscellaneous Functions, Up: Readline Convenience Functions
2401 2.4.12 Alternate Interface
2402 --------------------------
2404 An alternate interface is available to plain `readline()'. Some
2405 applications need to interleave keyboard I/O with file, device, or
2406 window system I/O, typically by using a main loop to `select()' on
2407 various file descriptors. To accomodate this need, readline can also
2408 be invoked as a `callback' function from an event loop. There are
2409 functions available to make this easy.
2411 -- Function: void rl_callback_handler_install (const char *prompt,
2412 rl_vcpfunc_t *lhandler)
2413 Set up the terminal for readline I/O and display the initial
2414 expanded value of PROMPT. Save the value of LHANDLER to use as a
2415 function to call when a complete line of input has been entered.
2416 The function takes the text of the line as an argument.
2418 -- Function: void rl_callback_read_char (void)
2419 Whenever an application determines that keyboard input is
2420 available, it should call `rl_callback_read_char()', which will
2421 read the next character from the current input source. If that
2422 character completes the line, `rl_callback_read_char' will invoke
2423 the LHANDLER function saved by `rl_callback_handler_install' to
2424 process the line. Before calling the LHANDLER function, the
2425 terminal settings are reset to the values they had before calling
2426 `rl_callback_handler_install'. If the LHANDLER function returns,
2427 the terminal settings are modified for Readline's use again.
2428 `EOF' is indicated by calling LHANDLER with a `NULL' line.
2430 -- Function: void rl_callback_handler_remove (void)
2431 Restore the terminal to its initial state and remove the line
2432 handler. This may be called from within a callback as well as
2433 independently. If the LHANDLER installed by
2434 `rl_callback_handler_install' does not exit the program, either
2435 this function or the function referred to by the value of
2436 `rl_deprep_term_function' should be called before the program
2437 exits to reset the terminal settings.
2440 File: readline.info, Node: A Readline Example, Prev: Alternate Interface, Up: Readline Convenience Functions
2442 2.4.13 A Readline Example
2443 -------------------------
2445 Here is a function which changes lowercase characters to their uppercase
2446 equivalents, and uppercase characters to lowercase. If this function
2447 was bound to `M-c', then typing `M-c' would change the case of the
2448 character under point. Typing `M-1 0 M-c' would change the case of the
2449 following 10 characters, leaving the cursor on the last character
2452 /* Invert the case of the COUNT following characters. */
2454 invert_case_line (count, key)
2457 register int start, end, i;
2461 if (rl_point >= rl_end)
2472 /* Find the end of the range to modify. */
2473 end = start + (count * direction);
2475 /* Force it to be within range. */
2491 /* Tell readline that we are modifying the line,
2492 so it will save the undo information. */
2493 rl_modifying (start, end);
2495 for (i = start; i != end; i++)
2497 if (_rl_uppercase_p (rl_line_buffer[i]))
2498 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
2499 else if (_rl_lowercase_p (rl_line_buffer[i]))
2500 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
2502 /* Move point to on top of the last character changed. */
2503 rl_point = (direction == 1) ? end - 1 : start;
2508 File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline
2510 2.5 Readline Signal Handling
2511 ============================
2513 Signals are asynchronous events sent to a process by the Unix kernel,
2514 sometimes on behalf of another process. They are intended to indicate
2515 exceptional events, like a user pressing the interrupt key on his
2516 terminal, or a network connection being broken. There is a class of
2517 signals that can be sent to the process currently reading input from
2518 the keyboard. Since Readline changes the terminal attributes when it
2519 is called, it needs to perform special processing when such a signal is
2520 received in order to restore the terminal to a sane state, or provide
2521 application writers with functions to do so manually.
2523 Readline contains an internal signal handler that is installed for a
2524 number of signals (`SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM',
2525 `SIGTSTP', `SIGTTIN', and `SIGTTOU'). When one of these signals is
2526 received, the signal handler will reset the terminal attributes to
2527 those that were in effect before `readline()' was called, reset the
2528 signal handling to what it was before `readline()' was called, and
2529 resend the signal to the calling application. If and when the calling
2530 application's signal handler returns, Readline will reinitialize the
2531 terminal and continue to accept input. When a `SIGINT' is received,
2532 the Readline signal handler performs some additional work, which will
2533 cause any partially-entered line to be aborted (see the description of
2534 `rl_free_line_state()' below).
2536 There is an additional Readline signal handler, for `SIGWINCH', which
2537 the kernel sends to a process whenever the terminal's size changes (for
2538 example, if a user resizes an `xterm'). The Readline `SIGWINCH'
2539 handler updates Readline's internal screen size information, and then
2540 calls any `SIGWINCH' signal handler the calling application has
2541 installed. Readline calls the application's `SIGWINCH' signal handler
2542 without resetting the terminal to its original state. If the
2543 application's signal handler does more than update its idea of the
2544 terminal size and return (for example, a `longjmp' back to a main
2545 processing loop), it _must_ call `rl_cleanup_after_signal()' (described
2546 below), to restore the terminal state.
2548 Readline provides two variables that allow application writers to
2549 control whether or not it will catch certain signals and act on them
2550 when they are received. It is important that applications change the
2551 values of these variables only when calling `readline()', not in a
2552 signal handler, so Readline's internal signal state is not corrupted.
2554 -- Variable: int rl_catch_signals
2555 If this variable is non-zero, Readline will install signal
2556 handlers for `SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM', `SIGTSTP',
2557 `SIGTTIN', and `SIGTTOU'.
2559 The default value of `rl_catch_signals' is 1.
2561 -- Variable: int rl_catch_sigwinch
2562 If this variable is non-zero, Readline will install a signal
2563 handler for `SIGWINCH'.
2565 The default value of `rl_catch_sigwinch' is 1.
2567 If an application does not wish to have Readline catch any signals,
2568 or to handle signals other than those Readline catches (`SIGHUP', for
2569 example), Readline provides convenience functions to do the necessary
2570 terminal and internal state cleanup upon receipt of a signal.
2572 -- Function: void rl_cleanup_after_signal (void)
2573 This function will reset the state of the terminal to what it was
2574 before `readline()' was called, and remove the Readline signal
2575 handlers for all signals, depending on the values of
2576 `rl_catch_signals' and `rl_catch_sigwinch'.
2578 -- Function: void rl_free_line_state (void)
2579 This will free any partial state associated with the current input
2580 line (undo information, any partial history entry, any
2581 partially-entered keyboard macro, and any partially-entered
2582 numeric argument). This should be called before
2583 `rl_cleanup_after_signal()'. The Readline signal handler for
2584 `SIGINT' calls this to abort the current input line.
2586 -- Function: void rl_reset_after_signal (void)
2587 This will reinitialize the terminal and reinstall any Readline
2588 signal handlers, depending on the values of `rl_catch_signals' and
2589 `rl_catch_sigwinch'.
2591 If an application does not wish Readline to catch `SIGWINCH', it may
2592 call `rl_resize_terminal()' or `rl_set_screen_size()' to force Readline
2593 to update its idea of the terminal size when a `SIGWINCH' is received.
2595 -- Function: void rl_resize_terminal (void)
2596 Update Readline's internal screen size by reading values from the
2599 -- Function: void rl_set_screen_size (int rows, int cols)
2600 Set Readline's idea of the terminal size to ROWS rows and COLS
2601 columns. If either ROWS or COLUMNS is less than or equal to 0,
2602 Readline's idea of that terminal dimension is unchanged.
2604 If an application does not want to install a `SIGWINCH' handler, but
2605 is still interested in the screen dimensions, Readline's idea of the
2606 screen size may be queried.
2608 -- Function: void rl_get_screen_size (int *rows, int *cols)
2609 Return Readline's idea of the terminal's size in the variables
2610 pointed to by the arguments.
2612 -- Function: void rl_reset_screen_size (void)
2613 Cause Readline to reobtain the screen size and recalculate its
2616 The following functions install and remove Readline's signal
2619 -- Function: int rl_set_signals (void)
2620 Install Readline's signal handler for `SIGINT', `SIGQUIT',
2621 `SIGTERM', `SIGALRM', `SIGTSTP', `SIGTTIN', `SIGTTOU', and
2622 `SIGWINCH', depending on the values of `rl_catch_signals' and
2623 `rl_catch_sigwinch'.
2625 -- Function: int rl_clear_signals (void)
2626 Remove all of the Readline signal handlers installed by
2630 File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline
2632 2.6 Custom Completers
2633 =====================
2635 Typically, a program that reads commands from the user has a way of
2636 disambiguating commands and data. If your program is one of these, then
2637 it can provide completion for commands, data, or both. The following
2638 sections describe how your program and Readline cooperate to provide
2643 * How Completing Works:: The logic used to do completion.
2644 * Completion Functions:: Functions provided by Readline.
2645 * Completion Variables:: Variables which control completion.
2646 * A Short Completion Example:: An example of writing completer subroutines.
2649 File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers
2651 2.6.1 How Completing Works
2652 --------------------------
2654 In order to complete some text, the full list of possible completions
2655 must be available. That is, it is not possible to accurately expand a
2656 partial word without knowing all of the possible words which make sense
2657 in that context. The Readline library provides the user interface to
2658 completion, and two of the most common completion functions: filename
2659 and username. For completing other types of text, you must write your
2660 own completion function. This section describes exactly what such
2661 functions must do, and provides an example.
2663 There are three major functions used to perform completion:
2665 1. The user-interface function `rl_complete()'. This function is
2666 called with the same arguments as other bindable Readline
2667 functions: COUNT and INVOKING_KEY. It isolates the word to be
2668 completed and calls `rl_completion_matches()' to generate a list
2669 of possible completions. It then either lists the possible
2670 completions, inserts the possible completions, or actually
2671 performs the completion, depending on which behavior is desired.
2673 2. The internal function `rl_completion_matches()' uses an
2674 application-supplied "generator" function to generate the list of
2675 possible matches, and then returns the array of these matches.
2676 The caller should place the address of its generator function in
2677 `rl_completion_entry_function'.
2679 3. The generator function is called repeatedly from
2680 `rl_completion_matches()', returning a string each time. The
2681 arguments to the generator function are TEXT and STATE. TEXT is
2682 the partial word to be completed. STATE is zero the first time
2683 the function is called, allowing the generator to perform any
2684 necessary initialization, and a positive non-zero integer for each
2685 subsequent call. The generator function returns `(char *)NULL' to
2686 inform `rl_completion_matches()' that there are no more
2687 possibilities left. Usually the generator function computes the
2688 list of possible completions when STATE is zero, and returns them
2689 one at a time on subsequent calls. Each string the generator
2690 function returns as a match must be allocated with `malloc()';
2691 Readline frees the strings when it has finished with them. Such a
2692 generator function is referred to as an "application-specific
2693 completion function".
2696 -- Function: int rl_complete (int ignore, int invoking_key)
2697 Complete the word at or before point. You have supplied the
2698 function that does the initial simple matching selection algorithm
2699 (see `rl_completion_matches()'). The default is to do filename
2702 -- Variable: rl_compentry_func_t * rl_completion_entry_function
2703 This is a pointer to the generator function for
2704 `rl_completion_matches()'. If the value of
2705 `rl_completion_entry_function' is `NULL' then the default filename
2706 generator function, `rl_filename_completion_function()', is used.
2707 An "application-specific completion function" is a function whose
2708 address is assigned to `rl_completion_entry_function' and whose
2709 return values are used to generate possible completions.
2712 File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers
2714 2.6.2 Completion Functions
2715 --------------------------
2717 Here is the complete list of callable completion functions present in
2720 -- Function: int rl_complete_internal (int what_to_do)
2721 Complete the word at or before point. WHAT_TO_DO says what to do
2722 with the completion. A value of `?' means list the possible
2723 completions. `TAB' means do standard completion. `*' means
2724 insert all of the possible completions. `!' means to display all
2725 of the possible completions, if there is more than one, as well as
2726 performing partial completion. `@' is similar to `!', but
2727 possible completions are not listed if the possible completions
2728 share a common prefix.
2730 -- Function: int rl_complete (int ignore, int invoking_key)
2731 Complete the word at or before point. You have supplied the
2732 function that does the initial simple matching selection algorithm
2733 (see `rl_completion_matches()' and `rl_completion_entry_function').
2734 The default is to do filename completion. This calls
2735 `rl_complete_internal()' with an argument depending on
2738 -- Function: int rl_possible_completions (int count, int invoking_key)
2739 List the possible completions. See description of `rl_complete
2740 ()'. This calls `rl_complete_internal()' with an argument of `?'.
2742 -- Function: int rl_insert_completions (int count, int invoking_key)
2743 Insert the list of possible completions into the line, deleting the
2744 partially-completed word. See description of `rl_complete()'.
2745 This calls `rl_complete_internal()' with an argument of `*'.
2747 -- Function: int rl_completion_mode (rl_command_func_t *cfunc)
2748 Returns the apppriate value to pass to `rl_complete_internal()'
2749 depending on whether CFUNC was called twice in succession and the
2750 values of the `show-all-if-ambiguous' and `show-all-if-unmodified'
2751 variables. Application-specific completion functions may use this
2752 function to present the same interface as `rl_complete()'.
2754 -- Function: char ** rl_completion_matches (const char *text,
2755 rl_compentry_func_t *entry_func)
2756 Returns an array of strings which is a list of completions for
2757 TEXT. If there are no completions, returns `NULL'. The first
2758 entry in the returned array is the substitution for TEXT. The
2759 remaining entries are the possible completions. The array is
2760 terminated with a `NULL' pointer.
2762 ENTRY_FUNC is a function of two args, and returns a `char *'. The
2763 first argument is TEXT. The second is a state argument; it is
2764 zero on the first call, and non-zero on subsequent calls.
2765 ENTRY_FUNC returns a `NULL' pointer to the caller when there are
2768 -- Function: char * rl_filename_completion_function (const char *text,
2770 A generator function for filename completion in the general case.
2771 TEXT is a partial filename. The Bash source is a useful reference
2772 for writing application-specific completion functions (the Bash
2773 completion functions call this and other Readline functions).
2775 -- Function: char * rl_username_completion_function (const char *text,
2777 A completion generator for usernames. TEXT contains a partial
2778 username preceded by a random character (usually `~'). As with all
2779 completion generators, STATE is zero on the first call and non-zero
2780 for subsequent calls.
2783 File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers
2785 2.6.3 Completion Variables
2786 --------------------------
2788 -- Variable: rl_compentry_func_t * rl_completion_entry_function
2789 A pointer to the generator function for `rl_completion_matches()'.
2790 `NULL' means to use `rl_filename_completion_function()', the
2791 default filename completer.
2793 -- Variable: rl_completion_func_t * rl_attempted_completion_function
2794 A pointer to an alternative function to create matches. The
2795 function is called with TEXT, START, and END. START and END are
2796 indices in `rl_line_buffer' defining the boundaries of TEXT, which
2797 is a character string. If this function exists and returns
2798 `NULL', or if this variable is set to `NULL', then `rl_complete()'
2799 will call the value of `rl_completion_entry_function' to generate
2800 matches, otherwise the array of strings returned will be used. If
2801 this function sets the `rl_attempted_completion_over' variable to
2802 a non-zero value, Readline will not perform its default completion
2803 even if this function returns no matches.
2805 -- Variable: rl_quote_func_t * rl_filename_quoting_function
2806 A pointer to a function that will quote a filename in an
2807 application-specific fashion. This is called if filename
2808 completion is being attempted and one of the characters in
2809 `rl_filename_quote_characters' appears in a completed filename.
2810 The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER.
2811 The TEXT is the filename to be quoted. The MATCH_TYPE is either
2812 `SINGLE_MATCH', if there is only one completion match, or
2813 `MULT_MATCH'. Some functions use this to decide whether or not to
2814 insert a closing quote character. The QUOTE_POINTER is a pointer
2815 to any opening quote character the user typed. Some functions
2816 choose to reset this character.
2818 -- Variable: rl_dequote_func_t * rl_filename_dequoting_function
2819 A pointer to a function that will remove application-specific
2820 quoting characters from a filename before completion is attempted,
2821 so those characters do not interfere with matching the text
2822 against names in the filesystem. It is called with TEXT, the text
2823 of the word to be dequoted, and QUOTE_CHAR, which is the quoting
2824 character that delimits the filename (usually `'' or `"'). If
2825 QUOTE_CHAR is zero, the filename was not in an embedded string.
2827 -- Variable: rl_linebuf_func_t * rl_char_is_quoted_p
2828 A pointer to a function to call that determines whether or not a
2829 specific character in the line buffer is quoted, according to
2830 whatever quoting mechanism the program calling Readline uses. The
2831 function is called with two arguments: TEXT, the text of the line,
2832 and INDEX, the index of the character in the line. It is used to
2833 decide whether a character found in
2834 `rl_completer_word_break_characters' should be used to break words
2837 -- Variable: rl_compignore_func_t * rl_ignore_some_completions_function
2838 This function, if defined, is called by the completer when real
2839 filename completion is done, after all the matching names have
2840 been generated. It is passed a `NULL' terminated array of matches.
2841 The first element (`matches[0]') is the maximal substring common
2842 to all matches. This function can re-arrange the list of matches
2843 as required, but each element deleted from the array must be freed.
2845 -- Variable: rl_icppfunc_t * rl_directory_completion_hook
2846 This function, if defined, is allowed to modify the directory
2847 portion of filenames Readline completes. It is called with the
2848 address of a string (the current directory name) as an argument,
2849 and may modify that string. If the string is replaced with a new
2850 string, the old value should be freed. Any modified directory
2851 name should have a trailing slash. The modified value will be
2852 displayed as part of the completion, replacing the directory
2853 portion of the pathname the user typed. It returns an integer
2854 that should be non-zero if the function modifies its directory
2855 argument. It could be used to expand symbolic links or shell
2856 variables in pathnames.
2858 -- Variable: rl_compdisp_func_t * rl_completion_display_matches_hook
2859 If non-zero, then this is the address of a function to call when
2860 completing a word would normally display the list of possible
2861 matches. This function is called in lieu of Readline displaying
2862 the list. It takes three arguments: (`char **'MATCHES, `int'
2863 NUM_MATCHES, `int' MAX_LENGTH) where MATCHES is the array of
2864 matching strings, NUM_MATCHES is the number of strings in that
2865 array, and MAX_LENGTH is the length of the longest string in that
2866 array. Readline provides a convenience function,
2867 `rl_display_match_list', that takes care of doing the display to
2868 Readline's output stream. That function may be called from this
2871 -- Variable: const char * rl_basic_word_break_characters
2872 The basic list of characters that signal a break between words for
2873 the completer routine. The default value of this variable is the
2874 characters which break words for completion in Bash: `"
2875 \t\n\"\\'`@$><=;|&{("'.
2877 -- Variable: const char * rl_basic_quote_characters
2878 A list of quote characters which can cause a word break.
2880 -- Variable: const char * rl_completer_word_break_characters
2881 The list of characters that signal a break between words for
2882 `rl_complete_internal()'. The default list is the value of
2883 `rl_basic_word_break_characters'.
2885 -- Variable: rl_cpvfunc_t * rl_completion_word_break_hook
2886 If non-zero, this is the address of a function to call when
2887 Readline is deciding where to separate words for word completion.
2888 It should return a character string like
2889 `rl_completer_word_break_characters' to be used to perform the
2890 current completion. The function may choose to set
2891 `rl_completer_word_break_characters' itself. If the function
2892 returns `NULL', `rl_completer_word_break_characters' is used.
2894 -- Variable: const char * rl_completer_quote_characters
2895 A list of characters which can be used to quote a substring of the
2896 line. Completion occurs on the entire substring, and within the
2897 substring `rl_completer_word_break_characters' are treated as any
2898 other character, unless they also appear within this list.
2900 -- Variable: const char * rl_filename_quote_characters
2901 A list of characters that cause a filename to be quoted by the
2902 completer when they appear in a completed filename. The default
2905 -- Variable: const char * rl_special_prefixes
2906 The list of characters that are word break characters, but should
2907 be left in TEXT when it is passed to the completion function.
2908 Programs can use this to help determine what kind of completing to
2909 do. For instance, Bash sets this variable to "$@" so that it can
2910 complete shell variables and hostnames.
2912 -- Variable: int rl_completion_query_items
2913 Up to this many items will be displayed in response to a
2914 possible-completions call. After that, readline asks the user if
2915 she is sure she wants to see them all. The default value is 100.
2916 A negative value indicates that Readline should never ask the user.
2918 -- Variable: int rl_completion_append_character
2919 When a single completion alternative matches at the end of the
2920 command line, this character is appended to the inserted
2921 completion text. The default is a space character (` '). Setting
2922 this to the null character (`\0') prevents anything being appended
2923 automatically. This can be changed in application-specific
2924 completion functions to provide the "most sensible word separator
2925 character" according to an application-specific command line
2926 syntax specification.
2928 -- Variable: int rl_completion_suppress_append
2929 If non-zero, RL_COMPLETION_APPEND_CHARACTER is not appended to
2930 matches at the end of the command line, as described above. It is
2931 set to 0 before any application-specific completion function is
2932 called, and may only be changed within such a function.
2934 -- Variable: int rl_completion_quote_character
2935 When Readline is completing quoted text, as delimited by one of the
2936 characters in RL_COMPLETER_QUOTE_CHARACTERS, it sets this variable
2937 to the quoting character found. This is set before any
2938 application-specific completion function is called.
2940 -- Variable: int rl_completion_suppress_quote
2941 If non-zero, Readline does not append a matching quote character
2942 when performing completion on a quoted string. It is set to 0
2943 before any application-specific completion function is called, and
2944 may only be changed within such a function.
2946 -- Variable: int rl_completion_found_quote
2947 When Readline is completing quoted text, it sets this variable to
2948 a non-zero value if the word being completed contains or is
2949 delimited by any quoting characters, including backslashes. This
2950 is set before any application-specific completion function is
2953 -- Variable: int rl_completion_mark_symlink_dirs
2954 If non-zero, a slash will be appended to completed filenames that
2955 are symbolic links to directory names, subject to the value of the
2956 user-settable MARK-DIRECTORIES variable. This variable exists so
2957 that application-specific completion functions can override the
2958 user's global preference (set via the MARK-SYMLINKED-DIRECTORIES
2959 Readline variable) if appropriate. This variable is set to the
2960 user's preference before any application-specific completion
2961 function is called, so unless that function modifies the value,
2962 the user's preferences are honored.
2964 -- Variable: int rl_ignore_completion_duplicates
2965 If non-zero, then duplicates in the matches are removed. The
2968 -- Variable: int rl_filename_completion_desired
2969 Non-zero means that the results of the matches are to be treated as
2970 filenames. This is _always_ zero when completion is attempted,
2971 and can only be changed within an application-specific completion
2972 function. If it is set to a non-zero value by such a function,
2973 directory names have a slash appended and Readline attempts to
2974 quote completed filenames if they contain any characters in
2975 `rl_filename_quote_characters' and `rl_filename_quoting_desired'
2976 is set to a non-zero value.
2978 -- Variable: int rl_filename_quoting_desired
2979 Non-zero means that the results of the matches are to be quoted
2980 using double quotes (or an application-specific quoting mechanism)
2981 if the completed filename contains any characters in
2982 `rl_filename_quote_chars'. This is _always_ non-zero when
2983 completion is attempted, and can only be changed within an
2984 application-specific completion function. The quoting is effected
2985 via a call to the function pointed to by
2986 `rl_filename_quoting_function'.
2988 -- Variable: int rl_attempted_completion_over
2989 If an application-specific completion function assigned to
2990 `rl_attempted_completion_function' sets this variable to a non-zero
2991 value, Readline will not perform its default filename completion
2992 even if the application's completion function returns no matches.
2993 It should be set only by an application's completion function.
2995 -- Variable: int rl_completion_type
2996 Set to a character describing the type of completion Readline is
2997 currently attempting; see the description of
2998 `rl_complete_internal()' (*note Completion Functions::) for the
2999 list of characters. This is set to the appropriate value before
3000 any application-specific completion function is called, allowing
3001 such functions to present the same interface as `rl_complete()'.
3003 -- Variable: int rl_inhibit_completion
3004 If this variable is non-zero, completion is inhibited. The
3005 completion character will be inserted as any other bound to
3009 File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers
3011 2.6.4 A Short Completion Example
3012 --------------------------------
3014 Here is a small application demonstrating the use of the GNU Readline
3015 library. It is called `fileman', and the source code resides in
3016 `examples/fileman.c'. This sample application provides completion of
3017 command names, line editing features, and access to the history list.
3019 /* fileman.c -- A tiny application which demonstrates how to use the
3020 GNU Readline library. This application interactively allows users
3021 to manipulate files and their modes. */
3024 #include <sys/types.h>
3025 #include <sys/file.h>
3026 #include <sys/stat.h>
3027 #include <sys/errno.h>
3029 #include <readline/readline.h>
3030 #include <readline/history.h>
3032 extern char *xmalloc ();
3034 /* The names of functions that actually do the manipulation. */
3035 int com_list __P((char *));
3036 int com_view __P((char *));
3037 int com_rename __P((char *));
3038 int com_stat __P((char *));
3039 int com_pwd __P((char *));
3040 int com_delete __P((char *));
3041 int com_help __P((char *));
3042 int com_cd __P((char *));
3043 int com_quit __P((char *));
3045 /* A structure which contains information on the commands this program
3049 char *name; /* User printable name of the function. */
3050 rl_icpfunc_t *func; /* Function to call to do the job. */
3051 char *doc; /* Documentation for this function. */
3054 COMMAND commands[] = {
3055 { "cd", com_cd, "Change to directory DIR" },
3056 { "delete", com_delete, "Delete FILE" },
3057 { "help", com_help, "Display this text" },
3058 { "?", com_help, "Synonym for `help'" },
3059 { "list", com_list, "List files in DIR" },
3060 { "ls", com_list, "Synonym for `list'" },
3061 { "pwd", com_pwd, "Print the current working directory" },
3062 { "quit", com_quit, "Quit using Fileman" },
3063 { "rename", com_rename, "Rename FILE to NEWNAME" },
3064 { "stat", com_stat, "Print out statistics on FILE" },
3065 { "view", com_view, "View the contents of FILE" },
3066 { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL }
3069 /* Forward declarations. */
3070 char *stripwhite ();
3071 COMMAND *find_command ();
3073 /* The name of this program, as taken from argv[0]. */
3076 /* When non-zero, this means the user is done using this program. */
3085 r = xmalloc (strlen (s) + 1);
3098 initialize_readline (); /* Bind our completer. */
3100 /* Loop reading and executing lines until the user quits. */
3101 for ( ; done == 0; )
3103 line = readline ("FileMan: ");
3108 /* Remove leading and trailing whitespace from the line.
3109 Then, if there is anything left, add it to the history list
3111 s = stripwhite (line);
3124 /* Execute a command line. */
3133 /* Isolate the command word. */
3135 while (line[i] && whitespace (line[i]))
3139 while (line[i] && !whitespace (line[i]))
3145 command = find_command (word);
3149 fprintf (stderr, "%s: No such command for FileMan.\n", word);
3153 /* Get argument to command, if any. */
3154 while (whitespace (line[i]))
3159 /* Call the function. */
3160 return ((*(command->func)) (word));
3163 /* Look up NAME as the name of a command, and return a pointer to that
3164 command. Return a NULL pointer if NAME isn't a command name. */
3171 for (i = 0; commands[i].name; i++)
3172 if (strcmp (name, commands[i].name) == 0)
3173 return (&commands[i]);
3175 return ((COMMAND *)NULL);
3178 /* Strip whitespace from the start and end of STRING. Return a pointer
3184 register char *s, *t;
3186 for (s = string; whitespace (*s); s++)
3192 t = s + strlen (s) - 1;
3193 while (t > s && whitespace (*t))
3200 /* **************************************************************** */
3202 /* Interface to Readline Completion */
3204 /* **************************************************************** */
3206 char *command_generator __P((const char *, int));
3207 char **fileman_completion __P((const char *, int, int));
3209 /* Tell the GNU Readline library how to complete. We want to try to
3210 complete on command names if this is the first word in the line, or
3211 on filenames if not. */
3212 initialize_readline ()
3214 /* Allow conditional parsing of the ~/.inputrc file. */
3215 rl_readline_name = "FileMan";
3217 /* Tell the completer that we want a crack first. */
3218 rl_attempted_completion_function = fileman_completion;
3221 /* Attempt to complete on the contents of TEXT. START and END
3222 bound the region of rl_line_buffer that contains the word to
3223 complete. TEXT is the word to complete. We can use the entire
3224 contents of rl_line_buffer in case we want to do some simple
3225 parsing. Returnthe array of matches, or NULL if there aren't any. */
3227 fileman_completion (text, start, end)
3233 matches = (char **)NULL;
3235 /* If this word is at the start of the line, then it is a command
3236 to complete. Otherwise it is the name of a file in the current
3239 matches = rl_completion_matches (text, command_generator);
3244 /* Generator function for command completion. STATE lets us
3245 know whether to start from scratch; without any state
3246 (i.e. STATE == 0), then we start at the top of the list. */
3248 command_generator (text, state)
3252 static int list_index, len;
3255 /* If this is a new word to complete, initialize now. This
3256 includes saving the length of TEXT for efficiency, and
3257 initializing the index variable to 0. */
3261 len = strlen (text);
3264 /* Return the next name which partially matches from the
3266 while (name = commands[list_index].name)
3270 if (strncmp (name, text, len) == 0)
3271 return (dupstr(name));
3274 /* If no names matched, then return NULL. */
3275 return ((char *)NULL);
3278 /* **************************************************************** */
3280 /* FileMan Commands */
3282 /* **************************************************************** */
3284 /* String to pass to system (). This is for the LIST, VIEW and RENAME
3286 static char syscom[1024];
3288 /* List the file(s) named in arg. */
3295 sprintf (syscom, "ls -FClg %s", arg);
3296 return (system (syscom));
3302 if (!valid_argument ("view", arg))
3305 sprintf (syscom, "more %s", arg);
3306 return (system (syscom));
3312 too_dangerous ("rename");
3321 if (!valid_argument ("stat", arg))
3324 if (stat (arg, &finfo) == -1)
3330 printf ("Statistics for `%s':\n", arg);
3332 printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
3334 (finfo.st_nlink == 1) ? "" : "s",
3336 (finfo.st_size == 1) ? "" : "s");
3337 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
3338 printf (" Last access at: %s", ctime (&finfo.st_atime));
3339 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
3346 too_dangerous ("delete");
3350 /* Print out help for ARG, or for all of the commands if ARG is
3358 for (i = 0; commands[i].name; i++)
3360 if (!*arg || (strcmp (arg, commands[i].name) == 0))
3362 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
3369 printf ("No commands match `%s'. Possibilties are:\n", arg);
3371 for (i = 0; commands[i].name; i++)
3373 /* Print in six columns. */
3380 printf ("%s\t", commands[i].name);
3390 /* Change to the directory ARG. */
3394 if (chdir (arg) == -1)
3404 /* Print out the current working directory. */
3410 s = getcwd (dir, sizeof(dir) - 1);
3413 printf ("Error getting pwd: %s\n", dir);
3417 printf ("Current directory is %s\n", dir);
3421 /* The user wishes to quit using this program. Just set DONE
3430 /* Function which tells you that you can't do this. */
3431 too_dangerous (caller)
3435 "%s: Too dangerous for me to distribute.\n",
3437 fprintf (stderr, "Write it yourself.\n");
3440 /* Return non-zero if ARG is a valid argument for CALLER,
3441 else print an error message and return zero. */
3443 valid_argument (caller, arg)
3448 fprintf (stderr, "%s: Argument required.\n", caller);
3456 File: readline.info, Node: Copying This Manual, Next: Concept Index, Prev: Programming with GNU Readline, Up: Top
3458 Appendix A Copying This Manual
3459 ******************************
3463 * GNU Free Documentation License:: License for copying this manual.
3466 File: readline.info, Node: GNU Free Documentation License, Up: Copying This Manual
3468 A.1 GNU Free Documentation License
3469 ==================================
3471 Version 1.2, November 2002
3473 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
3474 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
3476 Everyone is permitted to copy and distribute verbatim copies
3477 of this license document, but changing it is not allowed.
3481 The purpose of this License is to make a manual, textbook, or other
3482 functional and useful document "free" in the sense of freedom: to
3483 assure everyone the effective freedom to copy and redistribute it,
3484 with or without modifying it, either commercially or
3485 noncommercially. Secondarily, this License preserves for the
3486 author and publisher a way to get credit for their work, while not
3487 being considered responsible for modifications made by others.
3489 This License is a kind of "copyleft", which means that derivative
3490 works of the document must themselves be free in the same sense.
3491 It complements the GNU General Public License, which is a copyleft
3492 license designed for free software.
3494 We have designed this License in order to use it for manuals for
3495 free software, because free software needs free documentation: a
3496 free program should come with manuals providing the same freedoms
3497 that the software does. But this License is not limited to
3498 software manuals; it can be used for any textual work, regardless
3499 of subject matter or whether it is published as a printed book.
3500 We recommend this License principally for works whose purpose is
3501 instruction or reference.
3503 1. APPLICABILITY AND DEFINITIONS
3505 This License applies to any manual or other work, in any medium,
3506 that contains a notice placed by the copyright holder saying it
3507 can be distributed under the terms of this License. Such a notice
3508 grants a world-wide, royalty-free license, unlimited in duration,
3509 to use that work under the conditions stated herein. The
3510 "Document", below, refers to any such manual or work. Any member
3511 of the public is a licensee, and is addressed as "you". You
3512 accept the license if you copy, modify or distribute the work in a
3513 way requiring permission under copyright law.
3515 A "Modified Version" of the Document means any work containing the
3516 Document or a portion of it, either copied verbatim, or with
3517 modifications and/or translated into another language.
3519 A "Secondary Section" is a named appendix or a front-matter section
3520 of the Document that deals exclusively with the relationship of the
3521 publishers or authors of the Document to the Document's overall
3522 subject (or to related matters) and contains nothing that could
3523 fall directly within that overall subject. (Thus, if the Document
3524 is in part a textbook of mathematics, a Secondary Section may not
3525 explain any mathematics.) The relationship could be a matter of
3526 historical connection with the subject or with related matters, or
3527 of legal, commercial, philosophical, ethical or political position
3530 The "Invariant Sections" are certain Secondary Sections whose
3531 titles are designated, as being those of Invariant Sections, in
3532 the notice that says that the Document is released under this
3533 License. If a section does not fit the above definition of
3534 Secondary then it is not allowed to be designated as Invariant.
3535 The Document may contain zero Invariant Sections. If the Document
3536 does not identify any Invariant Sections then there are none.
3538 The "Cover Texts" are certain short passages of text that are
3539 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
3540 that says that the Document is released under this License. A
3541 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
3542 be at most 25 words.
3544 A "Transparent" copy of the Document means a machine-readable copy,
3545 represented in a format whose specification is available to the
3546 general public, that is suitable for revising the document
3547 straightforwardly with generic text editors or (for images
3548 composed of pixels) generic paint programs or (for drawings) some
3549 widely available drawing editor, and that is suitable for input to
3550 text formatters or for automatic translation to a variety of
3551 formats suitable for input to text formatters. A copy made in an
3552 otherwise Transparent file format whose markup, or absence of
3553 markup, has been arranged to thwart or discourage subsequent
3554 modification by readers is not Transparent. An image format is
3555 not Transparent if used for any substantial amount of text. A
3556 copy that is not "Transparent" is called "Opaque".
3558 Examples of suitable formats for Transparent copies include plain
3559 ASCII without markup, Texinfo input format, LaTeX input format,
3560 SGML or XML using a publicly available DTD, and
3561 standard-conforming simple HTML, PostScript or PDF designed for
3562 human modification. Examples of transparent image formats include
3563 PNG, XCF and JPG. Opaque formats include proprietary formats that
3564 can be read and edited only by proprietary word processors, SGML or
3565 XML for which the DTD and/or processing tools are not generally
3566 available, and the machine-generated HTML, PostScript or PDF
3567 produced by some word processors for output purposes only.
3569 The "Title Page" means, for a printed book, the title page itself,
3570 plus such following pages as are needed to hold, legibly, the
3571 material this License requires to appear in the title page. For
3572 works in formats which do not have any title page as such, "Title
3573 Page" means the text near the most prominent appearance of the
3574 work's title, preceding the beginning of the body of the text.
3576 A section "Entitled XYZ" means a named subunit of the Document
3577 whose title either is precisely XYZ or contains XYZ in parentheses
3578 following text that translates XYZ in another language. (Here XYZ
3579 stands for a specific section name mentioned below, such as
3580 "Acknowledgements", "Dedications", "Endorsements", or "History".)
3581 To "Preserve the Title" of such a section when you modify the
3582 Document means that it remains a section "Entitled XYZ" according
3585 The Document may include Warranty Disclaimers next to the notice
3586 which states that this License applies to the Document. These
3587 Warranty Disclaimers are considered to be included by reference in
3588 this License, but only as regards disclaiming warranties: any other
3589 implication that these Warranty Disclaimers may have is void and
3590 has no effect on the meaning of this License.
3594 You may copy and distribute the Document in any medium, either
3595 commercially or noncommercially, provided that this License, the
3596 copyright notices, and the license notice saying this License
3597 applies to the Document are reproduced in all copies, and that you
3598 add no other conditions whatsoever to those of this License. You
3599 may not use technical measures to obstruct or control the reading
3600 or further copying of the copies you make or distribute. However,
3601 you may accept compensation in exchange for copies. If you
3602 distribute a large enough number of copies you must also follow
3603 the conditions in section 3.
3605 You may also lend copies, under the same conditions stated above,
3606 and you may publicly display copies.
3608 3. COPYING IN QUANTITY
3610 If you publish printed copies (or copies in media that commonly
3611 have printed covers) of the Document, numbering more than 100, and
3612 the Document's license notice requires Cover Texts, you must
3613 enclose the copies in covers that carry, clearly and legibly, all
3614 these Cover Texts: Front-Cover Texts on the front cover, and
3615 Back-Cover Texts on the back cover. Both covers must also clearly
3616 and legibly identify you as the publisher of these copies. The
3617 front cover must present the full title with all words of the
3618 title equally prominent and visible. You may add other material
3619 on the covers in addition. Copying with changes limited to the
3620 covers, as long as they preserve the title of the Document and
3621 satisfy these conditions, can be treated as verbatim copying in
3624 If the required texts for either cover are too voluminous to fit
3625 legibly, you should put the first ones listed (as many as fit
3626 reasonably) on the actual cover, and continue the rest onto
3629 If you publish or distribute Opaque copies of the Document
3630 numbering more than 100, you must either include a
3631 machine-readable Transparent copy along with each Opaque copy, or
3632 state in or with each Opaque copy a computer-network location from
3633 which the general network-using public has access to download
3634 using public-standard network protocols a complete Transparent
3635 copy of the Document, free of added material. If you use the
3636 latter option, you must take reasonably prudent steps, when you
3637 begin distribution of Opaque copies in quantity, to ensure that
3638 this Transparent copy will remain thus accessible at the stated
3639 location until at least one year after the last time you
3640 distribute an Opaque copy (directly or through your agents or
3641 retailers) of that edition to the public.
3643 It is requested, but not required, that you contact the authors of
3644 the Document well before redistributing any large number of
3645 copies, to give them a chance to provide you with an updated
3646 version of the Document.
3650 You may copy and distribute a Modified Version of the Document
3651 under the conditions of sections 2 and 3 above, provided that you
3652 release the Modified Version under precisely this License, with
3653 the Modified Version filling the role of the Document, thus
3654 licensing distribution and modification of the Modified Version to
3655 whoever possesses a copy of it. In addition, you must do these
3656 things in the Modified Version:
3658 A. Use in the Title Page (and on the covers, if any) a title
3659 distinct from that of the Document, and from those of
3660 previous versions (which should, if there were any, be listed
3661 in the History section of the Document). You may use the
3662 same title as a previous version if the original publisher of
3663 that version gives permission.
3665 B. List on the Title Page, as authors, one or more persons or
3666 entities responsible for authorship of the modifications in
3667 the Modified Version, together with at least five of the
3668 principal authors of the Document (all of its principal
3669 authors, if it has fewer than five), unless they release you
3670 from this requirement.
3672 C. State on the Title page the name of the publisher of the
3673 Modified Version, as the publisher.
3675 D. Preserve all the copyright notices of the Document.
3677 E. Add an appropriate copyright notice for your modifications
3678 adjacent to the other copyright notices.
3680 F. Include, immediately after the copyright notices, a license
3681 notice giving the public permission to use the Modified
3682 Version under the terms of this License, in the form shown in
3685 G. Preserve in that license notice the full lists of Invariant
3686 Sections and required Cover Texts given in the Document's
3689 H. Include an unaltered copy of this License.
3691 I. Preserve the section Entitled "History", Preserve its Title,
3692 and add to it an item stating at least the title, year, new
3693 authors, and publisher of the Modified Version as given on
3694 the Title Page. If there is no section Entitled "History" in
3695 the Document, create one stating the title, year, authors,
3696 and publisher of the Document as given on its Title Page,
3697 then add an item describing the Modified Version as stated in
3698 the previous sentence.
3700 J. Preserve the network location, if any, given in the Document
3701 for public access to a Transparent copy of the Document, and
3702 likewise the network locations given in the Document for
3703 previous versions it was based on. These may be placed in
3704 the "History" section. You may omit a network location for a
3705 work that was published at least four years before the
3706 Document itself, or if the original publisher of the version
3707 it refers to gives permission.
3709 K. For any section Entitled "Acknowledgements" or "Dedications",
3710 Preserve the Title of the section, and preserve in the
3711 section all the substance and tone of each of the contributor
3712 acknowledgements and/or dedications given therein.
3714 L. Preserve all the Invariant Sections of the Document,
3715 unaltered in their text and in their titles. Section numbers
3716 or the equivalent are not considered part of the section
3719 M. Delete any section Entitled "Endorsements". Such a section
3720 may not be included in the Modified Version.
3722 N. Do not retitle any existing section to be Entitled
3723 "Endorsements" or to conflict in title with any Invariant
3726 O. Preserve any Warranty Disclaimers.
3728 If the Modified Version includes new front-matter sections or
3729 appendices that qualify as Secondary Sections and contain no
3730 material copied from the Document, you may at your option
3731 designate some or all of these sections as invariant. To do this,
3732 add their titles to the list of Invariant Sections in the Modified
3733 Version's license notice. These titles must be distinct from any
3734 other section titles.
3736 You may add a section Entitled "Endorsements", provided it contains
3737 nothing but endorsements of your Modified Version by various
3738 parties--for example, statements of peer review or that the text
3739 has been approved by an organization as the authoritative
3740 definition of a standard.
3742 You may add a passage of up to five words as a Front-Cover Text,
3743 and a passage of up to 25 words as a Back-Cover Text, to the end
3744 of the list of Cover Texts in the Modified Version. Only one
3745 passage of Front-Cover Text and one of Back-Cover Text may be
3746 added by (or through arrangements made by) any one entity. If the
3747 Document already includes a cover text for the same cover,
3748 previously added by you or by arrangement made by the same entity
3749 you are acting on behalf of, you may not add another; but you may
3750 replace the old one, on explicit permission from the previous
3751 publisher that added the old one.
3753 The author(s) and publisher(s) of the Document do not by this
3754 License give permission to use their names for publicity for or to
3755 assert or imply endorsement of any Modified Version.
3757 5. COMBINING DOCUMENTS
3759 You may combine the Document with other documents released under
3760 this License, under the terms defined in section 4 above for
3761 modified versions, provided that you include in the combination
3762 all of the Invariant Sections of all of the original documents,
3763 unmodified, and list them all as Invariant Sections of your
3764 combined work in its license notice, and that you preserve all
3765 their Warranty Disclaimers.
3767 The combined work need only contain one copy of this License, and
3768 multiple identical Invariant Sections may be replaced with a single
3769 copy. If there are multiple Invariant Sections with the same name
3770 but different contents, make the title of each such section unique
3771 by adding at the end of it, in parentheses, the name of the
3772 original author or publisher of that section if known, or else a
3773 unique number. Make the same adjustment to the section titles in
3774 the list of Invariant Sections in the license notice of the
3777 In the combination, you must combine any sections Entitled
3778 "History" in the various original documents, forming one section
3779 Entitled "History"; likewise combine any sections Entitled
3780 "Acknowledgements", and any sections Entitled "Dedications". You
3781 must delete all sections Entitled "Endorsements."
3783 6. COLLECTIONS OF DOCUMENTS
3785 You may make a collection consisting of the Document and other
3786 documents released under this License, and replace the individual
3787 copies of this License in the various documents with a single copy
3788 that is included in the collection, provided that you follow the
3789 rules of this License for verbatim copying of each of the
3790 documents in all other respects.
3792 You may extract a single document from such a collection, and
3793 distribute it individually under this License, provided you insert
3794 a copy of this License into the extracted document, and follow
3795 this License in all other respects regarding verbatim copying of
3798 7. AGGREGATION WITH INDEPENDENT WORKS
3800 A compilation of the Document or its derivatives with other
3801 separate and independent documents or works, in or on a volume of
3802 a storage or distribution medium, is called an "aggregate" if the
3803 copyright resulting from the compilation is not used to limit the
3804 legal rights of the compilation's users beyond what the individual
3805 works permit. When the Document is included an aggregate, this
3806 License does not apply to the other works in the aggregate which
3807 are not themselves derivative works of the Document.
3809 If the Cover Text requirement of section 3 is applicable to these
3810 copies of the Document, then if the Document is less than one half
3811 of the entire aggregate, the Document's Cover Texts may be placed
3812 on covers that bracket the Document within the aggregate, or the
3813 electronic equivalent of covers if the Document is in electronic
3814 form. Otherwise they must appear on printed covers that bracket
3815 the whole aggregate.
3819 Translation is considered a kind of modification, so you may
3820 distribute translations of the Document under the terms of section
3821 4. Replacing Invariant Sections with translations requires special
3822 permission from their copyright holders, but you may include
3823 translations of some or all Invariant Sections in addition to the
3824 original versions of these Invariant Sections. You may include a
3825 translation of this License, and all the license notices in the
3826 Document, and any Warranty Disclaimers, provided that you also
3827 include the original English version of this License and the
3828 original versions of those notices and disclaimers. In case of a
3829 disagreement between the translation and the original version of
3830 this License or a notice or disclaimer, the original version will
3833 If a section in the Document is Entitled "Acknowledgements",
3834 "Dedications", or "History", the requirement (section 4) to
3835 Preserve its Title (section 1) will typically require changing the
3840 You may not copy, modify, sublicense, or distribute the Document
3841 except as expressly provided for under this License. Any other
3842 attempt to copy, modify, sublicense or distribute the Document is
3843 void, and will automatically terminate your rights under this
3844 License. However, parties who have received copies, or rights,
3845 from you under this License will not have their licenses
3846 terminated so long as such parties remain in full compliance.
3848 10. FUTURE REVISIONS OF THIS LICENSE
3850 The Free Software Foundation may publish new, revised versions of
3851 the GNU Free Documentation License from time to time. Such new
3852 versions will be similar in spirit to the present version, but may
3853 differ in detail to address new problems or concerns. See
3854 `http://www.gnu.org/copyleft/'.
3856 Each version of the License is given a distinguishing version
3857 number. If the Document specifies that a particular numbered
3858 version of this License "or any later version" applies to it, you
3859 have the option of following the terms and conditions either of
3860 that specified version or of any later version that has been
3861 published (not as a draft) by the Free Software Foundation. If
3862 the Document does not specify a version number of this License,
3863 you may choose any version ever published (not as a draft) by the
3864 Free Software Foundation.
3866 A.1.1 ADDENDUM: How to use this License for your documents
3867 ----------------------------------------------------------
3869 To use this License in a document you have written, include a copy of
3870 the License in the document and put the following copyright and license
3871 notices just after the title page:
3873 Copyright (C) YEAR YOUR NAME.
3874 Permission is granted to copy, distribute and/or modify this document
3875 under the terms of the GNU Free Documentation License, Version 1.2
3876 or any later version published by the Free Software Foundation;
3877 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
3878 A copy of the license is included in the section entitled ``GNU
3879 Free Documentation License''.
3881 If you have Invariant Sections, Front-Cover Texts and Back-Cover
3882 Texts, replace the "with...Texts." line with this:
3884 with the Invariant Sections being LIST THEIR TITLES, with
3885 the Front-Cover Texts being LIST, and with the Back-Cover Texts
3888 If you have Invariant Sections without Cover Texts, or some other
3889 combination of the three, merge those two alternatives to suit the
3892 If your document contains nontrivial examples of program code, we
3893 recommend releasing these examples in parallel under your choice of
3894 free software license, such as the GNU General Public License, to
3895 permit their use in free software.
3898 File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: Copying This Manual, Up: Top