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.)
6 This document describes the GNU Readline Library, a utility for aiding
7 in the consistency of user interface across discrete programs that need
8 to provide a command line interface.
10 Copyright (C) 1988--2012 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of
13 this manual provided the copyright notice and this permission notice
14 pare preserved on all copies.
17 Permission is granted to process this file through TeX and print the
18 results, provided the printed document carries copying permission
19 notice identical to this one except for the removal of this paragraph
20 (this paragraph not being relevant to the printed manual).
23 Permission is granted to copy and distribute modified versions of this
24 manual under the conditions for verbatim copying, provided that the entire
25 resulting derived work is distributed under the terms of a permission
26 notice identical to this one.
28 Permission is granted to copy and distribute translations of this manual
29 into another language, under the above conditions for modified versions,
30 except that this permission notice may be stated in a translation approved
34 @node Programming with GNU Readline
35 @chapter Programming with GNU Readline
37 This chapter describes the interface between the @sc{gnu} Readline Library and
38 other programs. If you are a programmer, and you wish to include the
39 features found in @sc{gnu} Readline
40 such as completion, line editing, and interactive history manipulation
41 in your own programs, this section is for you.
44 * Basic Behavior:: Using the default behavior of Readline.
45 * Custom Functions:: Adding your own functions to Readline.
46 * Readline Variables:: Variables accessible to custom
48 * Readline Convenience Functions:: Functions which Readline supplies to
49 aid in writing your own custom
51 * Readline Signal Handling:: How Readline behaves when it receives signals.
52 * Custom Completers:: Supplanting or supplementing Readline's
57 @section Basic Behavior
59 Many programs provide a command line interface, such as @code{mail},
60 @code{ftp}, and @code{sh}. For such programs, the default behaviour of
61 Readline is sufficient. This section describes how to use Readline in
62 the simplest way possible, perhaps to replace calls in your code to
63 @code{gets()} or @code{fgets()}.
66 @cindex readline, function
68 The function @code{readline()} prints a prompt @var{prompt}
69 and then reads and returns a single line of text from the user.
70 If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
71 The line @code{readline} returns is allocated with @code{malloc()};
72 the caller should @code{free()} the line when it has finished with it.
73 The declaration for @code{readline} in ANSI C is
76 @code{char *readline (const char *@var{prompt});}
82 @code{char *line = readline ("Enter a line: ");}
85 in order to read a line of text from the user.
86 The line returned has the final newline removed, so only the
89 If @code{readline} encounters an @code{EOF} while reading the line, and the
90 line is empty at that point, then @code{(char *)NULL} is returned.
91 Otherwise, the line is ended just as if a newline had been typed.
93 If you want the user to be able to get at the line later, (with
94 @key{C-p} for example), you must call @code{add_history()} to save the
95 line away in a @dfn{history} list of such lines.
98 @code{add_history (line)};
102 For full details on the GNU History Library, see the associated manual.
104 It is preferable to avoid saving empty lines on the history list, since
105 users rarely have a burning need to reuse a blank line. Here is
106 a function which usefully replaces the standard @code{gets()} library
107 function, and has the advantage of no static buffer to overflow:
110 /* A static variable for holding the line. */
111 static char *line_read = (char *)NULL;
113 /* Read a string, and return a pointer to it.
114 Returns NULL on EOF. */
118 /* If the buffer has already been allocated,
119 return the memory to the free pool. */
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,
130 save it on the history. */
131 if (line_read && *line_read)
132 add_history (line_read);
138 This function gives the user the default behaviour of @key{TAB}
139 completion: completion on file names. If you do not want Readline to
140 complete on filenames, you can change the binding of the @key{TAB} key
141 with @code{rl_bind_key()}.
144 @code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
147 @code{rl_bind_key()} takes two arguments: @var{key} is the character that
148 you want to bind, and @var{function} is the address of the function to
149 call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()}
150 makes @key{TAB} insert itself.
151 @code{rl_bind_key()} returns non-zero if @var{key} is not a valid
152 ASCII character code (between 0 and 255).
154 Thus, to disable the default @key{TAB} behavior, the following suffices:
156 @code{rl_bind_key ('\t', rl_insert);}
159 This code should be executed once at the start of your program; you
160 might write a function called @code{initialize_readline()} which
161 performs this and other desired initializations, such as installing
162 custom completers (@pxref{Custom Completers}).
164 @node Custom Functions
165 @section Custom Functions
167 Readline provides many functions for manipulating the text of
168 the line, but it isn't possible to anticipate the needs of all
169 programs. This section describes the various functions and variables
170 defined within the Readline library which allow a user program to add
171 customized functionality to Readline.
173 Before declaring any functions that customize Readline's behavior, or
174 using any functionality Readline provides in other code, an
175 application writer should include the file @code{<readline/readline.h>}
176 in any file that uses Readline's features. Since some of the definitions
177 in @code{readline.h} use the @code{stdio} library, the file
178 @code{<stdio.h>} should be included before @code{readline.h}.
180 @code{readline.h} defines a C preprocessor variable that should
181 be treated as an integer, @code{RL_READLINE_VERSION}, which may
182 be used to conditionally compile application code depending on
183 the installed Readline version. The value is a hexadecimal
184 encoding of the major and minor version numbers of the library,
185 of the form 0x@var{MMmm}. @var{MM} is the two-digit major
186 version number; @var{mm} is the two-digit minor version number.
187 For Readline 4.2, for example, the value of
188 @code{RL_READLINE_VERSION} would be @code{0x0402}.
191 * Readline Typedefs:: C declarations to make code readable.
192 * Function Writing:: Variables and calling conventions.
195 @node Readline Typedefs
196 @subsection Readline Typedefs
198 For readabilty, we declare a number of new object types, all pointers
201 The reason for declaring these new types is to make it easier to write
202 code describing pointers to C functions with appropriately prototyped
203 arguments and return values.
205 For instance, say we want to declare a variable @var{func} as a pointer
206 to a function which takes two @code{int} arguments and returns an
207 @code{int} (this is the type of all of the Readline bindable functions).
208 Instead of the classic C declaration
210 @code{int (*func)();}
213 or the ANSI-C style declaration
215 @code{int (*func)(int, int);}
220 @code{rl_command_func_t *func;}
222 The full list of function pointer types available is
225 @item typedef int rl_command_func_t (int, int);
227 @item typedef char *rl_compentry_func_t (const char *, int);
229 @item typedef char **rl_completion_func_t (const char *, int, int);
231 @item typedef char *rl_quote_func_t (char *, int, char *);
233 @item typedef char *rl_dequote_func_t (char *, int);
235 @item typedef int rl_compignore_func_t (char **);
237 @item typedef void rl_compdisp_func_t (char **, int, int);
239 @item typedef int rl_hook_func_t (void);
241 @item typedef int rl_getc_func_t (FILE *);
243 @item typedef int rl_linebuf_func_t (char *, int);
245 @item typedef int rl_intfunc_t (int);
246 @item #define rl_ivoidfunc_t rl_hook_func_t
247 @item typedef int rl_icpfunc_t (char *);
248 @item typedef int rl_icppfunc_t (char **);
250 @item typedef void rl_voidfunc_t (void);
251 @item typedef void rl_vintfunc_t (int);
252 @item typedef void rl_vcpfunc_t (char *);
253 @item typedef void rl_vcppfunc_t (char **);
257 @node Function Writing
258 @subsection Writing a New Function
260 In order to write new functions for Readline, you need to know the
261 calling conventions for keyboard-invoked functions, and the names of the
262 variables that describe the current state of the line read so far.
264 The calling sequence for a command @code{foo} looks like
267 @code{int foo (int count, int key)}
271 where @var{count} is the numeric argument (or 1 if defaulted) and
272 @var{key} is the key that invoked this function.
274 It is completely up to the function as to what should be done with the
275 numeric argument. Some functions use it as a repeat count, some
276 as a flag, and others to choose alternate behavior (refreshing the current
277 line as opposed to refreshing the screen, for example). Some choose to
278 ignore it. In general, if a
279 function uses the numeric argument as a repeat count, it should be able
280 to do something useful with both negative and positive arguments.
281 At the very least, it should be aware that it can be passed a
284 A command function should return 0 if its action completes successfully,
285 and a non-zero value if some error occurs.
286 This is the convention obeyed by all of the builtin Readline bindable
289 @node Readline Variables
290 @section Readline Variables
292 These variables are available to function writers.
294 @deftypevar {char *} rl_line_buffer
295 This is the line gathered so far. You are welcome to modify the
296 contents of the line, but see @ref{Allowing Undoing}. The
297 function @code{rl_extend_line_buffer} is available to increase
298 the memory allocated to @code{rl_line_buffer}.
301 @deftypevar int rl_point
302 The offset of the current cursor position in @code{rl_line_buffer}
306 @deftypevar int rl_end
307 The number of characters present in @code{rl_line_buffer}. When
308 @code{rl_point} is at the end of the line, @code{rl_point} and
309 @code{rl_end} are equal.
312 @deftypevar int rl_mark
313 The @var{mark} (saved position) in the current line. If set, the mark
314 and point define a @emph{region}.
317 @deftypevar int rl_done
318 Setting this to a non-zero value causes Readline to return the current
322 @deftypevar int rl_num_chars_to_read
323 Setting this to a positive value before calling @code{readline()} causes
324 Readline to return after accepting that many characters, rather
325 than reading up to a character bound to @code{accept-line}.
328 @deftypevar int rl_pending_input
329 Setting this to a value makes it the next keystroke read. This is a
330 way to stuff a single character into the input stream.
333 @deftypevar int rl_dispatching
334 Set to a non-zero value if a function is being called from a key binding;
335 zero otherwise. Application functions can test this to discover whether
336 they were called directly or by Readline's dispatching mechanism.
339 @deftypevar int rl_erase_empty_line
340 Setting this to a non-zero value causes Readline to completely erase
341 the current line, including any prompt, any time a newline is typed as
342 the only character on an otherwise-empty line. The cursor is moved to
343 the beginning of the newly-blank line.
346 @deftypevar {char *} rl_prompt
347 The prompt Readline uses. This is set from the argument to
348 @code{readline()}, and should not be assigned to directly.
349 The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
350 be used to modify the prompt string after calling @code{readline()}.
353 @deftypevar {char *} rl_display_prompt
354 The string displayed as the prompt. This is usually identical to
355 @var{rl_prompt}, but may be changed temporarily by functions that
356 use the prompt string as a message area, such as incremental search.
359 @deftypevar int rl_already_prompted
360 If an application wishes to display the prompt itself, rather than have
361 Readline do it the first time @code{readline()} is called, it should set
362 this variable to a non-zero value after displaying the prompt.
363 The prompt must also be passed as the argument to @code{readline()} so
364 the redisplay functions can update the display properly.
365 The calling application is responsible for managing the value; Readline
369 @deftypevar {const char *} rl_library_version
370 The version number of this revision of the library.
373 @deftypevar int rl_readline_version
374 An integer encoding the current version of the library. The encoding is
375 of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
376 number, and @var{mm} is the two-digit minor version number.
377 For example, for Readline-4.2, @code{rl_readline_version} would have the
381 @deftypevar {int} rl_gnu_readline_p
382 Always set to 1, denoting that this is @sc{gnu} readline rather than some
386 @deftypevar {const char *} rl_terminal_name
387 The terminal type, used for initialization. If not set by the application,
388 Readline sets this to the value of the @env{TERM} environment variable
389 the first time it is called.
392 @deftypevar {const char *} rl_readline_name
393 This variable is set to a unique name by each application using Readline.
394 The value allows conditional parsing of the inputrc file
395 (@pxref{Conditional Init Constructs}).
398 @deftypevar {FILE *} rl_instream
399 The stdio stream from which Readline reads input.
400 If @code{NULL}, Readline defaults to @var{stdin}.
403 @deftypevar {FILE *} rl_outstream
404 The stdio stream to which Readline performs output.
405 If @code{NULL}, Readline defaults to @var{stdout}.
408 @deftypevar int rl_prefer_env_winsize
409 If non-zero, Readline gives values found in the @env{LINES} and
410 @env{COLUMNS} environment variables greater precedence than values fetched
411 from the kernel when computing the screen dimensions.
414 @deftypevar {rl_command_func_t *} rl_last_func
415 The address of the last command function Readline executed. May be used to
416 test whether or not a function is being executed twice in succession, for
420 @deftypevar {rl_hook_func_t *} rl_startup_hook
421 If non-zero, this is the address of a function to call just
422 before @code{readline} prints the first prompt.
425 @deftypevar {rl_hook_func_t *} rl_pre_input_hook
426 If non-zero, this is the address of a function to call after
427 the first prompt has been printed and just before @code{readline}
428 starts reading input characters.
431 @deftypevar {rl_hook_func_t *} rl_event_hook
432 If non-zero, this is the address of a function to call periodically
433 when Readline is waiting for terminal input.
434 By default, this will be called at most ten times a second if there
435 is no keyboard input.
438 @deftypevar {rl_getc_func_t *} rl_getc_function
439 If non-zero, Readline will call indirectly through this pointer
440 to get a character from the input stream. By default, it is set to
441 @code{rl_getc}, the default Readline character input function
442 (@pxref{Character Input}).
445 @deftypevar {rl_voidfunc_t *} rl_redisplay_function
446 If non-zero, Readline will call indirectly through this pointer
447 to update the display with the current contents of the editing buffer.
448 By default, it is set to @code{rl_redisplay}, the default Readline
449 redisplay function (@pxref{Redisplay}).
452 @deftypevar {rl_vintfunc_t *} rl_prep_term_function
453 If non-zero, Readline will call indirectly through this pointer
454 to initialize the terminal. The function takes a single argument, an
455 @code{int} flag that says whether or not to use eight-bit characters.
456 By default, this is set to @code{rl_prep_terminal}
457 (@pxref{Terminal Management}).
460 @deftypevar {rl_voidfunc_t *} rl_deprep_term_function
461 If non-zero, Readline will call indirectly through this pointer
462 to reset the terminal. This function should undo the effects of
463 @code{rl_prep_term_function}.
464 By default, this is set to @code{rl_deprep_terminal}
465 (@pxref{Terminal Management}).
468 @deftypevar {Keymap} rl_executing_keymap
469 This variable is set to the keymap (@pxref{Keymaps}) in which the
470 currently executing readline function was found.
473 @deftypevar {Keymap} rl_binding_keymap
474 This variable is set to the keymap (@pxref{Keymaps}) in which the
475 last key binding occurred.
478 @deftypevar {char *} rl_executing_macro
479 This variable is set to the text of any currently-executing macro.
482 @deftypevar int rl_executing_key
483 The key that caused the dispatch to the currently-executing Readline function.
486 @deftypevar {char *} rl_executing_keyseq
487 The full key sequence that caused the dispatch to the currently-executing
491 @deftypevar int rl_key_sequence_length
492 The number of characters in @var{rl_executing_keyseq}.
495 @deftypevar {int} rl_readline_state
496 A variable with bit values that encapsulate the current Readline state.
497 A bit is set with the @code{RL_SETSTATE} macro, and unset with the
498 @code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test
499 whether a particular state bit is set. Current state bits include:
503 Readline has not yet been called, nor has it begun to intialize.
504 @item RL_STATE_INITIALIZING
505 Readline is initializing its internal data structures.
506 @item RL_STATE_INITIALIZED
507 Readline has completed its initialization.
508 @item RL_STATE_TERMPREPPED
509 Readline has modified the terminal modes to do its own input and redisplay.
510 @item RL_STATE_READCMD
511 Readline is reading a command from the keyboard.
512 @item RL_STATE_METANEXT
513 Readline is reading more input after reading the meta-prefix character.
514 @item RL_STATE_DISPATCHING
515 Readline is dispatching to a command.
516 @item RL_STATE_MOREINPUT
517 Readline is reading more input while executing an editing command.
518 @item RL_STATE_ISEARCH
519 Readline is performing an incremental history search.
520 @item RL_STATE_NSEARCH
521 Readline is performing a non-incremental history search.
522 @item RL_STATE_SEARCH
523 Readline is searching backward or forward through the history for a string.
524 @item RL_STATE_NUMERICARG
525 Readline is reading a numeric argument.
526 @item RL_STATE_MACROINPUT
527 Readline is currently getting its input from a previously-defined keyboard
529 @item RL_STATE_MACRODEF
530 Readline is currently reading characters defining a keyboard macro.
531 @item RL_STATE_OVERWRITE
532 Readline is in overwrite mode.
533 @item RL_STATE_COMPLETING
534 Readline is performing word completion.
535 @item RL_STATE_SIGHANDLER
536 Readline is currently executing the readline signal handler.
537 @item RL_STATE_UNDOING
538 Readline is performing an undo.
539 @item RL_STATE_INPUTPENDING
540 Readline has input pending due to a call to @code{rl_execute_next()}.
541 @item RL_STATE_TTYCSAVED
542 Readline has saved the values of the terminal's special characters.
543 @item RL_STATE_CALLBACK
544 Readline is currently using the alternate (callback) interface
545 (@pxref{Alternate Interface}).
546 @item RL_STATE_VIMOTION
547 Readline is reading the argument to a vi-mode "motion" command.
548 @item RL_STATE_MULTIKEY
549 Readline is reading a multiple-keystroke command.
550 @item RL_STATE_VICMDONCE
551 Readline has entered vi command (movement) mode at least one time during
552 the current call to @code{readline()}.
554 Readline has read a key sequence bound to @code{accept-line}
555 and is about to return the line to the caller.
560 @deftypevar {int} rl_explicit_arg
561 Set to a non-zero value if an explicit numeric argument was specified by
562 the user. Only valid in a bindable command function.
565 @deftypevar {int} rl_numeric_arg
566 Set to the value of any numeric argument explicitly specified by the user
567 before executing the current Readline function. Only valid in a bindable
571 @deftypevar {int} rl_editing_mode
572 Set to a value denoting Readline's current editing mode. A value of
573 @var{1} means Readline is currently in emacs mode; @var{0}
574 means that vi mode is active.
578 @node Readline Convenience Functions
579 @section Readline Convenience Functions
582 * Function Naming:: How to give a function you write a name.
583 * Keymaps:: Making keymaps.
584 * Binding Keys:: Changing Keymaps.
585 * Associating Function Names and Bindings:: Translate function names to
587 * Allowing Undoing:: How to make your functions undoable.
588 * Redisplay:: Functions to control line display.
589 * Modifying Text:: Functions to modify @code{rl_line_buffer}.
590 * Character Input:: Functions to read keyboard input.
591 * Terminal Management:: Functions to manage terminal settings.
592 * Utility Functions:: Generally useful functions and hooks.
593 * Miscellaneous Functions:: Functions that don't fall into any category.
594 * Alternate Interface:: Using Readline in a `callback' fashion.
595 * A Readline Example:: An example Readline function.
598 @node Function Naming
599 @subsection Naming a Function
601 The user can dynamically change the bindings of keys while using
602 Readline. This is done by representing the function with a descriptive
603 name. The user is able to type the descriptive name when referring to
604 the function. Thus, in an init file, one might find
607 Meta-Rubout: backward-kill-word
610 This binds the keystroke @key{Meta-Rubout} to the function
611 @emph{descriptively} named @code{backward-kill-word}. You, as the
612 programmer, should bind the functions you write to descriptive names as
613 well. Readline provides a function for doing that:
615 @deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
616 Add @var{name} to the list of named functions. Make @var{function} be
617 the function that gets called. If @var{key} is not -1, then bind it to
618 @var{function} using @code{rl_bind_key()}.
621 Using this function alone is sufficient for most applications.
622 It is the recommended way to add a few functions to the default
623 functions that Readline has built in.
624 If you need to do something other than adding a function to Readline,
625 you may need to use the underlying functions described below.
628 @subsection Selecting a Keymap
630 Key bindings take place on a @dfn{keymap}. The keymap is the
631 association between the keys that the user types and the functions that
632 get run. You can make your own keymaps, copy existing keymaps, and tell
633 Readline which keymap to use.
635 @deftypefun Keymap rl_make_bare_keymap (void)
636 Returns a new, empty keymap. The space for the keymap is allocated with
637 @code{malloc()}; the caller should free it by calling
638 @code{rl_free_keymap()} when done.
641 @deftypefun Keymap rl_copy_keymap (Keymap map)
642 Return a new keymap which is a copy of @var{map}.
645 @deftypefun Keymap rl_make_keymap (void)
646 Return a new keymap with the printing characters bound to rl_insert,
647 the lowercase Meta characters bound to run their equivalents, and
648 the Meta digits bound to produce numeric arguments.
651 @deftypefun void rl_discard_keymap (Keymap keymap)
652 Free the storage associated with the data in @var{keymap}.
653 The caller should free @var{keymap}.
656 @deftypefun void rl_free_keymap (Keymap keymap)
657 Free all storage associated with @var{keymap}. This calls
658 @code{rl_discard_keymap} to free subordindate keymaps and macros.
661 Readline has several internal keymaps. These functions allow you to
662 change which keymap is active.
664 @deftypefun Keymap rl_get_keymap (void)
665 Returns the currently active keymap.
668 @deftypefun void rl_set_keymap (Keymap keymap)
669 Makes @var{keymap} the currently active keymap.
672 @deftypefun Keymap rl_get_keymap_by_name (const char *name)
673 Return the keymap matching @var{name}. @var{name} is one which would
674 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
677 @deftypefun {char *} rl_get_keymap_name (Keymap keymap)
678 Return the name matching @var{keymap}. @var{name} is one which would
679 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
683 @subsection Binding Keys
685 Key sequences are associate with functions through the keymap.
686 Readline has several internal keymaps: @code{emacs_standard_keymap},
687 @code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
688 @code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
689 @code{emacs_standard_keymap} is the default, and the examples in
690 this manual assume that.
692 Since @code{readline()} installs a set of default key bindings the first
693 time it is called, there is always the danger that a custom binding
694 installed before the first call to @code{readline()} will be overridden.
695 An alternate mechanism is to install custom key bindings in an
696 initialization function assigned to the @code{rl_startup_hook} variable
697 (@pxref{Readline Variables}).
699 These functions manage key bindings.
701 @deftypefun int rl_bind_key (int key, rl_command_func_t *function)
702 Binds @var{key} to @var{function} in the currently active keymap.
703 Returns non-zero in the case of an invalid @var{key}.
706 @deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
707 Bind @var{key} to @var{function} in @var{map}.
708 Returns non-zero in the case of an invalid @var{key}.
711 @deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function)
712 Binds @var{key} to @var{function} if it is not already bound in the
713 currently active keymap.
714 Returns non-zero in the case of an invalid @var{key} or if @var{key} is
718 @deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
719 Binds @var{key} to @var{function} if it is not already bound in @var{map}.
720 Returns non-zero in the case of an invalid @var{key} or if @var{key} is
724 @deftypefun int rl_unbind_key (int key)
725 Bind @var{key} to the null function in the currently active keymap.
726 Returns non-zero in case of error.
729 @deftypefun int rl_unbind_key_in_map (int key, Keymap map)
730 Bind @var{key} to the null function in @var{map}.
731 Returns non-zero in case of error.
734 @deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
735 Unbind all keys that execute @var{function} in @var{map}.
738 @deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
739 Unbind all keys that are bound to @var{command} in @var{map}.
742 @deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
743 Bind the key sequence represented by the string @var{keyseq} to the function
744 @var{function}, beginning in the current keymap.
745 This makes new keymaps as necessary.
746 The return value is non-zero if @var{keyseq} is invalid.
749 @deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
750 Bind the key sequence represented by the string @var{keyseq} to the function
751 @var{function}. This makes new keymaps as necessary.
752 Initial bindings are performed in @var{map}.
753 The return value is non-zero if @var{keyseq} is invalid.
756 @deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
757 Equivalent to @code{rl_bind_keyseq_in_map}.
760 @deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
761 Binds @var{keyseq} to @var{function} if it is not already bound in the
762 currently active keymap.
763 Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
767 @deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
768 Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
769 Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
773 @deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
774 Bind the key sequence represented by the string @var{keyseq} to the arbitrary
775 pointer @var{data}. @var{type} says what kind of data is pointed to by
776 @var{data}; this can be a function (@code{ISFUNC}), a macro
777 (@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
778 necessary. The initial keymap in which to do bindings is @var{map}.
781 @deftypefun int rl_parse_and_bind (char *line)
782 Parse @var{line} as if it had been read from the @code{inputrc} file and
783 perform any key bindings and variable assignments found
784 (@pxref{Readline Init File}).
787 @deftypefun int rl_read_init_file (const char *filename)
788 Read keybindings and variable assignments from @var{filename}
789 (@pxref{Readline Init File}).
792 @node Associating Function Names and Bindings
793 @subsection Associating Function Names and Bindings
795 These functions allow you to find out what keys invoke named functions
796 and the functions invoked by a particular key sequence. You may also
797 associate a new function name with an arbitrary function.
799 @deftypefun {rl_command_func_t *} rl_named_function (const char *name)
800 Return the function with name @var{name}.
803 @deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
804 Return the function invoked by @var{keyseq} in keymap @var{map}.
805 If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
806 not @code{NULL}, the type of the object is returned in the @code{int} variable
807 it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
810 @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
811 Return an array of strings representing the key sequences used to
812 invoke @var{function} in the current keymap.
815 @deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
816 Return an array of strings representing the key sequences used to
817 invoke @var{function} in the keymap @var{map}.
820 @deftypefun void rl_function_dumper (int readable)
821 Print the readline function names and the key sequences currently
822 bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
823 the list is formatted in such a way that it can be made part of an
824 @code{inputrc} file and re-read.
827 @deftypefun void rl_list_funmap_names (void)
828 Print the names of all bindable Readline functions to @code{rl_outstream}.
831 @deftypefun {const char **} rl_funmap_names (void)
832 Return a NULL terminated array of known function names. The array is
833 sorted. The array itself is allocated, but not the strings inside. You
834 should free the array, but not the pointers, using @code{free} or
835 @code{rl_free} when you are done.
838 @deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
839 Add @var{name} to the list of bindable Readline command names, and make
840 @var{function} the function to be called when @var{name} is invoked.
843 @node Allowing Undoing
844 @subsection Allowing Undoing
846 Supporting the undo command is a painless thing, and makes your
847 functions much more useful. It is certainly easy to try
848 something if you know you can undo it.
850 If your function simply inserts text once, or deletes text once, and
851 uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
852 undoing is already done for you automatically.
854 If you do multiple insertions or multiple deletions, or any combination
855 of these operations, you should group them together into one operation.
856 This is done with @code{rl_begin_undo_group()} and
857 @code{rl_end_undo_group()}.
859 The types of events that can be undone are:
862 enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
865 Notice that @code{UNDO_DELETE} means to insert some text, and
866 @code{UNDO_INSERT} means to delete some text. That is, the undo code
867 tells what to undo, not how to undo it. @code{UNDO_BEGIN} and
868 @code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
869 @code{rl_end_undo_group()}.
871 @deftypefun int rl_begin_undo_group (void)
872 Begins saving undo information in a group construct. The undo
873 information usually comes from calls to @code{rl_insert_text()} and
874 @code{rl_delete_text()}, but could be the result of calls to
875 @code{rl_add_undo()}.
878 @deftypefun int rl_end_undo_group (void)
879 Closes the current undo group started with @code{rl_begin_undo_group
880 ()}. There should be one call to @code{rl_end_undo_group()}
881 for each call to @code{rl_begin_undo_group()}.
884 @deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
885 Remember how to undo an event (according to @var{what}). The affected
886 text runs from @var{start} to @var{end}, and encompasses @var{text}.
889 @deftypefun void rl_free_undo_list (void)
890 Free the existing undo list.
893 @deftypefun int rl_do_undo (void)
894 Undo the first thing on the undo list. Returns @code{0} if there was
895 nothing to undo, non-zero if something was undone.
898 Finally, if you neither insert nor delete text, but directly modify the
899 existing text (e.g., change its case), call @code{rl_modifying()}
900 once, just before you modify the text. You must supply the indices of
901 the text range that you are going to modify.
903 @deftypefun int rl_modifying (int start, int end)
904 Tell Readline to save the text between @var{start} and @var{end} as a
905 single undo unit. It is assumed that you will subsequently modify
910 @subsection Redisplay
912 @deftypefun void rl_redisplay (void)
913 Change what's displayed on the screen to reflect the current contents
914 of @code{rl_line_buffer}.
917 @deftypefun int rl_forced_update_display (void)
918 Force the line to be updated and redisplayed, whether or not
919 Readline thinks the screen display is correct.
922 @deftypefun int rl_on_new_line (void)
923 Tell the update functions that we have moved onto a new (empty) line,
924 usually after ouputting a newline.
927 @deftypefun int rl_on_new_line_with_prompt (void)
928 Tell the update functions that we have moved onto a new line, with
929 @var{rl_prompt} already displayed.
930 This could be used by applications that want to output the prompt string
931 themselves, but still need Readline to know the prompt string length for
933 It should be used after setting @var{rl_already_prompted}.
936 @deftypefun int rl_reset_line_state (void)
937 Reset the display state to a clean state and redisplay the current line
938 starting on a new line.
941 @deftypefun int rl_crlf (void)
942 Move the cursor to the start of the next screen line.
945 @deftypefun int rl_show_char (int c)
946 Display character @var{c} on @code{rl_outstream}.
947 If Readline has not been set to display meta characters directly, this
948 will convert meta characters to a meta-prefixed key sequence.
949 This is intended for use by applications which wish to do their own
953 @deftypefun int rl_message (const char *, @dots{})
954 The arguments are a format string as would be supplied to @code{printf},
955 possibly containing conversion specifications such as @samp{%d}, and
956 any additional arguments necessary to satisfy the conversion specifications.
957 The resulting string is displayed in the @dfn{echo area}. The echo area
958 is also used to display numeric arguments and search strings.
959 You should call @code{rl_save_prompt} to save the prompt information
960 before calling this function.
963 @deftypefun int rl_clear_message (void)
964 Clear the message in the echo area. If the prompt was saved with a call to
965 @code{rl_save_prompt} before the last call to @code{rl_message},
966 call @code{rl_restore_prompt} before calling this function.
969 @deftypefun void rl_save_prompt (void)
970 Save the local Readline prompt display state in preparation for
971 displaying a new message in the message area with @code{rl_message()}.
974 @deftypefun void rl_restore_prompt (void)
975 Restore the local Readline prompt display state saved by the most
976 recent call to @code{rl_save_prompt}.
977 if @code{rl_save_prompt} was called to save the prompt before a call
978 to @code{rl_message}, this function should be called before the
979 corresponding call to @code{rl_clear_message}.
982 @deftypefun int rl_expand_prompt (char *prompt)
983 Expand any special character sequences in @var{prompt} and set up the
984 local Readline prompt redisplay variables.
985 This function is called by @code{readline()}. It may also be called to
986 expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
987 function or @code{rl_already_prompted} variable is used.
988 It returns the number of visible characters on the last line of the
989 (possibly multi-line) prompt.
990 Applications may indicate that the prompt contains characters that take
991 up no physical screen space when displayed by bracketing a sequence of
992 such characters with the special markers @code{RL_PROMPT_START_IGNORE}
993 and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}. This may
994 be used to embed terminal-specific escape sequences in prompts.
997 @deftypefun int rl_set_prompt (const char *prompt)
998 Make Readline use @var{prompt} for subsequent redisplay. This calls
999 @code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
1003 @node Modifying Text
1004 @subsection Modifying Text
1006 @deftypefun int rl_insert_text (const char *text)
1007 Insert @var{text} into the line at the current cursor position.
1008 Returns the number of characters inserted.
1011 @deftypefun int rl_delete_text (int start, int end)
1012 Delete the text between @var{start} and @var{end} in the current line.
1013 Returns the number of characters deleted.
1016 @deftypefun {char *} rl_copy_text (int start, int end)
1017 Return a copy of the text between @var{start} and @var{end} in
1021 @deftypefun int rl_kill_text (int start, int end)
1022 Copy the text between @var{start} and @var{end} in the current line
1023 to the kill ring, appending or prepending to the last kill if the
1024 last command was a kill command. The text is deleted.
1025 If @var{start} is less than @var{end},
1026 the text is appended, otherwise prepended. If the last command was
1027 not a kill, a new kill ring slot is used.
1030 @deftypefun int rl_push_macro_input (char *macro)
1031 Cause @var{macro} to be inserted into the line, as if it had been invoked
1032 by a key bound to a macro. Not especially useful; use
1033 @code{rl_insert_text()} instead.
1036 @node Character Input
1037 @subsection Character Input
1039 @deftypefun int rl_read_key (void)
1040 Return the next character available from Readline's current input stream.
1041 This handles input inserted into
1042 the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
1043 and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
1044 While waiting for input, this function will call any function assigned to
1045 the @code{rl_event_hook} variable.
1048 @deftypefun int rl_getc (FILE *stream)
1049 Return the next character available from @var{stream}, which is assumed to
1053 @deftypefun int rl_stuff_char (int c)
1054 Insert @var{c} into the Readline input stream. It will be "read"
1055 before Readline attempts to read characters from the terminal with
1056 @code{rl_read_key()}. Up to 512 characters may be pushed back.
1057 @code{rl_stuff_char} returns 1 if the character was successfully inserted;
1061 @deftypefun int rl_execute_next (int c)
1062 Make @var{c} be the next command to be executed when @code{rl_read_key()}
1063 is called. This sets @var{rl_pending_input}.
1066 @deftypefun int rl_clear_pending_input (void)
1067 Unset @var{rl_pending_input}, effectively negating the effect of any
1068 previous call to @code{rl_execute_next()}. This works only if the
1069 pending input has not already been read with @code{rl_read_key()}.
1072 @deftypefun int rl_set_keyboard_input_timeout (int u)
1073 While waiting for keyboard input in @code{rl_read_key()}, Readline will
1074 wait for @var{u} microseconds for input before calling any function
1075 assigned to @code{rl_event_hook}. @var{u} must be greater than or equal
1076 to zero (a zero-length timeout is equivalent to a poll).
1077 The default waiting period is one-tenth of a second.
1078 Returns the old timeout value.
1081 @node Terminal Management
1082 @subsection Terminal Management
1084 @deftypefun void rl_prep_terminal (int meta_flag)
1085 Modify the terminal settings for Readline's use, so @code{readline()}
1086 can read a single character at a time from the keyboard.
1087 The @var{meta_flag} argument should be non-zero if Readline should
1088 read eight-bit input.
1091 @deftypefun void rl_deprep_terminal (void)
1092 Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
1093 the state in which it was before the most recent call to
1094 @code{rl_prep_terminal()}.
1097 @deftypefun void rl_tty_set_default_bindings (Keymap kmap)
1098 Read the operating system's terminal editing characters (as would be
1099 displayed by @code{stty}) to their Readline equivalents.
1100 The bindings are performed in @var{kmap}.
1103 @deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
1104 Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
1105 that the terminal editing characters are bound to @code{rl_insert}.
1106 The bindings are performed in @var{kmap}.
1109 @deftypefun int rl_reset_terminal (const char *terminal_name)
1110 Reinitialize Readline's idea of the terminal settings using
1111 @var{terminal_name} as the terminal type (e.g., @code{vt100}).
1112 If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
1113 environment variable is used.
1116 @node Utility Functions
1117 @subsection Utility Functions
1119 @deftypefun int rl_save_state (struct readline_state *sp)
1120 Save a snapshot of Readline's internal state to @var{sp}.
1121 The contents of the @var{readline_state} structure are documented
1122 in @file{readline.h}.
1123 The caller is responsible for allocating the structure.
1126 @deftypefun int rl_restore_state (struct readline_state *sp)
1127 Restore Readline's internal state to that stored in @var{sp}, which must
1128 have been saved by a call to @code{rl_save_state}.
1129 The contents of the @var{readline_state} structure are documented
1130 in @file{readline.h}.
1131 The caller is responsible for freeing the structure.
1134 @deftypefun void rl_free (void *mem)
1135 Deallocate the memory pointed to by @var{mem}. @var{mem} must have been
1136 allocated by @code{malloc}.
1139 @deftypefun void rl_replace_line (const char *text, int clear_undo)
1140 Replace the contents of @code{rl_line_buffer} with @var{text}.
1141 The point and mark are preserved, if possible.
1142 If @var{clear_undo} is non-zero, the undo list associated with the
1143 current line is cleared.
1146 @deftypefun void rl_extend_line_buffer (int len)
1147 Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
1148 characters, possibly reallocating it if necessary.
1151 @deftypefun int rl_initialize (void)
1152 Initialize or re-initialize Readline's internal state.
1153 It's not strictly necessary to call this; @code{readline()} calls it before
1157 @deftypefun int rl_ding (void)
1158 Ring the terminal bell, obeying the setting of @code{bell-style}.
1161 @deftypefun int rl_alphabetic (int c)
1162 Return 1 if @var{c} is an alphabetic character.
1165 @deftypefun void rl_display_match_list (char **matches, int len, int max)
1166 A convenience function for displaying a list of strings in
1167 columnar format on Readline's output stream. @code{matches} is the list
1168 of strings, in argv format, such as a list of completion matches.
1169 @code{len} is the number of strings in @code{matches}, and @code{max}
1170 is the length of the longest string in @code{matches}. This function uses
1171 the setting of @code{print-completions-horizontally} to select how the
1172 matches are displayed (@pxref{Readline Init File Syntax}).
1173 When displaying completions, this function sets the number of columns used
1174 for display to the value of @code{completion-display-width}, the value of
1175 the environment variable @env{COLUMNS}, or the screen width, in that order.
1178 The following are implemented as macros, defined in @code{chardefs.h}.
1179 Applications should refrain from using them.
1181 @deftypefun int _rl_uppercase_p (int c)
1182 Return 1 if @var{c} is an uppercase alphabetic character.
1185 @deftypefun int _rl_lowercase_p (int c)
1186 Return 1 if @var{c} is a lowercase alphabetic character.
1189 @deftypefun int _rl_digit_p (int c)
1190 Return 1 if @var{c} is a numeric character.
1193 @deftypefun int _rl_to_upper (int c)
1194 If @var{c} is a lowercase alphabetic character, return the corresponding
1195 uppercase character.
1198 @deftypefun int _rl_to_lower (int c)
1199 If @var{c} is an uppercase alphabetic character, return the corresponding
1200 lowercase character.
1203 @deftypefun int _rl_digit_value (int c)
1204 If @var{c} is a number, return the value it represents.
1207 @node Miscellaneous Functions
1208 @subsection Miscellaneous Functions
1210 @deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
1211 Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
1212 The binding is performed in @var{map}. When @var{keyseq} is invoked, the
1213 @var{macro} will be inserted into the line. This function is deprecated;
1214 use @code{rl_generic_bind()} instead.
1217 @deftypefun void rl_macro_dumper (int readable)
1218 Print the key sequences bound to macros and their values, using
1219 the current keymap, to @code{rl_outstream}.
1220 If @var{readable} is non-zero, the list is formatted in such a way
1221 that it can be made part of an @code{inputrc} file and re-read.
1224 @deftypefun int rl_variable_bind (const char *variable, const char *value)
1225 Make the Readline variable @var{variable} have @var{value}.
1226 This behaves as if the readline command
1227 @samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
1228 file (@pxref{Readline Init File Syntax}).
1231 @deftypefun {char *} rl_variable_value (const char *variable)
1232 Return a string representing the value of the Readline variable @var{variable}.
1233 For boolean variables, this string is either @samp{on} or @samp{off}.
1236 @deftypefun void rl_variable_dumper (int readable)
1237 Print the readline variable names and their current values
1238 to @code{rl_outstream}.
1239 If @var{readable} is non-zero, the list is formatted in such a way
1240 that it can be made part of an @code{inputrc} file and re-read.
1243 @deftypefun int rl_set_paren_blink_timeout (int u)
1244 Set the time interval (in microseconds) that Readline waits when showing
1245 a balancing character when @code{blink-matching-paren} has been enabled.
1248 @deftypefun {char *} rl_get_termcap (const char *cap)
1249 Retrieve the string value of the termcap capability @var{cap}.
1250 Readline fetches the termcap entry for the current terminal name and
1251 uses those capabilities to move around the screen line and perform other
1252 terminal-specific operations, like erasing a line. Readline does not
1253 use all of a terminal's capabilities, and this function will return
1254 values for only those capabilities Readline uses.
1257 @deftypefun {void} rl_clear_history (void)
1258 Clear the history list by deleting all of the entries, in the same manner
1259 as the History library's @code{clear_history()} function.
1260 This differs from @code{clear_history} because it frees private data
1261 Readline saves in the history list.
1264 @node Alternate Interface
1265 @subsection Alternate Interface
1267 An alternate interface is available to plain @code{readline()}. Some
1268 applications need to interleave keyboard I/O with file, device, or
1269 window system I/O, typically by using a main loop to @code{select()}
1270 on various file descriptors. To accomodate this need, readline can
1271 also be invoked as a `callback' function from an event loop. There
1272 are functions available to make this easy.
1274 @deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
1275 Set up the terminal for readline I/O and display the initial
1276 expanded value of @var{prompt}. Save the value of @var{lhandler} to
1277 use as a function to call when a complete line of input has been entered.
1278 The function takes the text of the line as an argument.
1281 @deftypefun void rl_callback_read_char (void)
1282 Whenever an application determines that keyboard input is available, it
1283 should call @code{rl_callback_read_char()}, which will read the next
1284 character from the current input source.
1285 If that character completes the line, @code{rl_callback_read_char} will
1286 invoke the @var{lhandler} function saved by @code{rl_callback_handler_install}
1287 to process the line.
1288 Before calling the @var{lhandler} function, the terminal settings are
1289 reset to the values they had before calling
1290 @code{rl_callback_handler_install}.
1291 If the @var{lhandler} function returns,
1292 the terminal settings are modified for Readline's use again.
1293 @code{EOF} is indicated by calling @var{lhandler} with a
1297 @deftypefun void rl_callback_handler_remove (void)
1298 Restore the terminal to its initial state and remove the line handler.
1299 This may be called from within a callback as well as independently.
1300 If the @var{lhandler} installed by @code{rl_callback_handler_install}
1301 does not exit the program, either this function or the function referred
1302 to by the value of @code{rl_deprep_term_function} should be called before
1303 the program exits to reset the terminal settings.
1306 @node A Readline Example
1307 @subsection A Readline Example
1309 Here is a function which changes lowercase characters to their uppercase
1310 equivalents, and uppercase characters to lowercase. If
1311 this function was bound to @samp{M-c}, then typing @samp{M-c} would
1312 change the case of the character under point. Typing @samp{M-1 0 M-c}
1313 would change the case of the following 10 characters, leaving the cursor on
1314 the last character changed.
1317 /* Invert the case of the COUNT following characters. */
1319 invert_case_line (count, key)
1322 register int start, end, i;
1326 if (rl_point >= rl_end)
1337 /* Find the end of the range to modify. */
1338 end = start + (count * direction);
1340 /* Force it to be within range. */
1356 /* Tell readline that we are modifying the line,
1357 so it will save the undo information. */
1358 rl_modifying (start, end);
1360 for (i = start; i != end; i++)
1362 if (_rl_uppercase_p (rl_line_buffer[i]))
1363 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
1364 else if (_rl_lowercase_p (rl_line_buffer[i]))
1365 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
1367 /* Move point to on top of the last character changed. */
1368 rl_point = (direction == 1) ? end - 1 : start;
1373 @node Readline Signal Handling
1374 @section Readline Signal Handling
1376 Signals are asynchronous events sent to a process by the Unix kernel,
1377 sometimes on behalf of another process. They are intended to indicate
1378 exceptional events, like a user pressing the interrupt key on his terminal,
1379 or a network connection being broken. There is a class of signals that can
1380 be sent to the process currently reading input from the keyboard. Since
1381 Readline changes the terminal attributes when it is called, it needs to
1382 perform special processing when such a signal is received in order to
1383 restore the terminal to a sane state, or provide application writers with
1384 functions to do so manually.
1386 Readline contains an internal signal handler that is installed for a
1387 number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
1389 @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
1390 When one of these signals is received, the signal handler
1391 will reset the terminal attributes to those that were in effect before
1392 @code{readline()} was called, reset the signal handling to what it was
1393 before @code{readline()} was called, and resend the signal to the calling
1395 If and when the calling application's signal handler returns, Readline
1396 will reinitialize the terminal and continue to accept input.
1397 When a @code{SIGINT} is received, the Readline signal handler performs
1398 some additional work, which will cause any partially-entered line to be
1399 aborted (see the description of @code{rl_free_line_state()} below).
1401 There is an additional Readline signal handler, for @code{SIGWINCH}, which
1402 the kernel sends to a process whenever the terminal's size changes (for
1403 example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
1404 handler updates Readline's internal screen size information, and then calls
1405 any @code{SIGWINCH} signal handler the calling application has installed.
1406 Readline calls the application's @code{SIGWINCH} signal handler without
1407 resetting the terminal to its original state. If the application's signal
1408 handler does more than update its idea of the terminal size and return (for
1409 example, a @code{longjmp} back to a main processing loop), it @emph{must}
1410 call @code{rl_cleanup_after_signal()} (described below), to restore the
1413 Readline provides two variables that allow application writers to
1414 control whether or not it will catch certain signals and act on them
1415 when they are received. It is important that applications change the
1416 values of these variables only when calling @code{readline()}, not in
1417 a signal handler, so Readline's internal signal state is not corrupted.
1419 @deftypevar int rl_catch_signals
1420 If this variable is non-zero, Readline will install signal handlers for
1421 @code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
1422 @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
1424 The default value of @code{rl_catch_signals} is 1.
1427 @deftypevar int rl_catch_sigwinch
1428 If this variable is non-zero, Readline will install a signal handler for
1431 The default value of @code{rl_catch_sigwinch} is 1.
1434 If an application does not wish to have Readline catch any signals, or
1435 to handle signals other than those Readline catches (@code{SIGHUP},
1437 Readline provides convenience functions to do the necessary terminal
1438 and internal state cleanup upon receipt of a signal.
1440 @deftypefun void rl_cleanup_after_signal (void)
1441 This function will reset the state of the terminal to what it was before
1442 @code{readline()} was called, and remove the Readline signal handlers for
1443 all signals, depending on the values of @code{rl_catch_signals} and
1444 @code{rl_catch_sigwinch}.
1447 @deftypefun void rl_free_line_state (void)
1448 This will free any partial state associated with the current input line
1449 (undo information, any partial history entry, any partially-entered
1450 keyboard macro, and any partially-entered numeric argument). This
1451 should be called before @code{rl_cleanup_after_signal()}. The
1452 Readline signal handler for @code{SIGINT} calls this to abort the
1456 @deftypefun void rl_reset_after_signal (void)
1457 This will reinitialize the terminal and reinstall any Readline signal
1458 handlers, depending on the values of @code{rl_catch_signals} and
1459 @code{rl_catch_sigwinch}.
1462 If an application does not wish Readline to catch @code{SIGWINCH}, it may
1463 call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
1464 Readline to update its idea of the terminal size when a @code{SIGWINCH}
1467 @deftypefun void rl_echo_signal_char (int sig)
1468 If an application wishes to install its own signal handlers, but still
1469 have readline display characters that generate signals, calling this
1470 function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or
1471 @code{SIGTSTP} will display the character generating that signal.
1474 @deftypefun void rl_resize_terminal (void)
1475 Update Readline's internal screen size by reading values from the kernel.
1478 @deftypefun void rl_set_screen_size (int rows, int cols)
1479 Set Readline's idea of the terminal size to @var{rows} rows and
1480 @var{cols} columns. If either @var{rows} or @var{columns} is less than
1481 or equal to 0, Readline's idea of that terminal dimension is unchanged.
1484 If an application does not want to install a @code{SIGWINCH} handler, but
1485 is still interested in the screen dimensions, Readline's idea of the screen
1486 size may be queried.
1488 @deftypefun void rl_get_screen_size (int *rows, int *cols)
1489 Return Readline's idea of the terminal's size in the
1490 variables pointed to by the arguments.
1493 @deftypefun void rl_reset_screen_size (void)
1494 Cause Readline to reobtain the screen size and recalculate its dimensions.
1497 The following functions install and remove Readline's signal handlers.
1499 @deftypefun int rl_set_signals (void)
1500 Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
1501 @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
1502 @code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
1503 @code{rl_catch_signals} and @code{rl_catch_sigwinch}.
1506 @deftypefun int rl_clear_signals (void)
1507 Remove all of the Readline signal handlers installed by
1508 @code{rl_set_signals()}.
1511 @node Custom Completers
1512 @section Custom Completers
1513 @cindex application-specific completion functions
1515 Typically, a program that reads commands from the user has a way of
1516 disambiguating commands and data. If your program is one of these, then
1517 it can provide completion for commands, data, or both.
1518 The following sections describe how your program and Readline
1519 cooperate to provide this service.
1522 * How Completing Works:: The logic used to do completion.
1523 * Completion Functions:: Functions provided by Readline.
1524 * Completion Variables:: Variables which control completion.
1525 * A Short Completion Example:: An example of writing completer subroutines.
1528 @node How Completing Works
1529 @subsection How Completing Works
1531 In order to complete some text, the full list of possible completions
1532 must be available. That is, it is not possible to accurately
1533 expand a partial word without knowing all of the possible words
1534 which make sense in that context. The Readline library provides
1535 the user interface to completion, and two of the most common
1536 completion functions: filename and username. For completing other types
1537 of text, you must write your own completion function. This section
1538 describes exactly what such functions must do, and provides an example.
1540 There are three major functions used to perform completion:
1544 The user-interface function @code{rl_complete()}. This function is
1545 called with the same arguments as other bindable Readline functions:
1546 @var{count} and @var{invoking_key}.
1547 It isolates the word to be completed and calls
1548 @code{rl_completion_matches()} to generate a list of possible completions.
1549 It then either lists the possible completions, inserts the possible
1550 completions, or actually performs the
1551 completion, depending on which behavior is desired.
1554 The internal function @code{rl_completion_matches()} uses an
1555 application-supplied @dfn{generator} function to generate the list of
1556 possible matches, and then returns the array of these matches.
1557 The caller should place the address of its generator function in
1558 @code{rl_completion_entry_function}.
1561 The generator function is called repeatedly from
1562 @code{rl_completion_matches()}, returning a string each time. The
1563 arguments to the generator function are @var{text} and @var{state}.
1564 @var{text} is the partial word to be completed. @var{state} is zero the
1565 first time the function is called, allowing the generator to perform
1566 any necessary initialization, and a positive non-zero integer for
1567 each subsequent call. The generator function returns
1568 @code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
1569 no more possibilities left. Usually the generator function computes the
1570 list of possible completions when @var{state} is zero, and returns them
1571 one at a time on subsequent calls. Each string the generator function
1572 returns as a match must be allocated with @code{malloc()}; Readline
1573 frees the strings when it has finished with them.
1574 Such a generator function is referred to as an
1575 @dfn{application-specific completion function}.
1579 @deftypefun int rl_complete (int ignore, int invoking_key)
1580 Complete the word at or before point. You have supplied the function
1581 that does the initial simple matching selection algorithm (see
1582 @code{rl_completion_matches()}). The default is to do filename completion.
1585 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1586 This is a pointer to the generator function for
1587 @code{rl_completion_matches()}.
1588 If the value of @code{rl_completion_entry_function} is
1589 @code{NULL} then the default filename generator
1590 function, @code{rl_filename_completion_function()}, is used.
1591 An @dfn{application-specific completion function} is a function whose
1592 address is assigned to @code{rl_completion_entry_function} and whose
1593 return values are used to generate possible completions.
1596 @node Completion Functions
1597 @subsection Completion Functions
1599 Here is the complete list of callable completion functions present in
1602 @deftypefun int rl_complete_internal (int what_to_do)
1603 Complete the word at or before point. @var{what_to_do} says what to do
1604 with the completion. A value of @samp{?} means list the possible
1605 completions. @samp{TAB} means do standard completion. @samp{*} means
1606 insert all of the possible completions. @samp{!} means to display
1607 all of the possible completions, if there is more than one, as well as
1608 performing partial completion. @samp{@@} is similar to @samp{!}, but
1609 possible completions are not listed if the possible completions share
1613 @deftypefun int rl_complete (int ignore, int invoking_key)
1614 Complete the word at or before point. You have supplied the function
1615 that does the initial simple matching selection algorithm (see
1616 @code{rl_completion_matches()} and @code{rl_completion_entry_function}).
1617 The default is to do filename
1618 completion. This calls @code{rl_complete_internal()} with an
1619 argument depending on @var{invoking_key}.
1622 @deftypefun int rl_possible_completions (int count, int invoking_key)
1623 List the possible completions. See description of @code{rl_complete
1624 ()}. This calls @code{rl_complete_internal()} with an argument of
1628 @deftypefun int rl_insert_completions (int count, int invoking_key)
1629 Insert the list of possible completions into the line, deleting the
1630 partially-completed word. See description of @code{rl_complete()}.
1631 This calls @code{rl_complete_internal()} with an argument of @samp{*}.
1634 @deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
1635 Returns the apppriate value to pass to @code{rl_complete_internal()}
1636 depending on whether @var{cfunc} was called twice in succession and
1637 the values of the @code{show-all-if-ambiguous} and
1638 @code{show-all-if-unmodified} variables.
1639 Application-specific completion functions may use this function to present
1640 the same interface as @code{rl_complete()}.
1643 @deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
1644 Returns an array of strings which is a list of completions for
1645 @var{text}. If there are no completions, returns @code{NULL}.
1646 The first entry in the returned array is the substitution for @var{text}.
1647 The remaining entries are the possible completions. The array is
1648 terminated with a @code{NULL} pointer.
1650 @var{entry_func} is a function of two args, and returns a
1651 @code{char *}. The first argument is @var{text}. The second is a
1652 state argument; it is zero on the first call, and non-zero on subsequent
1653 calls. @var{entry_func} returns a @code{NULL} pointer to the caller
1654 when there are no more matches.
1657 @deftypefun {char *} rl_filename_completion_function (const char *text, int state)
1658 A generator function for filename completion in the general case.
1659 @var{text} is a partial filename.
1660 The Bash source is a useful reference for writing application-specific
1661 completion functions (the Bash completion functions call this and other
1662 Readline functions).
1665 @deftypefun {char *} rl_username_completion_function (const char *text, int state)
1666 A completion generator for usernames. @var{text} contains a partial
1667 username preceded by a random character (usually @samp{~}). As with all
1668 completion generators, @var{state} is zero on the first call and non-zero
1669 for subsequent calls.
1672 @node Completion Variables
1673 @subsection Completion Variables
1675 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1676 A pointer to the generator function for @code{rl_completion_matches()}.
1677 @code{NULL} means to use @code{rl_filename_completion_function()},
1678 the default filename completer.
1681 @deftypevar {rl_completion_func_t *} rl_attempted_completion_function
1682 A pointer to an alternative function to create matches.
1683 The function is called with @var{text}, @var{start}, and @var{end}.
1684 @var{start} and @var{end} are indices in @code{rl_line_buffer} defining
1685 the boundaries of @var{text}, which is a character string.
1686 If this function exists and returns @code{NULL}, or if this variable is
1687 set to @code{NULL}, then @code{rl_complete()} will call the value of
1688 @code{rl_completion_entry_function} to generate matches, otherwise the
1689 array of strings returned will be used.
1690 If this function sets the @code{rl_attempted_completion_over}
1691 variable to a non-zero value, Readline will not perform its default
1692 completion even if this function returns no matches.
1695 @deftypevar {rl_quote_func_t *} rl_filename_quoting_function
1696 A pointer to a function that will quote a filename in an
1697 application-specific fashion. This is called if filename completion is being
1698 attempted and one of the characters in @code{rl_filename_quote_characters}
1699 appears in a completed filename. The function is called with
1700 @var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
1701 is the filename to be quoted. The @var{match_type} is either
1702 @code{SINGLE_MATCH}, if there is only one completion match, or
1703 @code{MULT_MATCH}. Some functions use this to decide whether or not to
1704 insert a closing quote character. The @var{quote_pointer} is a pointer
1705 to any opening quote character the user typed. Some functions choose
1706 to reset this character.
1709 @deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
1710 A pointer to a function that will remove application-specific quoting
1711 characters from a filename before completion is attempted, so those
1712 characters do not interfere with matching the text against names in
1713 the filesystem. It is called with @var{text}, the text of the word
1714 to be dequoted, and @var{quote_char}, which is the quoting character
1715 that delimits the filename (usually @samp{'} or @samp{"}). If
1716 @var{quote_char} is zero, the filename was not in an embedded string.
1719 @deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
1720 A pointer to a function to call that determines whether or not a specific
1721 character in the line buffer is quoted, according to whatever quoting
1722 mechanism the program calling Readline uses. The function is called with
1723 two arguments: @var{text}, the text of the line, and @var{index}, the
1724 index of the character in the line. It is used to decide whether a
1725 character found in @code{rl_completer_word_break_characters} should be
1726 used to break words for the completer.
1729 @deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
1730 This function, if defined, is called by the completer when real filename
1731 completion is done, after all the matching names have been generated.
1732 It is passed a @code{NULL} terminated array of matches.
1733 The first element (@code{matches[0]}) is the
1734 maximal substring common to all matches. This function can
1735 re-arrange the list of matches as required, but each element deleted
1736 from the array must be freed.
1739 @deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
1740 This function, if defined, is allowed to modify the directory portion
1741 of filenames Readline completes.
1742 It could be used to expand symbolic links or shell variables in pathnames.
1743 It is called with the address of a string (the current directory name) as an
1744 argument, and may modify that string.
1745 If the string is replaced with a new string, the old value should be freed.
1746 Any modified directory name should have a trailing slash.
1747 The modified value will be used as part of the completion, replacing
1748 the directory portion of the pathname the user typed.
1749 At the least, even if no other expansion is performed, this function should
1750 remove any quote characters from the directory name, because its result will
1751 be passed directly to @code{opendir()}.
1753 The directory completion hook returns an integer that should be non-zero if
1754 the function modifies its directory argument.
1755 The function should not modify the directory argument if it returns 0.
1758 @deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook;
1759 If non-zero, this is the address of a function to call when completing
1760 a directory name. This function takes the address of the directory name
1761 to be modified as an argument. Unlike @code{rl_directory_completion_hook},
1762 it only modifies the directory name used in @code{opendir}, not what is
1763 displayed when the possible completions are printed or inserted. It is
1764 called before rl_directory_completion_hook.
1765 At the least, even if no other expansion is performed, this function should
1766 remove any quote characters from the directory name, because its result will
1767 be passed directly to @code{opendir()}.
1769 The directory rewrite hook returns an integer that should be non-zero if
1770 the function modfies its directory argument.
1771 The function should not modify the directory argument if it returns 0.
1774 @deftypevar {rl_icppfunc_t *} rl_filename_stat_hook
1775 If non-zero, this is the address of a function for the completer to
1776 call before deciding which character to append to a completed name.
1777 This function modifies its filename name argument, and the modified value
1778 is passed to @code{stat()} to determine the file's type and characteristics.
1779 This function does not need to remove quote characters from the filename.
1781 The stat hook returns an integer that should be non-zero if
1782 the function modfies its directory argument.
1783 The function should not modify the directory argument if it returns 0.
1786 @deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook
1787 If non-zero, this is the address of a function called when reading
1788 directory entries from the filesystem for completion and comparing
1789 them to the partial word to be completed. The function should
1790 perform any necesary application or system-specific conversion on
1791 the filename, such as converting between character sets or converting
1792 from a filesystem format to a character input format.
1793 The function takes two arguments: @var{fname}, the filename to be converted,
1794 and @var{fnlen}, its length in bytes.
1795 It must either return its first argument (if no conversion takes place)
1796 or the converted filename in newly-allocated memory. The converted
1797 form is used to compare against the word to be completed, and, if it
1798 matches, is added to the list of matches. Readline will free the
1802 @deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
1803 If non-zero, then this is the address of a function to call when
1804 completing a word would normally display the list of possible matches.
1805 This function is called in lieu of Readline displaying the list.
1806 It takes three arguments:
1807 (@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
1808 where @var{matches} is the array of matching strings,
1809 @var{num_matches} is the number of strings in that array, and
1810 @var{max_length} is the length of the longest string in that array.
1811 Readline provides a convenience function, @code{rl_display_match_list},
1812 that takes care of doing the display to Readline's output stream. That
1813 function may be called from this hook.
1816 @deftypevar {const char *} rl_basic_word_break_characters
1817 The basic list of characters that signal a break between words for the
1818 completer routine. The default value of this variable is the characters
1819 which break words for completion in Bash:
1820 @code{" \t\n\"\\'`@@$><=;|&@{("}.
1823 @deftypevar {const char *} rl_basic_quote_characters
1824 A list of quote characters which can cause a word break.
1827 @deftypevar {const char *} rl_completer_word_break_characters
1828 The list of characters that signal a break between words for
1829 @code{rl_complete_internal()}. The default list is the value of
1830 @code{rl_basic_word_break_characters}.
1833 @deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook
1834 If non-zero, this is the address of a function to call when Readline is
1835 deciding where to separate words for word completion. It should return
1836 a character string like @code{rl_completer_word_break_characters} to be
1837 used to perform the current completion. The function may choose to set
1838 @code{rl_completer_word_break_characters} itself. If the function
1839 returns @code{NULL}, @code{rl_completer_word_break_characters} is used.
1842 @deftypevar {const char *} rl_completer_quote_characters
1843 A list of characters which can be used to quote a substring of the line.
1844 Completion occurs on the entire substring, and within the substring
1845 @code{rl_completer_word_break_characters} are treated as any other character,
1846 unless they also appear within this list.
1849 @deftypevar {const char *} rl_filename_quote_characters
1850 A list of characters that cause a filename to be quoted by the completer
1851 when they appear in a completed filename. The default is the null string.
1854 @deftypevar {const char *} rl_special_prefixes
1855 The list of characters that are word break characters, but should be
1856 left in @var{text} when it is passed to the completion function.
1857 Programs can use this to help determine what kind of completing to do.
1858 For instance, Bash sets this variable to "$@@" so that it can complete
1859 shell variables and hostnames.
1862 @deftypevar int rl_completion_query_items
1863 Up to this many items will be displayed in response to a
1864 possible-completions call. After that, readline asks the user if she is sure
1865 she wants to see them all. The default value is 100. A negative value
1866 indicates that Readline should never ask the user.
1869 @deftypevar {int} rl_completion_append_character
1870 When a single completion alternative matches at the end of the command
1871 line, this character is appended to the inserted completion text. The
1872 default is a space character (@samp{ }). Setting this to the null
1873 character (@samp{\0}) prevents anything being appended automatically.
1874 This can be changed in application-specific completion functions to
1875 provide the ``most sensible word separator character'' according to
1876 an application-specific command line syntax specification.
1879 @deftypevar int rl_completion_suppress_append
1880 If non-zero, @var{rl_completion_append_character} is not appended to
1881 matches at the end of the command line, as described above.
1882 It is set to 0 before any application-specific completion function
1883 is called, and may only be changed within such a function.
1886 @deftypevar int rl_completion_quote_character
1887 When Readline is completing quoted text, as delimited by one of the
1888 characters in @var{rl_completer_quote_characters}, it sets this variable
1889 to the quoting character found.
1890 This is set before any application-specific completion function is called.
1893 @deftypevar int rl_completion_suppress_quote
1894 If non-zero, Readline does not append a matching quote character when
1895 performing completion on a quoted string.
1896 It is set to 0 before any application-specific completion function
1897 is called, and may only be changed within such a function.
1900 @deftypevar int rl_completion_found_quote
1901 When Readline is completing quoted text, it sets this variable
1902 to a non-zero value if the word being completed contains or is delimited
1903 by any quoting characters, including backslashes.
1904 This is set before any application-specific completion function is called.
1907 @deftypevar int rl_completion_mark_symlink_dirs
1908 If non-zero, a slash will be appended to completed filenames that are
1909 symbolic links to directory names, subject to the value of the
1910 user-settable @var{mark-directories} variable.
1911 This variable exists so that application-specific completion functions
1912 can override the user's global preference (set via the
1913 @var{mark-symlinked-directories} Readline variable) if appropriate.
1914 This variable is set to the user's preference before any
1915 application-specific completion function is called, so unless that
1916 function modifies the value, the user's preferences are honored.
1919 @deftypevar int rl_ignore_completion_duplicates
1920 If non-zero, then duplicates in the matches are removed.
1924 @deftypevar int rl_filename_completion_desired
1925 Non-zero means that the results of the matches are to be treated as
1926 filenames. This is @emph{always} zero when completion is attempted,
1927 and can only be changed
1928 within an application-specific completion function. If it is set to a
1929 non-zero value by such a function, directory names have a slash appended
1930 and Readline attempts to quote completed filenames if they contain any
1931 characters in @code{rl_filename_quote_characters} and
1932 @code{rl_filename_quoting_desired} is set to a non-zero value.
1935 @deftypevar int rl_filename_quoting_desired
1936 Non-zero means that the results of the matches are to be quoted using
1937 double quotes (or an application-specific quoting mechanism) if the
1938 completed filename contains any characters in
1939 @code{rl_filename_quote_chars}. This is @emph{always} non-zero
1940 when completion is attempted, and can only be changed within an
1941 application-specific completion function.
1942 The quoting is effected via a call to the function pointed to
1943 by @code{rl_filename_quoting_function}.
1946 @deftypevar int rl_attempted_completion_over
1947 If an application-specific completion function assigned to
1948 @code{rl_attempted_completion_function} sets this variable to a non-zero
1949 value, Readline will not perform its default filename completion even
1950 if the application's completion function returns no matches.
1951 It should be set only by an application's completion function.
1954 @deftypevar int rl_sort_completion_matches
1955 If an application sets this variable to 0, Readline will not sort the
1956 list of completions (which implies that it cannot remove any duplicate
1957 completions). The default value is 1, which means that Readline will
1958 sort the completions and, depending on the value of
1959 @code{rl_ignore_completion_duplicates}, will attempt to remove duplicate
1963 @deftypevar int rl_completion_type
1964 Set to a character describing the type of completion Readline is currently
1965 attempting; see the description of @code{rl_complete_internal()}
1966 (@pxref{Completion Functions}) for the list of characters.
1967 This is set to the appropriate value before any application-specific
1968 completion function is called, allowing such functions to present
1969 the same interface as @code{rl_complete()}.
1972 @deftypevar int rl_completion_invoking_key
1973 Set to the final character in the key sequence that invoked one of the
1974 completion functions that call @code{rl_complete_internal()}. This is
1975 set to the appropriate value before any application-specific completion
1979 @deftypevar int rl_inhibit_completion
1980 If this variable is non-zero, completion is inhibited. The completion
1981 character will be inserted as any other bound to @code{self-insert}.
1984 @node A Short Completion Example
1985 @subsection A Short Completion Example
1987 Here is a small application demonstrating the use of the GNU Readline
1988 library. It is called @code{fileman}, and the source code resides in
1989 @file{examples/fileman.c}. This sample application provides
1990 completion of command names, line editing features, and access to the
1995 /* fileman.c -- A tiny application which demonstrates how to use the
1996 GNU Readline library. This application interactively allows users
1997 to manipulate files and their modes. */
1999 #ifdef HAVE_CONFIG_H
2000 # include <config.h>
2003 #include <sys/types.h>
2004 #ifdef HAVE_SYS_FILE_H
2005 # include <sys/file.h>
2007 #include <sys/stat.h>
2009 #ifdef HAVE_UNISTD_H
2010 # include <unistd.h>
2017 #if defined (HAVE_STRING_H)
2018 # include <string.h>
2019 #else /* !HAVE_STRING_H */
2020 # include <strings.h>
2021 #endif /* !HAVE_STRING_H */
2023 #ifdef HAVE_STDLIB_H
2024 # include <stdlib.h>
2029 #include <readline/readline.h>
2030 #include <readline/history.h>
2032 extern char *xmalloc PARAMS((size_t));
2034 /* The names of functions that actually do the manipulation. */
2035 int com_list PARAMS((char *));
2036 int com_view PARAMS((char *));
2037 int com_rename PARAMS((char *));
2038 int com_stat PARAMS((char *));
2039 int com_pwd PARAMS((char *));
2040 int com_delete PARAMS((char *));
2041 int com_help PARAMS((char *));
2042 int com_cd PARAMS((char *));
2043 int com_quit PARAMS((char *));
2045 /* A structure which contains information on the commands this program
2049 char *name; /* User printable name of the function. */
2050 rl_icpfunc_t *func; /* Function to call to do the job. */
2051 char *doc; /* Documentation for this function. */
2054 COMMAND commands[] = @{
2055 @{ "cd", com_cd, "Change to directory DIR" @},
2056 @{ "delete", com_delete, "Delete FILE" @},
2057 @{ "help", com_help, "Display this text" @},
2058 @{ "?", com_help, "Synonym for `help'" @},
2059 @{ "list", com_list, "List files in DIR" @},
2060 @{ "ls", com_list, "Synonym for `list'" @},
2061 @{ "pwd", com_pwd, "Print the current working directory" @},
2062 @{ "quit", com_quit, "Quit using Fileman" @},
2063 @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
2064 @{ "stat", com_stat, "Print out statistics on FILE" @},
2065 @{ "view", com_view, "View the contents of FILE" @},
2066 @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
2069 /* Forward declarations. */
2070 char *stripwhite ();
2071 COMMAND *find_command ();
2073 /* The name of this program, as taken from argv[0]. */
2076 /* When non-zero, this global means the user is done using this program. */
2085 r = xmalloc (strlen (s) + 1);
2098 initialize_readline (); /* Bind our completer. */
2100 /* Loop reading and executing lines until the user quits. */
2101 for ( ; done == 0; )
2103 line = readline ("FileMan: ");
2108 /* Remove leading and trailing whitespace from the line.
2109 Then, if there is anything left, add it to the history list
2111 s = stripwhite (line);
2124 /* Execute a command line. */
2133 /* Isolate the command word. */
2135 while (line[i] && whitespace (line[i]))
2139 while (line[i] && !whitespace (line[i]))
2145 command = find_command (word);
2149 fprintf (stderr, "%s: No such command for FileMan.\n", word);
2153 /* Get argument to command, if any. */
2154 while (whitespace (line[i]))
2159 /* Call the function. */
2160 return ((*(command->func)) (word));
2163 /* Look up NAME as the name of a command, and return a pointer to that
2164 command. Return a NULL pointer if NAME isn't a command name. */
2171 for (i = 0; commands[i].name; i++)
2172 if (strcmp (name, commands[i].name) == 0)
2173 return (&commands[i]);
2175 return ((COMMAND *)NULL);
2178 /* Strip whitespace from the start and end of STRING. Return a pointer
2184 register char *s, *t;
2186 for (s = string; whitespace (*s); s++)
2192 t = s + strlen (s) - 1;
2193 while (t > s && whitespace (*t))
2200 /* **************************************************************** */
2202 /* Interface to Readline Completion */
2204 /* **************************************************************** */
2206 char *command_generator PARAMS((const char *, int));
2207 char **fileman_completion PARAMS((const char *, int, int));
2209 /* Tell the GNU Readline library how to complete. We want to try to complete
2210 on command names if this is the first word in the line, or on filenames
2212 initialize_readline ()
2214 /* Allow conditional parsing of the ~/.inputrc file. */
2215 rl_readline_name = "FileMan";
2217 /* Tell the completer that we want a crack first. */
2218 rl_attempted_completion_function = fileman_completion;
2221 /* Attempt to complete on the contents of TEXT. START and END bound the
2222 region of rl_line_buffer that contains the word to complete. TEXT is
2223 the word to complete. We can use the entire contents of rl_line_buffer
2224 in case we want to do some simple parsing. Return the array of matches,
2225 or NULL if there aren't any. */
2227 fileman_completion (text, start, end)
2233 matches = (char **)NULL;
2235 /* If this word is at the start of the line, then it is a command
2236 to complete. Otherwise it is the name of a file in the current
2239 matches = rl_completion_matches (text, command_generator);
2244 /* Generator function for command completion. STATE lets us know whether
2245 to start from scratch; without any state (i.e. STATE == 0), then we
2246 start at the top of the list. */
2248 command_generator (text, state)
2252 static int list_index, len;
2255 /* If this is a new word to complete, initialize now. This includes
2256 saving the length of TEXT for efficiency, and initializing the index
2261 len = strlen (text);
2264 /* Return the next name which partially matches from the command list. */
2265 while (name = commands[list_index].name)
2269 if (strncmp (name, text, len) == 0)
2270 return (dupstr(name));
2273 /* If no names matched, then return NULL. */
2274 return ((char *)NULL);
2277 /* **************************************************************** */
2279 /* FileMan Commands */
2281 /* **************************************************************** */
2283 /* String to pass to system (). This is for the LIST, VIEW and RENAME
2285 static char syscom[1024];
2287 /* List the file(s) named in arg. */
2294 sprintf (syscom, "ls -FClg %s", arg);
2295 return (system (syscom));
2301 if (!valid_argument ("view", arg))
2304 #if defined (__MSDOS__)
2305 /* more.com doesn't grok slashes in pathnames */
2306 sprintf (syscom, "less %s", arg);
2308 sprintf (syscom, "more %s", arg);
2310 return (system (syscom));
2316 too_dangerous ("rename");
2325 if (!valid_argument ("stat", arg))
2328 if (stat (arg, &finfo) == -1)
2334 printf ("Statistics for `%s':\n", arg);
2336 printf ("%s has %d link%s, and is %d byte%s in length.\n",
2339 (finfo.st_nlink == 1) ? "" : "s",
2341 (finfo.st_size == 1) ? "" : "s");
2342 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
2343 printf (" Last access at: %s", ctime (&finfo.st_atime));
2344 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
2351 too_dangerous ("delete");
2355 /* Print out help for ARG, or for all of the commands if ARG is
2363 for (i = 0; commands[i].name; i++)
2365 if (!*arg || (strcmp (arg, commands[i].name) == 0))
2367 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
2374 printf ("No commands match `%s'. Possibilties are:\n", arg);
2376 for (i = 0; commands[i].name; i++)
2378 /* Print in six columns. */
2385 printf ("%s\t", commands[i].name);
2395 /* Change to the directory ARG. */
2399 if (chdir (arg) == -1)
2409 /* Print out the current working directory. */
2415 s = getcwd (dir, sizeof(dir) - 1);
2418 printf ("Error getting pwd: %s\n", dir);
2422 printf ("Current directory is %s\n", dir);
2426 /* The user wishes to quit using this program. Just set DONE non-zero. */
2434 /* Function which tells you that you can't do this. */
2435 too_dangerous (caller)
2439 "%s: Too dangerous for me to distribute. Write it yourself.\n",
2443 /* Return non-zero if ARG is a valid argument for CALLER, else print
2444 an error message and return zero. */
2446 valid_argument (caller, arg)
2451 fprintf (stderr, "%s: Argument required.\n", caller);