1 @comment %**start of header (This is for running Texinfo on a region.)
2 @setfilename rltech.info
3 @comment %**end of header (This is for running Texinfo on a region.)
7 This document describes the GNU Readline Library, a utility for aiding
8 in the consitency of user interface across discrete programs that need
9 to provide a command line interface.
11 Copyright (C) 1988-2001 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 pare preserved on all copies.
18 Permission is granted to process this file through TeX and print the
19 results, provided the printed document carries copying permission
20 notice identical to this one except for the removal of this paragraph
21 (this paragraph not being relevant to the printed manual).
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided that the entire
26 resulting derived work is distributed under the terms of a permission
27 notice identical to this one.
29 Permission is granted to copy and distribute translations of this manual
30 into another language, under the above conditions for modified versions,
31 except that this permission notice may be stated in a translation approved
35 @node Programming with GNU Readline
36 @chapter Programming with GNU Readline
38 This chapter describes the interface between the @sc{gnu} Readline Library and
39 other programs. If you are a programmer, and you wish to include the
40 features found in @sc{gnu} Readline
41 such as completion, line editing, and interactive history manipulation
42 in your own programs, this section is for you.
45 * Basic Behavior:: Using the default behavior of Readline.
46 * Custom Functions:: Adding your own functions to Readline.
47 * Readline Variables:: Variables accessible to custom
49 * Readline Convenience Functions:: Functions which Readline supplies to
50 aid in writing your own custom
52 * Readline Signal Handling:: How Readline behaves when it receives signals.
53 * Custom Completers:: Supplanting or supplementing Readline's
58 @section Basic Behavior
60 Many programs provide a command line interface, such as @code{mail},
61 @code{ftp}, and @code{sh}. For such programs, the default behaviour of
62 Readline is sufficient. This section describes how to use Readline in
63 the simplest way possible, perhaps to replace calls in your code to
64 @code{gets()} or @code{fgets()}.
67 @cindex readline, function
69 The function @code{readline()} prints a prompt @var{prompt}
70 and then reads and returns a single line of text from the user.
71 If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
72 The line @code{readline} returns is allocated with @code{malloc()};
73 the caller should @code{free()} the line when it has finished with it.
74 The declaration for @code{readline} in ANSI C is
77 @code{char *readline (const char *@var{prompt});}
83 @code{char *line = readline ("Enter a line: ");}
86 in order to read a line of text from the user.
87 The line returned has the final newline removed, so only the
90 If @code{readline} encounters an @code{EOF} while reading the line, and the
91 line is empty at that point, then @code{(char *)NULL} is returned.
92 Otherwise, the line is ended just as if a newline had been typed.
94 If you want the user to be able to get at the line later, (with
95 @key{C-p} for example), you must call @code{add_history()} to save the
96 line away in a @dfn{history} list of such lines.
99 @code{add_history (line)};
103 For full details on the GNU History Library, see the associated manual.
105 It is preferable to avoid saving empty lines on the history list, since
106 users rarely have a burning need to reuse a blank line. Here is
107 a function which usefully replaces the standard @code{gets()} library
108 function, and has the advantage of no static buffer to overflow:
111 /* A static variable for holding the line. */
112 static char *line_read = (char *)NULL;
114 /* Read a string, and return a pointer to it. Returns NULL on EOF. */
118 /* If the buffer has already been allocated, return the memory
123 line_read = (char *)NULL;
126 /* Get a line from the user. */
127 line_read = readline ("");
129 /* If the line has any text in it, save it on the history. */
130 if (line_read && *line_read)
131 add_history (line_read);
137 This function gives the user the default behaviour of @key{TAB}
138 completion: completion on file names. If you do not want Readline to
139 complete on filenames, you can change the binding of the @key{TAB} key
140 with @code{rl_bind_key()}.
143 @code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
146 @code{rl_bind_key()} takes two arguments: @var{key} is the character that
147 you want to bind, and @var{function} is the address of the function to
148 call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()}
149 makes @key{TAB} insert itself.
150 @code{rl_bind_key()} returns non-zero if @var{key} is not a valid
151 ASCII character code (between 0 and 255).
153 Thus, to disable the default @key{TAB} behavior, the following suffices:
155 @code{rl_bind_key ('\t', rl_insert);}
158 This code should be executed once at the start of your program; you
159 might write a function called @code{initialize_readline()} which
160 performs this and other desired initializations, such as installing
161 custom completers (@pxref{Custom Completers}).
163 @node Custom Functions
164 @section Custom Functions
166 Readline provides many functions for manipulating the text of
167 the line, but it isn't possible to anticipate the needs of all
168 programs. This section describes the various functions and variables
169 defined within the Readline library which allow a user program to add
170 customized functionality to Readline.
172 Before declaring any functions that customize Readline's behavior, or
173 using any functionality Readline provides in other code, an
174 application writer should include the file @code{<readline/readline.h>}
175 in any file that uses Readline's features. Since some of the definitions
176 in @code{readline.h} use the @code{stdio} library, the file
177 @code{<stdio.h>} should be included before @code{readline.h}.
179 @code{readline.h} defines a C preprocessor variable that should
180 be treated as an integer, @code{RL_READLINE_VERSION}, which may
181 be used to conditionally compile application code depending on
182 the installed Readline version. The value is a hexadecimal
183 encoding of the major and minor version numbers of the library,
184 of the form 0x@var{MMmm}. @var{MM} is the two-digit major
185 version number; @var{mm} is the two-digit minor version number.
186 For Readline 4.2, for example, the value of
187 @code{RL_READLINE_VERSION} would be @code{0x0402}.
190 * Readline Typedefs:: C declarations to make code readable.
191 * Function Writing:: Variables and calling conventions.
194 @node Readline Typedefs
195 @subsection Readline Typedefs
197 For readabilty, we declare a number of new object types, all pointers
200 The reason for declaring these new types is to make it easier to write
201 code describing pointers to C functions with appropriately prototyped
202 arguments and return values.
204 For instance, say we want to declare a variable @var{func} as a pointer
205 to a function which takes two @code{int} arguments and returns an
206 @code{int} (this is the type of all of the Readline bindable functions).
207 Instead of the classic C declaration
209 @code{int (*func)();}
212 or the ANSI-C style declaration
214 @code{int (*func)(int, int);}
219 @code{rl_command_func_t *func;}
221 The full list of function pointer types available is
224 @item typedef int rl_command_func_t (int, int);
226 @item typedef char *rl_compentry_func_t (const char *, int);
228 @item typedef char **rl_completion_func_t (const char *, int, int);
230 @item typedef char *rl_quote_func_t (char *, int, char *);
232 @item typedef char *rl_dequote_func_t (char *, int);
234 @item typedef int rl_compignore_func_t (char **);
236 @item typedef void rl_compdisp_func_t (char **, int, int);
238 @item typedef int rl_hook_func_t (void);
240 @item typedef int rl_getc_func_t (FILE *);
242 @item typedef int rl_linebuf_func_t (char *, int);
244 @item typedef int rl_intfunc_t (int);
245 @item #define rl_ivoidfunc_t rl_hook_func_t
246 @item typedef int rl_icpfunc_t (char *);
247 @item typedef int rl_icppfunc_t (char **);
249 @item typedef void rl_voidfunc_t (void);
250 @item typedef void rl_vintfunc_t (int);
251 @item typedef void rl_vcpfunc_t (char *);
252 @item typedef void rl_vcppfunc_t (char **);
256 @node Function Writing
257 @subsection Writing a New Function
259 In order to write new functions for Readline, you need to know the
260 calling conventions for keyboard-invoked functions, and the names of the
261 variables that describe the current state of the line read so far.
263 The calling sequence for a command @code{foo} looks like
266 @code{foo (int count, int key)}
270 where @var{count} is the numeric argument (or 1 if defaulted) and
271 @var{key} is the key that invoked this function.
273 It is completely up to the function as to what should be done with the
274 numeric argument. Some functions use it as a repeat count, some
275 as a flag, and others to choose alternate behavior (refreshing the current
276 line as opposed to refreshing the screen, for example). Some choose to
277 ignore it. In general, if a
278 function uses the numeric argument as a repeat count, it should be able
279 to do something useful with both negative and positive arguments.
280 At the very least, it should be aware that it can be passed a
283 @node Readline Variables
284 @section Readline Variables
286 These variables are available to function writers.
288 @deftypevar {char *} rl_line_buffer
289 This is the line gathered so far. You are welcome to modify the
290 contents of the line, but see @ref{Allowing Undoing}. The
291 function @code{rl_extend_line_buffer} is available to increase
292 the memory allocated to @code{rl_line_buffer}.
295 @deftypevar int rl_point
296 The offset of the current cursor position in @code{rl_line_buffer}
300 @deftypevar int rl_end
301 The number of characters present in @code{rl_line_buffer}. When
302 @code{rl_point} is at the end of the line, @code{rl_point} and
303 @code{rl_end} are equal.
306 @deftypevar int rl_mark
307 The @var{mark} (saved position) in the current line. If set, the mark
308 and point define a @emph{region}.
311 @deftypevar int rl_done
312 Setting this to a non-zero value causes Readline to return the current
316 @deftypevar int rl_num_chars_to_read
317 Setting this to a positive value before calling @code{readline()} causes
318 Readline to return after accepting that many characters, rather
319 than reading up to a character bound to @code{accept-line}.
322 @deftypevar int rl_pending_input
323 Setting this to a value makes it the next keystroke read. This is a
324 way to stuff a single character into the input stream.
327 @deftypevar int rl_dispatching
328 Set to a non-zero value if a function is being called from a key binding;
329 zero otherwise. Application functions can test this to discover whether
330 they were called directly or by Readline's dispatching mechanism.
333 @deftypevar int rl_erase_empty_line
334 Setting this to a non-zero value causes Readline to completely erase
335 the current line, including any prompt, any time a newline is typed as
336 the only character on an otherwise-empty line. The cursor is moved to
337 the beginning of the newly-blank line.
340 @deftypevar {char *} rl_prompt
341 The prompt Readline uses. This is set from the argument to
342 @code{readline()}, and should not be assigned to directly.
343 The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
344 be used to modify the prompt string after calling @code{readline()}.
347 @deftypevar int rl_already_prompted
348 If an application wishes to display the prompt itself, rather than have
349 Readline do it the first time @code{readline()} is called, it should set
350 this variable to a non-zero value after displaying the prompt.
351 The prompt must also be passed as the argument to @code{readline()} so
352 the redisplay functions can update the display properly.
353 The calling application is responsible for managing the value; Readline
357 @deftypevar {const char *} rl_library_version
358 The version number of this revision of the library.
361 @deftypevar int rl_readline_version
362 An integer encoding the current version of the library. The encoding is
363 of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
364 number, and @var{mm} is the two-digit minor version number.
365 For example, for Readline-4.2, @code{rl_readline_version} would have the
369 @deftypevar {int} rl_gnu_readline_p
370 Always set to 1, denoting that this is @sc{gnu} readline rather than some
374 @deftypevar {const char *} rl_terminal_name
375 The terminal type, used for initialization. If not set by the application,
376 Readline sets this to the value of the @env{TERM} environment variable
377 the first time it is called.
380 @deftypevar {const char *} rl_readline_name
381 This variable is set to a unique name by each application using Readline.
382 The value allows conditional parsing of the inputrc file
383 (@pxref{Conditional Init Constructs}).
386 @deftypevar {FILE *} rl_instream
387 The stdio stream from which Readline reads input.
390 @deftypevar {FILE *} rl_outstream
391 The stdio stream to which Readline performs output.
394 @deftypevar {rl_command_func_t *} rl_last_func
395 The address of the last command function Readline executed. May be used to
396 test whether or not a function is being executed twice in succession, for
400 @deftypevar {rl_hook_func_t *} rl_startup_hook
401 If non-zero, this is the address of a function to call just
402 before @code{readline} prints the first prompt.
405 @deftypevar {rl_hook_func_t *} rl_pre_input_hook
406 If non-zero, this is the address of a function to call after
407 the first prompt has been printed and just before @code{readline}
408 starts reading input characters.
411 @deftypevar {rl_hook_func_t *} rl_event_hook
412 If non-zero, this is the address of a function to call periodically
413 when Readline is waiting for terminal input.
414 By default, this will be called at most ten times a second if there
415 is no keyboard input.
418 @deftypevar {rl_getc_func_t *} rl_getc_function
419 If non-zero, Readline will call indirectly through this pointer
420 to get a character from the input stream. By default, it is set to
421 @code{rl_getc}, the default Readline character input function
422 (@pxref{Character Input}).
425 @deftypevar {rl_voidfunc_t *} rl_redisplay_function
426 If non-zero, Readline will call indirectly through this pointer
427 to update the display with the current contents of the editing buffer.
428 By default, it is set to @code{rl_redisplay}, the default Readline
429 redisplay function (@pxref{Redisplay}).
432 @deftypevar {rl_vintfunc_t *} rl_prep_term_function
433 If non-zero, Readline will call indirectly through this pointer
434 to initialize the terminal. The function takes a single argument, an
435 @code{int} flag that says whether or not to use eight-bit characters.
436 By default, this is set to @code{rl_prep_terminal}
437 (@pxref{Terminal Management}).
440 @deftypevar {rl_voidfunc_t *} rl_deprep_term_function
441 If non-zero, Readline will call indirectly through this pointer
442 to reset the terminal. This function should undo the effects of
443 @code{rl_prep_term_function}.
444 By default, this is set to @code{rl_deprep_terminal}
445 (@pxref{Terminal Management}).
448 @deftypevar {Keymap} rl_executing_keymap
449 This variable is set to the keymap (@pxref{Keymaps}) in which the
450 currently executing readline function was found.
453 @deftypevar {Keymap} rl_binding_keymap
454 This variable is set to the keymap (@pxref{Keymaps}) in which the
455 last key binding occurred.
458 @deftypevar {char *} rl_executing_macro
459 This variable is set to the text of any currently-executing macro.
462 @deftypevar {int} rl_readline_state
463 A variable with bit values that encapsulate the current Readline state.
464 A bit is set with the @code{RL_SETSTATE} macro, and unset with the
465 @code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test
466 whether a particular state bit is set. Current state bits include:
470 Readline has not yet been called, nor has it begun to intialize.
471 @item RL_STATE_INITIALIZING
472 Readline is initializing its internal data structures.
473 @item RL_STATE_INITIALIZED
474 Readline has completed its initialization.
475 @item RL_STATE_TERMPREPPED
476 Readline has modified the terminal modes to do its own input and redisplay.
477 @item RL_STATE_READCMD
478 Readline is reading a command from the keyboard.
479 @item RL_STATE_METANEXT
480 Readline is reading more input after reading the meta-prefix character.
481 @item RL_STATE_DISPATCHING
482 Readline is dispatching to a command.
483 @item RL_STATE_MOREINPUT
484 Readline is reading more input while executing an editing command.
485 @item RL_STATE_ISEARCH
486 Readline is performing an incremental history search.
487 @item RL_STATE_NSEARCH
488 Readline is performing a non-incremental history search.
489 @item RL_STATE_SEARCH
490 Readline is searching backward or forward through the history for a string.
491 @item RL_STATE_NUMERICARG
492 Readline is reading a numeric argument.
493 @item RL_STATE_MACROINPUT
494 Readline is currently getting its input from a previously-defined keyboard
496 @item RL_STATE_MACRODEF
497 Readline is currently reading characters defining a keyboard macro.
498 @item RL_STATE_OVERWRITE
499 Readline is in overwrite mode.
500 @item RL_STATE_COMPLETING
501 Readline is performing word completion.
502 @item RL_STATE_SIGHANDLER
503 Readline is currently executing the readline signal handler.
504 @item RL_STATE_UNDOING
505 Readline is performing an undo.
507 Readline has read a key sequence bound to @code{accept-line}
508 and is about to return the line to the caller.
513 @deftypevar {int} rl_explicit_arg
514 Set to a non-zero value if an explicit numeric argument was specified by
515 the user. Only valid in a bindable command function.
518 @deftypevar {int} rl_numeric_arg
519 Set to the value of any numeric argument explicitly specified by the user
520 before executing the current Readline function. Only valid in a bindable
524 @deftypevar {int} rl_editing_mode
525 Set to a value denoting Readline's current editing mode. A value of
526 @var{1} means Readline is currently in emacs mode; @var{0}
527 means that vi mode is active.
531 @node Readline Convenience Functions
532 @section Readline Convenience Functions
535 * Function Naming:: How to give a function you write a name.
536 * Keymaps:: Making keymaps.
537 * Binding Keys:: Changing Keymaps.
538 * Associating Function Names and Bindings:: Translate function names to
540 * Allowing Undoing:: How to make your functions undoable.
541 * Redisplay:: Functions to control line display.
542 * Modifying Text:: Functions to modify @code{rl_line_buffer}.
543 * Character Input:: Functions to read keyboard input.
544 * Terminal Management:: Functions to manage terminal settings.
545 * Utility Functions:: Generally useful functions and hooks.
546 * Miscellaneous Functions:: Functions that don't fall into any category.
547 * Alternate Interface:: Using Readline in a `callback' fashion.
548 * A Readline Example:: An example Readline function.
551 @node Function Naming
552 @subsection Naming a Function
554 The user can dynamically change the bindings of keys while using
555 Readline. This is done by representing the function with a descriptive
556 name. The user is able to type the descriptive name when referring to
557 the function. Thus, in an init file, one might find
560 Meta-Rubout: backward-kill-word
563 This binds the keystroke @key{Meta-Rubout} to the function
564 @emph{descriptively} named @code{backward-kill-word}. You, as the
565 programmer, should bind the functions you write to descriptive names as
566 well. Readline provides a function for doing that:
568 @deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
569 Add @var{name} to the list of named functions. Make @var{function} be
570 the function that gets called. If @var{key} is not -1, then bind it to
571 @var{function} using @code{rl_bind_key()}.
574 Using this function alone is sufficient for most applications. It is
575 the recommended way to add a few functions to the default functions that
576 Readline has built in. If you need to do something other
577 than adding a function to Readline, you may need to use the
578 underlying functions described below.
581 @subsection Selecting a Keymap
583 Key bindings take place on a @dfn{keymap}. The keymap is the
584 association between the keys that the user types and the functions that
585 get run. You can make your own keymaps, copy existing keymaps, and tell
586 Readline which keymap to use.
588 @deftypefun Keymap rl_make_bare_keymap (void)
589 Returns a new, empty keymap. The space for the keymap is allocated with
590 @code{malloc()}; the caller should free it by calling
591 @code{rl_discard_keymap()} when done.
594 @deftypefun Keymap rl_copy_keymap (Keymap map)
595 Return a new keymap which is a copy of @var{map}.
598 @deftypefun Keymap rl_make_keymap (void)
599 Return a new keymap with the printing characters bound to rl_insert,
600 the lowercase Meta characters bound to run their equivalents, and
601 the Meta digits bound to produce numeric arguments.
604 @deftypefun void rl_discard_keymap (Keymap keymap)
605 Free the storage associated with @var{keymap}.
608 Readline has several internal keymaps. These functions allow you to
609 change which keymap is active.
611 @deftypefun Keymap rl_get_keymap (void)
612 Returns the currently active keymap.
615 @deftypefun void rl_set_keymap (Keymap keymap)
616 Makes @var{keymap} the currently active keymap.
619 @deftypefun Keymap rl_get_keymap_by_name (const char *name)
620 Return the keymap matching @var{name}. @var{name} is one which would
621 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
624 @deftypefun {char *} rl_get_keymap_name (Keymap keymap)
625 Return the name matching @var{keymap}. @var{name} is one which would
626 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
630 @subsection Binding Keys
632 Key sequences are associate with functions through the keymap.
633 Readline has several internal keymaps: @code{emacs_standard_keymap},
634 @code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
635 @code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
636 @code{emacs_standard_keymap} is the default, and the examples in
637 this manual assume that.
639 Since @code{readline()} installs a set of default key bindings the first
640 time it is called, there is always the danger that a custom binding
641 installed before the first call to @code{readline()} will be overridden.
642 An alternate mechanism is to install custom key bindings in an
643 initialization function assigned to the @code{rl_startup_hook} variable
644 (@pxref{Readline Variables}).
646 These functions manage key bindings.
648 @deftypefun int rl_bind_key (int key, rl_command_func_t *function)
649 Binds @var{key} to @var{function} in the currently active keymap.
650 Returns non-zero in the case of an invalid @var{key}.
653 @deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
654 Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case
655 of an invalid @var{key}.
658 @deftypefun int rl_unbind_key (int key)
659 Bind @var{key} to the null function in the currently active keymap.
660 Returns non-zero in case of error.
663 @deftypefun int rl_unbind_key_in_map (int key, Keymap map)
664 Bind @var{key} to the null function in @var{map}.
665 Returns non-zero in case of error.
668 @deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
669 Unbind all keys that execute @var{function} in @var{map}.
672 @deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
673 Unbind all keys that are bound to @var{command} in @var{map}.
676 @deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
677 Bind the key sequence represented by the string @var{keyseq} to the function
678 @var{function}. This makes new keymaps as
679 necessary. The initial keymap in which to do bindings is @var{map}.
682 @deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
683 Bind the key sequence represented by the string @var{keyseq} to the arbitrary
684 pointer @var{data}. @var{type} says what kind of data is pointed to by
685 @var{data}; this can be a function (@code{ISFUNC}), a macro
686 (@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
687 necessary. The initial keymap in which to do bindings is @var{map}.
690 @deftypefun int rl_parse_and_bind (char *line)
691 Parse @var{line} as if it had been read from the @code{inputrc} file and
692 perform any key bindings and variable assignments found
693 (@pxref{Readline Init File}).
696 @deftypefun int rl_read_init_file (const char *filename)
697 Read keybindings and variable assignments from @var{filename}
698 (@pxref{Readline Init File}).
701 @node Associating Function Names and Bindings
702 @subsection Associating Function Names and Bindings
704 These functions allow you to find out what keys invoke named functions
705 and the functions invoked by a particular key sequence. You may also
706 associate a new function name with an arbitrary function.
708 @deftypefun {rl_command_func_t *} rl_named_function (const char *name)
709 Return the function with name @var{name}.
712 @deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
713 Return the function invoked by @var{keyseq} in keymap @var{map}.
714 If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
715 not @code{NULL}, the type of the object is returned in the @code{int} variable
716 it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
719 @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
720 Return an array of strings representing the key sequences used to
721 invoke @var{function} in the current keymap.
724 @deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
725 Return an array of strings representing the key sequences used to
726 invoke @var{function} in the keymap @var{map}.
729 @deftypefun void rl_function_dumper (int readable)
730 Print the readline function names and the key sequences currently
731 bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
732 the list is formatted in such a way that it can be made part of an
733 @code{inputrc} file and re-read.
736 @deftypefun void rl_list_funmap_names (void)
737 Print the names of all bindable Readline functions to @code{rl_outstream}.
740 @deftypefun {const char **} rl_funmap_names (void)
741 Return a NULL terminated array of known function names. The array is
742 sorted. The array itself is allocated, but not the strings inside. You
743 should @code{free()} the array when you are done, but not the pointers.
746 @deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
747 Add @var{name} to the list of bindable Readline command names, and make
748 @var{function} the function to be called when @var{name} is invoked.
751 @node Allowing Undoing
752 @subsection Allowing Undoing
754 Supporting the undo command is a painless thing, and makes your
755 functions much more useful. It is certainly easy to try
756 something if you know you can undo it.
758 If your function simply inserts text once, or deletes text once, and
759 uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
760 undoing is already done for you automatically.
762 If you do multiple insertions or multiple deletions, or any combination
763 of these operations, you should group them together into one operation.
764 This is done with @code{rl_begin_undo_group()} and
765 @code{rl_end_undo_group()}.
767 The types of events that can be undone are:
770 enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
773 Notice that @code{UNDO_DELETE} means to insert some text, and
774 @code{UNDO_INSERT} means to delete some text. That is, the undo code
775 tells what to undo, not how to undo it. @code{UNDO_BEGIN} and
776 @code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
777 @code{rl_end_undo_group()}.
779 @deftypefun int rl_begin_undo_group (void)
780 Begins saving undo information in a group construct. The undo
781 information usually comes from calls to @code{rl_insert_text()} and
782 @code{rl_delete_text()}, but could be the result of calls to
783 @code{rl_add_undo()}.
786 @deftypefun int rl_end_undo_group (void)
787 Closes the current undo group started with @code{rl_begin_undo_group
788 ()}. There should be one call to @code{rl_end_undo_group()}
789 for each call to @code{rl_begin_undo_group()}.
792 @deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
793 Remember how to undo an event (according to @var{what}). The affected
794 text runs from @var{start} to @var{end}, and encompasses @var{text}.
797 @deftypefun void rl_free_undo_list (void)
798 Free the existing undo list.
801 @deftypefun int rl_do_undo (void)
802 Undo the first thing on the undo list. Returns @code{0} if there was
803 nothing to undo, non-zero if something was undone.
806 Finally, if you neither insert nor delete text, but directly modify the
807 existing text (e.g., change its case), call @code{rl_modifying()}
808 once, just before you modify the text. You must supply the indices of
809 the text range that you are going to modify.
811 @deftypefun int rl_modifying (int start, int end)
812 Tell Readline to save the text between @var{start} and @var{end} as a
813 single undo unit. It is assumed that you will subsequently modify
818 @subsection Redisplay
820 @deftypefun void rl_redisplay (void)
821 Change what's displayed on the screen to reflect the current contents
822 of @code{rl_line_buffer}.
825 @deftypefun int rl_forced_update_display (void)
826 Force the line to be updated and redisplayed, whether or not
827 Readline thinks the screen display is correct.
830 @deftypefun int rl_on_new_line (void)
831 Tell the update functions that we have moved onto a new (empty) line,
832 usually after ouputting a newline.
835 @deftypefun int rl_on_new_line_with_prompt (void)
836 Tell the update functions that we have moved onto a new line, with
837 @var{rl_prompt} already displayed.
838 This could be used by applications that want to output the prompt string
839 themselves, but still need Readline to know the prompt string length for
841 It should be used after setting @var{rl_already_prompted}.
844 @deftypefun int rl_reset_line_state (void)
845 Reset the display state to a clean state and redisplay the current line
846 starting on a new line.
849 @deftypefun int rl_crlf (void)
850 Move the cursor to the start of the next screen line.
853 @deftypefun int rl_show_char (int c)
854 Display character @var{c} on @code{rl_outstream}.
855 If Readline has not been set to display meta characters directly, this
856 will convert meta characters to a meta-prefixed key sequence.
857 This is intended for use by applications which wish to do their own
861 @deftypefun int rl_message (const char *, @dots{})
862 The arguments are a format string as would be supplied to @code{printf},
863 possibly containing conversion specifications such as @samp{%d}, and
864 any additional arguments necessary to satisfy the conversion specifications.
865 The resulting string is displayed in the @dfn{echo area}. The echo area
866 is also used to display numeric arguments and search strings.
869 @deftypefun int rl_clear_message (void)
870 Clear the message in the echo area.
873 @deftypefun void rl_save_prompt (void)
874 Save the local Readline prompt display state in preparation for
875 displaying a new message in the message area with @code{rl_message()}.
878 @deftypefun void rl_restore_prompt (void)
879 Restore the local Readline prompt display state saved by the most
880 recent call to @code{rl_save_prompt}.
883 @deftypefun int rl_expand_prompt (char *prompt)
884 Expand any special character sequences in @var{prompt} and set up the
885 local Readline prompt redisplay variables.
886 This function is called by @code{readline()}. It may also be called to
887 expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
888 function or @code{rl_already_prompted} variable is used.
889 It returns the number of visible characters on the last line of the
890 (possibly multi-line) prompt.
893 @deftypefun int rl_set_prompt (const char *prompt)
894 Make Readline use @var{prompt} for subsequent redisplay. This calls
895 @code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
900 @subsection Modifying Text
902 @deftypefun int rl_insert_text (const char *text)
903 Insert @var{text} into the line at the current cursor position.
906 @deftypefun int rl_delete_text (int start, int end)
907 Delete the text between @var{start} and @var{end} in the current line.
910 @deftypefun {char *} rl_copy_text (int start, int end)
911 Return a copy of the text between @var{start} and @var{end} in
915 @deftypefun int rl_kill_text (int start, int end)
916 Copy the text between @var{start} and @var{end} in the current line
917 to the kill ring, appending or prepending to the last kill if the
918 last command was a kill command. The text is deleted.
919 If @var{start} is less than @var{end},
920 the text is appended, otherwise prepended. If the last command was
921 not a kill, a new kill ring slot is used.
924 @deftypefun int rl_push_macro_input (char *macro)
925 Cause @var{macro} to be inserted into the line, as if it had been invoked
926 by a key bound to a macro. Not especially useful; use
927 @code{rl_insert_text()} instead.
930 @node Character Input
931 @subsection Character Input
933 @deftypefun int rl_read_key (void)
934 Return the next character available from Readline's current input stream.
935 This handles input inserted into
936 the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
937 and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
938 While waiting for input, this function will call any function assigned to
939 the @code{rl_event_hook} variable.
942 @deftypefun int rl_getc (FILE *stream)
943 Return the next character available from @var{stream}, which is assumed to
947 @deftypefun int rl_stuff_char (int c)
948 Insert @var{c} into the Readline input stream. It will be "read"
949 before Readline attempts to read characters from the terminal with
950 @code{rl_read_key()}.
953 @deftypefun int rl_execute_next (int c)
954 Make @var{c} be the next command to be executed when @code{rl_read_key()}
955 is called. This sets @var{rl_pending_input}.
958 @deftypefun int rl_clear_pending_input (void)
959 Unset @var{rl_pending_input}, effectively negating the effect of any
960 previous call to @code{rl_execute_next()}. This works only if the
961 pending input has not already been read with @code{rl_read_key()}.
964 @deftypefun int rl_set_keyboard_input_timeout (int u)
965 While waiting for keyboard input in @code{rl_read_key()}, Readline will
966 wait for @var{u} microseconds for input before calling any function
967 assigned to @code{rl_event_hook}. The default waiting period is
968 one-tenth of a second. Returns the old timeout value.
971 @node Terminal Management
972 @subsection Terminal Management
974 @deftypefun void rl_prep_terminal (int meta_flag)
975 Modify the terminal settings for Readline's use, so @code{readline()}
976 can read a single character at a time from the keyboard.
977 The @var{meta_flag} argument should be non-zero if Readline should
978 read eight-bit input.
981 @deftypefun void rl_deprep_terminal (void)
982 Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
983 the state in which it was before the most recent call to
984 @code{rl_prep_terminal()}.
987 @deftypefun void rl_tty_set_default_bindings (Keymap kmap)
988 Read the operating system's terminal editing characters (as would be displayed
989 by @code{stty}) to their Readline equivalents. The bindings are performed
993 @deftypefun int rl_reset_terminal (const char *terminal_name)
994 Reinitialize Readline's idea of the terminal settings using
995 @var{terminal_name} as the terminal type (e.g., @code{vt100}).
996 If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
997 environment variable is used.
1000 @node Utility Functions
1001 @subsection Utility Functions
1003 @deftypefun int rl_extend_line_buffer (int len)
1004 Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
1005 characters, possibly reallocating it if necessary.
1008 @deftypefun int rl_initialize (void)
1009 Initialize or re-initialize Readline's internal state.
1010 It's not strictly necessary to call this; @code{readline()} calls it before
1014 @deftypefun int rl_ding (void)
1015 Ring the terminal bell, obeying the setting of @code{bell-style}.
1018 @deftypefun int rl_alphabetic (int c)
1019 Return 1 if @var{c} is an alphabetic character.
1022 @deftypefun void rl_display_match_list (char **matches, int len, int max)
1023 A convenience function for displaying a list of strings in
1024 columnar format on Readline's output stream. @code{matches} is the list
1025 of strings, in argv format, such as a list of completion matches.
1026 @code{len} is the number of strings in @code{matches}, and @code{max}
1027 is the length of the longest string in @code{matches}. This function uses
1028 the setting of @code{print-completions-horizontally} to select how the
1029 matches are displayed (@pxref{Readline Init File Syntax}).
1032 The following are implemented as macros, defined in @code{chardefs.h}.
1033 Applications should refrain from using them.
1035 @deftypefun int _rl_uppercase_p (int c)
1036 Return 1 if @var{c} is an uppercase alphabetic character.
1039 @deftypefun int _rl_lowercase_p (int c)
1040 Return 1 if @var{c} is a lowercase alphabetic character.
1043 @deftypefun int _rl_digit_p (int c)
1044 Return 1 if @var{c} is a numeric character.
1047 @deftypefun int _rl_to_upper (int c)
1048 If @var{c} is a lowercase alphabetic character, return the corresponding
1049 uppercase character.
1052 @deftypefun int _rl_to_lower (int c)
1053 If @var{c} is an uppercase alphabetic character, return the corresponding
1054 lowercase character.
1057 @deftypefun int _rl_digit_value (int c)
1058 If @var{c} is a number, return the value it represents.
1061 @node Miscellaneous Functions
1062 @subsection Miscellaneous Functions
1064 @deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
1065 Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
1066 The binding is performed in @var{map}. When @var{keyseq} is invoked, the
1067 @var{macro} will be inserted into the line. This function is deprecated;
1068 use @code{rl_generic_bind()} instead.
1071 @deftypefun void rl_macro_dumper (int readable)
1072 Print the key sequences bound to macros and their values, using
1073 the current keymap, to @code{rl_outstream}.
1074 If @var{readable} is non-zero, the list is formatted in such a way
1075 that it can be made part of an @code{inputrc} file and re-read.
1078 @deftypefun int rl_variable_bind (const char *variable, const char *value)
1079 Make the Readline variable @var{variable} have @var{value}.
1080 This behaves as if the readline command
1081 @samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
1082 file (@pxref{Readline Init File Syntax}).
1085 @deftypefun void rl_variable_dumper (int readable)
1086 Print the readline variable names and their current values
1087 to @code{rl_outstream}.
1088 If @var{readable} is non-zero, the list is formatted in such a way
1089 that it can be made part of an @code{inputrc} file and re-read.
1092 @deftypefun int rl_set_paren_blink_timeout (int u)
1093 Set the time interval (in microseconds) that Readline waits when showing
1094 a balancing character when @code{blink-matching-paren} has been enabled.
1097 @deftypefun {char *} rl_get_termcap (const char *cap)
1098 Retrieve the string value of the termcap capability @var{cap}.
1099 Readline fetches the termcap entry for the current terminal name and
1100 uses those capabilities to move around the screen line and perform other
1101 terminal-specific operations, like erasing a line. Readline does not
1102 use all of a terminal's capabilities, and this function will return
1103 values for only those capabilities Readline uses.
1106 @node Alternate Interface
1107 @subsection Alternate Interface
1109 An alternate interface is available to plain @code{readline()}. Some
1110 applications need to interleave keyboard I/O with file, device, or
1111 window system I/O, typically by using a main loop to @code{select()}
1112 on various file descriptors. To accomodate this need, readline can
1113 also be invoked as a `callback' function from an event loop. There
1114 are functions available to make this easy.
1116 @deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
1117 Set up the terminal for readline I/O and display the initial
1118 expanded value of @var{prompt}. Save the value of @var{lhandler} to
1119 use as a function to call when a complete line of input has been entered.
1120 The function takes the text of the line as an argument.
1123 @deftypefun void rl_callback_read_char (void)
1124 Whenever an application determines that keyboard input is available, it
1125 should call @code{rl_callback_read_char()}, which will read the next
1126 character from the current input source. If that character completes the
1127 line, @code{rl_callback_read_char} will invoke the @var{lhandler}
1128 function saved by @code{rl_callback_handler_install} to process the
1129 line. @code{EOF} is indicated by calling @var{lhandler} with a
1133 @deftypefun void rl_callback_handler_remove (void)
1134 Restore the terminal to its initial state and remove the line handler.
1135 This may be called from within a callback as well as independently.
1138 @node A Readline Example
1139 @subsection A Readline Example
1141 Here is a function which changes lowercase characters to their uppercase
1142 equivalents, and uppercase characters to lowercase. If
1143 this function was bound to @samp{M-c}, then typing @samp{M-c} would
1144 change the case of the character under point. Typing @samp{M-1 0 M-c}
1145 would change the case of the following 10 characters, leaving the cursor on
1146 the last character changed.
1149 /* Invert the case of the COUNT following characters. */
1151 invert_case_line (count, key)
1154 register int start, end, i;
1158 if (rl_point >= rl_end)
1169 /* Find the end of the range to modify. */
1170 end = start + (count * direction);
1172 /* Force it to be within range. */
1188 /* Tell readline that we are modifying the line, so it will save
1189 the undo information. */
1190 rl_modifying (start, end);
1192 for (i = start; i != end; i++)
1194 if (_rl_uppercase_p (rl_line_buffer[i]))
1195 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
1196 else if (_rl_lowercase_p (rl_line_buffer[i]))
1197 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
1199 /* Move point to on top of the last character changed. */
1200 rl_point = (direction == 1) ? end - 1 : start;
1205 @node Readline Signal Handling
1206 @section Readline Signal Handling
1208 Signals are asynchronous events sent to a process by the Unix kernel,
1209 sometimes on behalf of another process. They are intended to indicate
1210 exceptional events, like a user pressing the interrupt key on his terminal,
1211 or a network connection being broken. There is a class of signals that can
1212 be sent to the process currently reading input from the keyboard. Since
1213 Readline changes the terminal attributes when it is called, it needs to
1214 perform special processing when such a signal is received in order to
1215 restore the terminal to a sane state, or provide application writers with
1216 functions to do so manually.
1218 Readline contains an internal signal handler that is installed for a
1219 number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
1220 @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
1221 When one of these signals is received, the signal handler
1222 will reset the terminal attributes to those that were in effect before
1223 @code{readline()} was called, reset the signal handling to what it was
1224 before @code{readline()} was called, and resend the signal to the calling
1226 If and when the calling application's signal handler returns, Readline
1227 will reinitialize the terminal and continue to accept input.
1228 When a @code{SIGINT} is received, the Readline signal handler performs
1229 some additional work, which will cause any partially-entered line to be
1230 aborted (see the description of @code{rl_free_line_state()} below).
1232 There is an additional Readline signal handler, for @code{SIGWINCH}, which
1233 the kernel sends to a process whenever the terminal's size changes (for
1234 example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
1235 handler updates Readline's internal screen size information, and then calls
1236 any @code{SIGWINCH} signal handler the calling application has installed.
1237 Readline calls the application's @code{SIGWINCH} signal handler without
1238 resetting the terminal to its original state. If the application's signal
1239 handler does more than update its idea of the terminal size and return (for
1240 example, a @code{longjmp} back to a main processing loop), it @emph{must}
1241 call @code{rl_cleanup_after_signal()} (described below), to restore the
1244 Readline provides two variables that allow application writers to
1245 control whether or not it will catch certain signals and act on them
1246 when they are received. It is important that applications change the
1247 values of these variables only when calling @code{readline()}, not in
1248 a signal handler, so Readline's internal signal state is not corrupted.
1250 @deftypevar int rl_catch_signals
1251 If this variable is non-zero, Readline will install signal handlers for
1252 @code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
1253 @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
1255 The default value of @code{rl_catch_signals} is 1.
1258 @deftypevar int rl_catch_sigwinch
1259 If this variable is non-zero, Readline will install a signal handler for
1262 The default value of @code{rl_catch_sigwinch} is 1.
1265 If an application does not wish to have Readline catch any signals, or
1266 to handle signals other than those Readline catches (@code{SIGHUP},
1268 Readline provides convenience functions to do the necessary terminal
1269 and internal state cleanup upon receipt of a signal.
1271 @deftypefun void rl_cleanup_after_signal (void)
1272 This function will reset the state of the terminal to what it was before
1273 @code{readline()} was called, and remove the Readline signal handlers for
1274 all signals, depending on the values of @code{rl_catch_signals} and
1275 @code{rl_catch_sigwinch}.
1278 @deftypefun void rl_free_line_state (void)
1279 This will free any partial state associated with the current input line
1280 (undo information, any partial history entry, any partially-entered
1281 keyboard macro, and any partially-entered numeric argument). This
1282 should be called before @code{rl_cleanup_after_signal()}. The
1283 Readline signal handler for @code{SIGINT} calls this to abort the
1287 @deftypefun void rl_reset_after_signal (void)
1288 This will reinitialize the terminal and reinstall any Readline signal
1289 handlers, depending on the values of @code{rl_catch_signals} and
1290 @code{rl_catch_sigwinch}.
1293 If an application does not wish Readline to catch @code{SIGWINCH}, it may
1294 call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
1295 Readline to update its idea of the terminal size when a @code{SIGWINCH}
1298 @deftypefun void rl_resize_terminal (void)
1299 Update Readline's internal screen size by reading values from the kernel.
1302 @deftypefun void rl_set_screen_size (int rows, int cols)
1303 Set Readline's idea of the terminal size to @var{rows} rows and
1307 If an application does not want to install a @code{SIGWINCH} handler, but
1308 is still interested in the screen dimensions, Readline's idea of the screen
1309 size may be queried.
1311 @deftypefun void rl_get_screen_size (int *rows, int *cols)
1312 Return Readline's idea of the terminal's size in the
1313 variables pointed to by the arguments.
1316 The following functions install and remove Readline's signal handlers.
1318 @deftypefun int rl_set_signals (void)
1319 Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
1320 @code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
1321 @code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
1322 @code{rl_catch_signals} and @code{rl_catch_sigwinch}.
1325 @deftypefun int rl_clear_signals (void)
1326 Remove all of the Readline signal handlers installed by
1327 @code{rl_set_signals()}.
1330 @node Custom Completers
1331 @section Custom Completers
1333 Typically, a program that reads commands from the user has a way of
1334 disambiguating commands and data. If your program is one of these, then
1335 it can provide completion for commands, data, or both.
1336 The following sections describe how your program and Readline
1337 cooperate to provide this service.
1340 * How Completing Works:: The logic used to do completion.
1341 * Completion Functions:: Functions provided by Readline.
1342 * Completion Variables:: Variables which control completion.
1343 * A Short Completion Example:: An example of writing completer subroutines.
1346 @node How Completing Works
1347 @subsection How Completing Works
1349 In order to complete some text, the full list of possible completions
1350 must be available. That is, it is not possible to accurately
1351 expand a partial word without knowing all of the possible words
1352 which make sense in that context. The Readline library provides
1353 the user interface to completion, and two of the most common
1354 completion functions: filename and username. For completing other types
1355 of text, you must write your own completion function. This section
1356 describes exactly what such functions must do, and provides an example.
1358 There are three major functions used to perform completion:
1362 The user-interface function @code{rl_complete()}. This function is
1363 called with the same arguments as other bindable Readline functions:
1364 @var{count} and @var{invoking_key}.
1365 It isolates the word to be completed and calls
1366 @code{rl_completion_matches()} to generate a list of possible completions.
1367 It then either lists the possible completions, inserts the possible
1368 completions, or actually performs the
1369 completion, depending on which behavior is desired.
1372 The internal function @code{rl_completion_matches()} uses an
1373 application-supplied @dfn{generator} function to generate the list of
1374 possible matches, and then returns the array of these matches.
1375 The caller should place the address of its generator function in
1376 @code{rl_completion_entry_function}.
1379 The generator function is called repeatedly from
1380 @code{rl_completion_matches()}, returning a string each time. The
1381 arguments to the generator function are @var{text} and @var{state}.
1382 @var{text} is the partial word to be completed. @var{state} is zero the
1383 first time the function is called, allowing the generator to perform
1384 any necessary initialization, and a positive non-zero integer for
1385 each subsequent call. The generator function returns
1386 @code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
1387 no more possibilities left. Usually the generator function computes the
1388 list of possible completions when @var{state} is zero, and returns them
1389 one at a time on subsequent calls. Each string the generator function
1390 returns as a match must be allocated with @code{malloc()}; Readline
1391 frees the strings when it has finished with them.
1395 @deftypefun int rl_complete (int ignore, int invoking_key)
1396 Complete the word at or before point. You have supplied the function
1397 that does the initial simple matching selection algorithm (see
1398 @code{rl_completion_matches()}). The default is to do filename completion.
1401 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1402 This is a pointer to the generator function for
1403 @code{rl_completion_matches()}.
1404 If the value of @code{rl_completion_entry_function} is
1405 @code{NULL} then the default filename generator
1406 function, @code{rl_filename_completion_function()}, is used.
1409 @node Completion Functions
1410 @subsection Completion Functions
1412 Here is the complete list of callable completion functions present in
1415 @deftypefun int rl_complete_internal (int what_to_do)
1416 Complete the word at or before point. @var{what_to_do} says what to do
1417 with the completion. A value of @samp{?} means list the possible
1418 completions. @samp{TAB} means do standard completion. @samp{*} means
1419 insert all of the possible completions. @samp{!} means to display
1420 all of the possible completions, if there is more than one, as well as
1421 performing partial completion.
1424 @deftypefun int rl_complete (int ignore, int invoking_key)
1425 Complete the word at or before point. You have supplied the function
1426 that does the initial simple matching selection algorithm (see
1427 @code{rl_completion_matches()} and @code{rl_completion_entry_function}).
1428 The default is to do filename
1429 completion. This calls @code{rl_complete_internal()} with an
1430 argument depending on @var{invoking_key}.
1433 @deftypefun int rl_possible_completions (int count, int invoking_key)
1434 List the possible completions. See description of @code{rl_complete
1435 ()}. This calls @code{rl_complete_internal()} with an argument of
1439 @deftypefun int rl_insert_completions (int count, int invoking_key)
1440 Insert the list of possible completions into the line, deleting the
1441 partially-completed word. See description of @code{rl_complete()}.
1442 This calls @code{rl_complete_internal()} with an argument of @samp{*}.
1445 @deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
1446 Returns an array of strings which is a list of completions for
1447 @var{text}. If there are no completions, returns @code{NULL}.
1448 The first entry in the returned array is the substitution for @var{text}.
1449 The remaining entries are the possible completions. The array is
1450 terminated with a @code{NULL} pointer.
1452 @var{entry_func} is a function of two args, and returns a
1453 @code{char *}. The first argument is @var{text}. The second is a
1454 state argument; it is zero on the first call, and non-zero on subsequent
1455 calls. @var{entry_func} returns a @code{NULL} pointer to the caller
1456 when there are no more matches.
1459 @deftypefun {char *} rl_filename_completion_function (const char *text, int state)
1460 A generator function for filename completion in the general case.
1461 @var{text} is a partial filename.
1462 The Bash source is a useful reference for writing custom
1463 completion functions (the Bash completion functions call this and other
1464 Readline functions).
1467 @deftypefun {char *} rl_username_completion_function (const char *text, int state)
1468 A completion generator for usernames. @var{text} contains a partial
1469 username preceded by a random character (usually @samp{~}). As with all
1470 completion generators, @var{state} is zero on the first call and non-zero
1471 for subsequent calls.
1474 @node Completion Variables
1475 @subsection Completion Variables
1477 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1478 A pointer to the generator function for @code{rl_completion_matches()}.
1479 @code{NULL} means to use @code{rl_filename_completion_function()}, the default
1483 @deftypevar {rl_completion_func_t *} rl_attempted_completion_function
1484 A pointer to an alternative function to create matches.
1485 The function is called with @var{text}, @var{start}, and @var{end}.
1486 @var{start} and @var{end} are indices in @code{rl_line_buffer} defining
1487 the boundaries of @var{text}, which is a character string.
1488 If this function exists and returns @code{NULL}, or if this variable is
1489 set to @code{NULL}, then @code{rl_complete()} will call the value of
1490 @code{rl_completion_entry_function} to generate matches, otherwise the
1491 array of strings returned will be used.
1492 If this function sets the @code{rl_attempted_completion_over}
1493 variable to a non-zero value, Readline will not perform its default
1494 completion even if this function returns no matches.
1497 @deftypevar {rl_quote_func_t *} rl_filename_quoting_function
1498 A pointer to a function that will quote a filename in an
1499 application-specific fashion. This is called if filename completion is being
1500 attempted and one of the characters in @code{rl_filename_quote_characters}
1501 appears in a completed filename. The function is called with
1502 @var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
1503 is the filename to be quoted. The @var{match_type} is either
1504 @code{SINGLE_MATCH}, if there is only one completion match, or
1505 @code{MULT_MATCH}. Some functions use this to decide whether or not to
1506 insert a closing quote character. The @var{quote_pointer} is a pointer
1507 to any opening quote character the user typed. Some functions choose
1508 to reset this character.
1511 @deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
1512 A pointer to a function that will remove application-specific quoting
1513 characters from a filename before completion is attempted, so those
1514 characters do not interfere with matching the text against names in
1515 the filesystem. It is called with @var{text}, the text of the word
1516 to be dequoted, and @var{quote_char}, which is the quoting character
1517 that delimits the filename (usually @samp{'} or @samp{"}). If
1518 @var{quote_char} is zero, the filename was not in an embedded string.
1521 @deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
1522 A pointer to a function to call that determines whether or not a specific
1523 character in the line buffer is quoted, according to whatever quoting
1524 mechanism the program calling Readline uses. The function is called with
1525 two arguments: @var{text}, the text of the line, and @var{index}, the
1526 index of the character in the line. It is used to decide whether a
1527 character found in @code{rl_completer_word_break_characters} should be
1528 used to break words for the completer.
1531 @deftypevar int rl_completion_query_items
1532 Up to this many items will be displayed in response to a
1533 possible-completions call. After that, we ask the user if she is sure
1534 she wants to see them all. The default value is 100.
1537 @deftypevar {const char *} rl_basic_word_break_characters
1538 The basic list of characters that signal a break between words for the
1539 completer routine. The default value of this variable is the characters
1540 which break words for completion in Bash:
1541 @code{" \t\n\"\\'`@@$><=;|&@{("}.
1544 @deftypevar {const char *} rl_basic_quote_characters
1545 A list of quote characters which can cause a word break.
1548 @deftypevar {const char *} rl_completer_word_break_characters
1549 The list of characters that signal a break between words for
1550 @code{rl_complete_internal()}. The default list is the value of
1551 @code{rl_basic_word_break_characters}.
1554 @deftypevar {const char *} rl_completer_quote_characters
1555 A list of characters which can be used to quote a substring of the line.
1556 Completion occurs on the entire substring, and within the substring
1557 @code{rl_completer_word_break_characters} are treated as any other character,
1558 unless they also appear within this list.
1561 @deftypevar {const char *} rl_filename_quote_characters
1562 A list of characters that cause a filename to be quoted by the completer
1563 when they appear in a completed filename. The default is the null string.
1566 @deftypevar {const char *} rl_special_prefixes
1567 The list of characters that are word break characters, but should be
1568 left in @var{text} when it is passed to the completion function.
1569 Programs can use this to help determine what kind of completing to do.
1570 For instance, Bash sets this variable to "$@@" so that it can complete
1571 shell variables and hostnames.
1574 @deftypevar {int} rl_completion_append_character
1575 When a single completion alternative matches at the end of the command
1576 line, this character is appended to the inserted completion text. The
1577 default is a space character (@samp{ }). Setting this to the null
1578 character (@samp{\0}) prevents anything being appended automatically.
1579 This can be changed in custom completion functions to
1580 provide the ``most sensible word separator character'' according to
1581 an application-specific command line syntax specification.
1584 @deftypevar int rl_ignore_completion_duplicates
1585 If non-zero, then duplicates in the matches are removed.
1589 @deftypevar int rl_filename_completion_desired
1590 Non-zero means that the results of the matches are to be treated as
1591 filenames. This is @emph{always} zero on entry, and can only be changed
1592 within a completion entry generator function. If it is set to a non-zero
1593 value, directory names have a slash appended and Readline attempts to
1594 quote completed filenames if they contain any characters in
1595 @code{rl_filename_quote_characters} and @code{rl_filename_quoting_desired}
1596 is set to a non-zero value.
1599 @deftypevar int rl_filename_quoting_desired
1600 Non-zero means that the results of the matches are to be quoted using
1601 double quotes (or an application-specific quoting mechanism) if the
1602 completed filename contains any characters in
1603 @code{rl_filename_quote_chars}. This is @emph{always} non-zero
1604 on entry, and can only be changed within a completion entry generator
1605 function. The quoting is effected via a call to the function pointed to
1606 by @code{rl_filename_quoting_function}.
1609 @deftypevar int rl_attempted_completion_over
1610 If an application-specific completion function assigned to
1611 @code{rl_attempted_completion_function} sets this variable to a non-zero
1612 value, Readline will not perform its default filename completion even
1613 if the application's completion function returns no matches.
1614 It should be set only by an application's completion function.
1617 @deftypevar int rl_completion_type
1618 Set to a character describing the type of completion Readline is currently
1619 attempting; see the description of @code{rl_complete_internal()}
1620 (@pxref{Completion Functions}) for the list of characters.
1623 @deftypevar int rl_inhibit_completion
1624 If this variable is non-zero, completion is inhibited. The completion
1625 character will be inserted as any other bound to @code{self-insert}.
1628 @deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
1629 This function, if defined, is called by the completer when real filename
1630 completion is done, after all the matching names have been generated.
1631 It is passed a @code{NULL} terminated array of matches.
1632 The first element (@code{matches[0]}) is the
1633 maximal substring common to all matches. This function can
1634 re-arrange the list of matches as required, but each element deleted
1635 from the array must be freed.
1638 @deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
1639 This function, if defined, is allowed to modify the directory portion
1640 of filenames Readline completes. It is called with the address of a
1641 string (the current directory name) as an argument, and may modify that string.
1642 If the string is replaced with a new string, the old value should be freed.
1643 Any modified directory name should have a trailing slash.
1644 The modified value will be displayed as part of the completion, replacing
1645 the directory portion of the pathname the user typed.
1646 It returns an integer that should be non-zero if the function modifies
1647 its directory argument.
1648 It could be used to expand symbolic links or shell variables in pathnames.
1651 @deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
1652 If non-zero, then this is the address of a function to call when
1653 completing a word would normally display the list of possible matches.
1654 This function is called in lieu of Readline displaying the list.
1655 It takes three arguments:
1656 (@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
1657 where @var{matches} is the array of matching strings,
1658 @var{num_matches} is the number of strings in that array, and
1659 @var{max_length} is the length of the longest string in that array.
1660 Readline provides a convenience function, @code{rl_display_match_list},
1661 that takes care of doing the display to Readline's output stream. That
1662 function may be called from this hook.
1665 @node A Short Completion Example
1666 @subsection A Short Completion Example
1668 Here is a small application demonstrating the use of the GNU Readline
1669 library. It is called @code{fileman}, and the source code resides in
1670 @file{examples/fileman.c}. This sample application provides
1671 completion of command names, line editing features, and access to the
1676 /* fileman.c -- A tiny application which demonstrates how to use the
1677 GNU Readline library. This application interactively allows users
1678 to manipulate files and their modes. */
1681 #include <sys/types.h>
1682 #include <sys/file.h>
1683 #include <sys/stat.h>
1684 #include <sys/errno.h>
1686 #include <readline/readline.h>
1687 #include <readline/history.h>
1689 extern char *xmalloc ();
1691 /* The names of functions that actually do the manipulation. */
1692 int com_list __P((char *));
1693 int com_view __P((char *));
1694 int com_rename __P((char *));
1695 int com_stat __P((char *));
1696 int com_pwd __P((char *));
1697 int com_delete __P((char *));
1698 int com_help __P((char *));
1699 int com_cd __P((char *));
1700 int com_quit __P((char *));
1702 /* A structure which contains information on the commands this program
1706 char *name; /* User printable name of the function. */
1707 rl_icpfunc_t *func; /* Function to call to do the job. */
1708 char *doc; /* Documentation for this function. */
1711 COMMAND commands[] = @{
1712 @{ "cd", com_cd, "Change to directory DIR" @},
1713 @{ "delete", com_delete, "Delete FILE" @},
1714 @{ "help", com_help, "Display this text" @},
1715 @{ "?", com_help, "Synonym for `help'" @},
1716 @{ "list", com_list, "List files in DIR" @},
1717 @{ "ls", com_list, "Synonym for `list'" @},
1718 @{ "pwd", com_pwd, "Print the current working directory" @},
1719 @{ "quit", com_quit, "Quit using Fileman" @},
1720 @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
1721 @{ "stat", com_stat, "Print out statistics on FILE" @},
1722 @{ "view", com_view, "View the contents of FILE" @},
1723 @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
1726 /* Forward declarations. */
1727 char *stripwhite ();
1728 COMMAND *find_command ();
1730 /* The name of this program, as taken from argv[0]. */
1733 /* When non-zero, this means the user is done using this program. */
1742 r = xmalloc (strlen (s) + 1);
1755 initialize_readline (); /* Bind our completer. */
1757 /* Loop reading and executing lines until the user quits. */
1758 for ( ; done == 0; )
1760 line = readline ("FileMan: ");
1765 /* Remove leading and trailing whitespace from the line.
1766 Then, if there is anything left, add it to the history list
1768 s = stripwhite (line);
1781 /* Execute a command line. */
1790 /* Isolate the command word. */
1792 while (line[i] && whitespace (line[i]))
1796 while (line[i] && !whitespace (line[i]))
1802 command = find_command (word);
1806 fprintf (stderr, "%s: No such command for FileMan.\n", word);
1810 /* Get argument to command, if any. */
1811 while (whitespace (line[i]))
1816 /* Call the function. */
1817 return ((*(command->func)) (word));
1820 /* Look up NAME as the name of a command, and return a pointer to that
1821 command. Return a NULL pointer if NAME isn't a command name. */
1828 for (i = 0; commands[i].name; i++)
1829 if (strcmp (name, commands[i].name) == 0)
1830 return (&commands[i]);
1832 return ((COMMAND *)NULL);
1835 /* Strip whitespace from the start and end of STRING. Return a pointer
1841 register char *s, *t;
1843 for (s = string; whitespace (*s); s++)
1849 t = s + strlen (s) - 1;
1850 while (t > s && whitespace (*t))
1857 /* **************************************************************** */
1859 /* Interface to Readline Completion */
1861 /* **************************************************************** */
1863 char *command_generator __P((const char *, int));
1864 char **fileman_completion __P((const char *, int, int));
1866 /* Tell the GNU Readline library how to complete. We want to try to
1867 complete on command names if this is the first word in the line, or
1868 on filenames if not. */
1869 initialize_readline ()
1871 /* Allow conditional parsing of the ~/.inputrc file. */
1872 rl_readline_name = "FileMan";
1874 /* Tell the completer that we want a crack first. */
1875 rl_attempted_completion_function = fileman_completion;
1878 /* Attempt to complete on the contents of TEXT. START and END
1879 bound the region of rl_line_buffer that contains the word to
1880 complete. TEXT is the word to complete. We can use the entire
1881 contents of rl_line_buffer in case we want to do some simple
1882 parsing. Returnthe array of matches, or NULL if there aren't any. */
1884 fileman_completion (text, start, end)
1890 matches = (char **)NULL;
1892 /* If this word is at the start of the line, then it is a command
1893 to complete. Otherwise it is the name of a file in the current
1896 matches = rl_completion_matches (text, command_generator);
1901 /* Generator function for command completion. STATE lets us
1902 know whether to start from scratch; without any state
1903 (i.e. STATE == 0), then we start at the top of the list. */
1905 command_generator (text, state)
1909 static int list_index, len;
1912 /* If this is a new word to complete, initialize now. This
1913 includes saving the length of TEXT for efficiency, and
1914 initializing the index variable to 0. */
1918 len = strlen (text);
1921 /* Return the next name which partially matches from the
1923 while (name = commands[list_index].name)
1927 if (strncmp (name, text, len) == 0)
1928 return (dupstr(name));
1931 /* If no names matched, then return NULL. */
1932 return ((char *)NULL);
1935 /* **************************************************************** */
1937 /* FileMan Commands */
1939 /* **************************************************************** */
1941 /* String to pass to system (). This is for the LIST, VIEW and RENAME
1943 static char syscom[1024];
1945 /* List the file(s) named in arg. */
1952 sprintf (syscom, "ls -FClg %s", arg);
1953 return (system (syscom));
1959 if (!valid_argument ("view", arg))
1962 sprintf (syscom, "more %s", arg);
1963 return (system (syscom));
1969 too_dangerous ("rename");
1978 if (!valid_argument ("stat", arg))
1981 if (stat (arg, &finfo) == -1)
1987 printf ("Statistics for `%s':\n", arg);
1989 printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
1991 (finfo.st_nlink == 1) ? "" : "s",
1993 (finfo.st_size == 1) ? "" : "s");
1994 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
1995 printf (" Last access at: %s", ctime (&finfo.st_atime));
1996 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
2003 too_dangerous ("delete");
2007 /* Print out help for ARG, or for all of the commands if ARG is
2015 for (i = 0; commands[i].name; i++)
2017 if (!*arg || (strcmp (arg, commands[i].name) == 0))
2019 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
2026 printf ("No commands match `%s'. Possibilties are:\n", arg);
2028 for (i = 0; commands[i].name; i++)
2030 /* Print in six columns. */
2037 printf ("%s\t", commands[i].name);
2047 /* Change to the directory ARG. */
2051 if (chdir (arg) == -1)
2061 /* Print out the current working directory. */
2067 s = getcwd (dir, sizeof(dir) - 1);
2070 printf ("Error getting pwd: %s\n", dir);
2074 printf ("Current directory is %s\n", dir);
2078 /* The user wishes to quit using this program. Just set DONE
2087 /* Function which tells you that you can't do this. */
2088 too_dangerous (caller)
2092 "%s: Too dangerous for me to distribute. Write it yourself.\n",
2096 /* Return non-zero if ARG is a valid argument for CALLER, else print
2097 an error message and return zero. */
2099 valid_argument (caller, arg)
2104 fprintf (stderr, "%s: Argument required.\n", caller);