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.)
4@setchapternewpage odd
5
6@ifinfo
7This document describes the GNU Readline Library, a utility for aiding
8in the consitency of user interface across discrete programs that need
9to provide a command line interface.
10
11Copyright (C) 1988-2002 Free Software Foundation, Inc.
12
13Permission is granted to make and distribute verbatim copies of
14this manual provided the copyright notice and this permission notice
15pare preserved on all copies.
16
17@ignore
18Permission is granted to process this file through TeX and print the
19results, provided the printed document carries copying permission
20notice identical to this one except for the removal of this paragraph
21(this paragraph not being relevant to the printed manual).
22@end ignore
23
24Permission is granted to copy and distribute modified versions of this
25manual under the conditions for verbatim copying, provided that the entire
26resulting derived work is distributed under the terms of a permission
27notice identical to this one.
28
29Permission is granted to copy and distribute translations of this manual
30into another language, under the above conditions for modified versions,
31except that this permission notice may be stated in a translation approved
32by the Foundation.
33@end ifinfo
34
35@node Programming with GNU Readline
36@chapter Programming with GNU Readline
37
38This chapter describes the interface between the @sc{gnu} Readline Library and
39other programs.  If you are a programmer, and you wish to include the
40features found in @sc{gnu} Readline
41such as completion, line editing, and interactive history manipulation
42in your own programs, this section is for you.
43
44@menu
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
48					functions.
49* Readline Convenience Functions::	Functions which Readline supplies to
50					aid in writing your own custom
51					functions.
52* Readline Signal Handling::	How Readline behaves when it receives signals.
53* Custom Completers::	Supplanting or supplementing Readline's
54			completion functions.
55@end menu
56
57@node Basic Behavior
58@section Basic Behavior
59
60Many programs provide a command line interface, such as @code{mail},
61@code{ftp}, and @code{sh}.  For such programs, the default behaviour of
62Readline is sufficient.  This section describes how to use Readline in
63the simplest way possible, perhaps to replace calls in your code to
64@code{gets()} or @code{fgets()}.
65
66@findex readline
67@cindex readline, function
68
69The function @code{readline()} prints a prompt @var{prompt}
70and then reads and returns a single line of text from the user.
71If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
72The line @code{readline} returns is allocated with @code{malloc()};
73the caller should @code{free()} the line when it has finished with it.
74The declaration for @code{readline} in ANSI C is
75
76@example
77@code{char *readline (const char *@var{prompt});}
78@end example
79
80@noindent
81So, one might say
82@example
83@code{char *line = readline ("Enter a line: ");}
84@end example
85@noindent
86in order to read a line of text from the user.
87The line returned has the final newline removed, so only the
88text remains.
89
90If @code{readline} encounters an @code{EOF} while reading the line, and the
91line is empty at that point, then @code{(char *)NULL} is returned.
92Otherwise, the line is ended just as if a newline had been typed.
93
94If 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
96line away in a @dfn{history} list of such lines.
97
98@example
99@code{add_history (line)};
100@end example
101
102@noindent
103For full details on the GNU History Library, see the associated manual.
104
105It is preferable to avoid saving empty lines on the history list, since
106users rarely have a burning need to reuse a blank line.  Here is
107a function which usefully replaces the standard @code{gets()} library
108function, and has the advantage of no static buffer to overflow:
109
110@example
111/* A static variable for holding the line. */
112static char *line_read = (char *)NULL;
113
114/* Read a string, and return a pointer to it.
115   Returns NULL on EOF. */
116char *
117rl_gets ()
118@{
119  /* If the buffer has already been allocated,
120     return the memory to the free pool. */
121  if (line_read)
122    @{
123      free (line_read);
124      line_read = (char *)NULL;
125    @}
126
127  /* Get a line from the user. */
128  line_read = readline ("");
129
130  /* If the line has any text in it,
131     save it on the history. */
132  if (line_read && *line_read)
133    add_history (line_read);
134
135  return (line_read);
136@}
137@end example
138
139This function gives the user the default behaviour of @key{TAB}
140completion: completion on file names.  If you do not want Readline to
141complete on filenames, you can change the binding of the @key{TAB} key
142with @code{rl_bind_key()}.
143
144@example
145@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
146@end example
147
148@code{rl_bind_key()} takes two arguments: @var{key} is the character that
149you want to bind, and @var{function} is the address of the function to
150call when @var{key} is pressed.  Binding @key{TAB} to @code{rl_insert()}
151makes @key{TAB} insert itself.
152@code{rl_bind_key()} returns non-zero if @var{key} is not a valid
153ASCII character code (between 0 and 255).
154
155Thus, to disable the default @key{TAB} behavior, the following suffices:
156@example
157@code{rl_bind_key ('\t', rl_insert);}
158@end example
159
160This code should be executed once at the start of your program; you
161might write a function called @code{initialize_readline()} which
162performs this and other desired initializations, such as installing
163custom completers (@pxref{Custom Completers}).
164
165@node Custom Functions
166@section Custom Functions
167
168Readline provides many functions for manipulating the text of
169the line, but it isn't possible to anticipate the needs of all
170programs.  This section describes the various functions and variables
171defined within the Readline library which allow a user program to add
172customized functionality to Readline.
173
174Before declaring any functions that customize Readline's behavior, or
175using any functionality Readline provides in other code, an
176application writer should include the file @code{<readline/readline.h>}
177in any file that uses Readline's features.  Since some of the definitions
178in @code{readline.h} use the @code{stdio} library, the file
179@code{<stdio.h>} should be included before @code{readline.h}.
180
181@code{readline.h} defines a C preprocessor variable that should
182be treated as an integer, @code{RL_READLINE_VERSION}, which may
183be used to conditionally compile application code depending on
184the installed Readline version.  The value is a hexadecimal
185encoding of the major and minor version numbers of the library,
186of the form 0x@var{MMmm}.  @var{MM} is the two-digit major
187version number; @var{mm} is the two-digit minor version number.
188For Readline 4.2, for example, the value of
189@code{RL_READLINE_VERSION} would be @code{0x0402}.
190
191@menu
192* Readline Typedefs::	C declarations to make code readable.
193* Function Writing::	Variables and calling conventions.
194@end menu
195
196@node Readline Typedefs
197@subsection Readline Typedefs
198
199For readabilty, we declare a number of new object types, all pointers
200to functions.
201
202The reason for declaring these new types is to make it easier to write
203code describing pointers to C functions with appropriately prototyped
204arguments and return values.
205
206For instance, say we want to declare a variable @var{func} as a pointer
207to a function which takes two @code{int} arguments and returns an
208@code{int} (this is the type of all of the Readline bindable functions).
209Instead of the classic C declaration
210
211@code{int (*func)();}
212
213@noindent
214or the ANSI-C style declaration
215
216@code{int (*func)(int, int);}
217
218@noindent
219we may write
220
221@code{rl_command_func_t *func;}
222
223The full list of function pointer types available is
224
225@table @code
226@item typedef int rl_command_func_t (int, int);
227
228@item typedef char *rl_compentry_func_t (const char *, int);
229
230@item typedef char **rl_completion_func_t (const char *, int, int);
231
232@item typedef char *rl_quote_func_t (char *, int, char *);
233
234@item typedef char *rl_dequote_func_t (char *, int);
235
236@item typedef int rl_compignore_func_t (char **);
237
238@item typedef void rl_compdisp_func_t (char **, int, int);
239
240@item typedef int rl_hook_func_t (void);
241
242@item typedef int rl_getc_func_t (FILE *);
243
244@item typedef int rl_linebuf_func_t (char *, int);
245
246@item typedef int rl_intfunc_t (int);
247@item #define rl_ivoidfunc_t rl_hook_func_t
248@item typedef int rl_icpfunc_t (char *);
249@item typedef int rl_icppfunc_t (char **);
250
251@item typedef void rl_voidfunc_t (void);
252@item typedef void rl_vintfunc_t (int);
253@item typedef void rl_vcpfunc_t (char *);
254@item typedef void rl_vcppfunc_t (char **);
255
256@end table
257
258@node Function Writing
259@subsection Writing a New Function
260
261In order to write new functions for Readline, you need to know the
262calling conventions for keyboard-invoked functions, and the names of the
263variables that describe the current state of the line read so far.
264
265The calling sequence for a command @code{foo} looks like
266
267@example
268@code{int foo (int count, int key)}
269@end example
270
271@noindent
272where @var{count} is the numeric argument (or 1 if defaulted) and
273@var{key} is the key that invoked this function.
274
275It is completely up to the function as to what should be done with the
276numeric argument.  Some functions use it as a repeat count, some
277as a flag, and others to choose alternate behavior (refreshing the current
278line as opposed to refreshing the screen, for example).  Some choose to
279ignore it.  In general, if a
280function uses the numeric argument as a repeat count, it should be able
281to do something useful with both negative and positive arguments.
282At the very least, it should be aware that it can be passed a
283negative argument.
284
285A command function should return 0 if its action completes successfully,
286and a non-zero value if some error occurs.
287
288@node Readline Variables
289@section Readline Variables
290
291These variables are available to function writers.
292
293@deftypevar {char *} rl_line_buffer
294This is the line gathered so far.  You are welcome to modify the
295contents of the line, but see @ref{Allowing Undoing}.  The
296function @code{rl_extend_line_buffer} is available to increase
297the memory allocated to @code{rl_line_buffer}.
298@end deftypevar
299
300@deftypevar int rl_point
301The offset of the current cursor position in @code{rl_line_buffer}
302(the @emph{point}).
303@end deftypevar
304
305@deftypevar int rl_end
306The number of characters present in @code{rl_line_buffer}.  When
307@code{rl_point} is at the end of the line, @code{rl_point} and
308@code{rl_end} are equal.
309@end deftypevar
310
311@deftypevar int rl_mark
312The @var{mark} (saved position) in the current line.  If set, the mark
313and point define a @emph{region}.
314@end deftypevar
315
316@deftypevar int rl_done
317Setting this to a non-zero value causes Readline to return the current
318line immediately.
319@end deftypevar
320
321@deftypevar int rl_num_chars_to_read
322Setting this to a positive value before calling @code{readline()} causes
323Readline to return after accepting that many characters, rather
324than reading up to a character bound to @code{accept-line}.
325@end deftypevar
326
327@deftypevar int rl_pending_input
328Setting this to a value makes it the next keystroke read.  This is a
329way to stuff a single character into the input stream.
330@end deftypevar
331
332@deftypevar int rl_dispatching
333Set to a non-zero value if a function is being called from a key binding;
334zero otherwise.  Application functions can test this to discover whether
335they were called directly or by Readline's dispatching mechanism.
336@end deftypevar
337
338@deftypevar int rl_erase_empty_line
339Setting this to a non-zero value causes Readline to completely erase
340the current line, including any prompt, any time a newline is typed as
341the only character on an otherwise-empty line.  The cursor is moved to
342the beginning of the newly-blank line.
343@end deftypevar
344
345@deftypevar {char *} rl_prompt
346The prompt Readline uses.  This is set from the argument to
347@code{readline()}, and should not be assigned to directly.
348The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
349be used to modify the prompt string after calling @code{readline()}.
350@end deftypevar
351
352@deftypevar int rl_already_prompted
353If an application wishes to display the prompt itself, rather than have
354Readline do it the first time @code{readline()} is called, it should set
355this variable to a non-zero value after displaying the prompt.
356The prompt must also be passed as the argument to @code{readline()} so
357the redisplay functions can update the display properly.
358The calling application is responsible for managing the value; Readline
359never sets it.
360@end deftypevar
361
362@deftypevar {const char *} rl_library_version
363The version number of this revision of the library.
364@end deftypevar
365
366@deftypevar int rl_readline_version
367An integer encoding the current version of the library.  The encoding is
368of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
369number, and @var{mm} is the two-digit minor version number.
370For example, for Readline-4.2, @code{rl_readline_version} would have the
371value 0x0402.
372@end deftypevar
373
374@deftypevar {int} rl_gnu_readline_p
375Always set to 1, denoting that this is @sc{gnu} readline rather than some
376emulation.
377@end deftypevar
378
379@deftypevar {const char *} rl_terminal_name
380The terminal type, used for initialization.  If not set by the application,
381Readline sets this to the value of the @env{TERM} environment variable
382the first time it is called.
383@end deftypevar
384
385@deftypevar {const char *} rl_readline_name
386This variable is set to a unique name by each application using Readline.
387The value allows conditional parsing of the inputrc file
388(@pxref{Conditional Init Constructs}).
389@end deftypevar
390
391@deftypevar {FILE *} rl_instream
392The stdio stream from which Readline reads input.
393If @code{NULL}, Readline defaults to @var{stdin}.
394@end deftypevar
395
396@deftypevar {FILE *} rl_outstream
397The stdio stream to which Readline performs output.
398If @code{NULL}, Readline defaults to @var{stdout}.
399@end deftypevar
400
401@deftypevar {rl_command_func_t *} rl_last_func
402The address of the last command function Readline executed.  May be used to
403test whether or not a function is being executed twice in succession, for
404example.
405@end deftypevar
406
407@deftypevar {rl_hook_func_t *} rl_startup_hook
408If non-zero, this is the address of a function to call just
409before @code{readline} prints the first prompt.
410@end deftypevar
411
412@deftypevar {rl_hook_func_t *} rl_pre_input_hook
413If non-zero, this is the address of a function to call after
414the first prompt has been printed and just before @code{readline}
415starts reading input characters.
416@end deftypevar
417
418@deftypevar {rl_hook_func_t *} rl_event_hook
419If non-zero, this is the address of a function to call periodically
420when Readline is waiting for terminal input.
421By default, this will be called at most ten times a second if there
422is no keyboard input.
423@end deftypevar
424
425@deftypevar {rl_getc_func_t *} rl_getc_function
426If non-zero, Readline will call indirectly through this pointer
427to get a character from the input stream.  By default, it is set to
428@code{rl_getc}, the default Readline character input function
429(@pxref{Character Input}).
430@end deftypevar
431
432@deftypevar {rl_voidfunc_t *} rl_redisplay_function
433If non-zero, Readline will call indirectly through this pointer
434to update the display with the current contents of the editing buffer.
435By default, it is set to @code{rl_redisplay}, the default Readline
436redisplay function (@pxref{Redisplay}).
437@end deftypevar
438
439@deftypevar {rl_vintfunc_t *} rl_prep_term_function
440If non-zero, Readline will call indirectly through this pointer
441to initialize the terminal.  The function takes a single argument, an
442@code{int} flag that says whether or not to use eight-bit characters.
443By default, this is set to @code{rl_prep_terminal}
444(@pxref{Terminal Management}).
445@end deftypevar
446
447@deftypevar {rl_voidfunc_t *} rl_deprep_term_function
448If non-zero, Readline will call indirectly through this pointer
449to reset the terminal.  This function should undo the effects of
450@code{rl_prep_term_function}.
451By default, this is set to @code{rl_deprep_terminal}
452(@pxref{Terminal Management}).
453@end deftypevar
454
455@deftypevar {Keymap} rl_executing_keymap
456This variable is set to the keymap (@pxref{Keymaps}) in which the
457currently executing readline function was found.
458@end deftypevar
459
460@deftypevar {Keymap} rl_binding_keymap
461This variable is set to the keymap (@pxref{Keymaps}) in which the
462last key binding occurred.
463@end deftypevar
464
465@deftypevar {char *} rl_executing_macro
466This variable is set to the text of any currently-executing macro.
467@end deftypevar
468
469@deftypevar {int} rl_readline_state
470A variable with bit values that encapsulate the current Readline state.
471A bit is set with the @code{RL_SETSTATE} macro, and unset with the
472@code{RL_UNSETSTATE} macro.  Use the @code{RL_ISSTATE} macro to test
473whether a particular state bit is set.  Current state bits include:
474
475@table @code
476@item RL_STATE_NONE
477Readline has not yet been called, nor has it begun to intialize.
478@item RL_STATE_INITIALIZING
479Readline is initializing its internal data structures.
480@item RL_STATE_INITIALIZED
481Readline has completed its initialization.
482@item RL_STATE_TERMPREPPED
483Readline has modified the terminal modes to do its own input and redisplay.
484@item RL_STATE_READCMD
485Readline is reading a command from the keyboard.
486@item RL_STATE_METANEXT
487Readline is reading more input after reading the meta-prefix character.
488@item RL_STATE_DISPATCHING
489Readline is dispatching to a command.
490@item RL_STATE_MOREINPUT
491Readline is reading more input while executing an editing command.
492@item RL_STATE_ISEARCH
493Readline is performing an incremental history search.
494@item RL_STATE_NSEARCH
495Readline is performing a non-incremental history search.
496@item RL_STATE_SEARCH
497Readline is searching backward or forward through the history for a string.
498@item RL_STATE_NUMERICARG
499Readline is reading a numeric argument.
500@item RL_STATE_MACROINPUT
501Readline is currently getting its input from a previously-defined keyboard
502macro.
503@item RL_STATE_MACRODEF
504Readline is currently reading characters defining a keyboard macro.
505@item RL_STATE_OVERWRITE
506Readline is in overwrite mode.
507@item RL_STATE_COMPLETING
508Readline is performing word completion.
509@item RL_STATE_SIGHANDLER
510Readline is currently executing the readline signal handler.
511@item RL_STATE_UNDOING
512Readline is performing an undo.
513@item RL_STATE_DONE
514Readline has read a key sequence bound to @code{accept-line}
515and is about to return the line to the caller.
516@end table
517
518@end deftypevar
519
520@deftypevar {int} rl_explicit_arg
521Set to a non-zero value if an explicit numeric argument was specified by
522the user.  Only valid in a bindable command function.
523@end deftypevar
524
525@deftypevar {int} rl_numeric_arg
526Set to the value of any numeric argument explicitly specified by the user
527before executing the current Readline function.  Only valid in a bindable
528command function.
529@end deftypevar
530
531@deftypevar {int} rl_editing_mode
532Set to a value denoting Readline's current editing mode.  A value of
533@var{1} means Readline is currently in emacs mode; @var{0}
534means that vi mode is active.
535@end deftypevar
536
537
538@node Readline Convenience Functions
539@section Readline Convenience Functions
540
541@menu
542* Function Naming::	How to give a function you write a name.
543* Keymaps::		Making keymaps.
544* Binding Keys::	Changing Keymaps.
545* Associating Function Names and Bindings::	Translate function names to
546						key sequences.
547* Allowing Undoing::	How to make your functions undoable.
548* Redisplay::		Functions to control line display.
549* Modifying Text::	Functions to modify @code{rl_line_buffer}.
550* Character Input::	Functions to read keyboard input.
551* Terminal Management::	Functions to manage terminal settings.
552* Utility Functions::	Generally useful functions and hooks.
553* Miscellaneous Functions::	Functions that don't fall into any category.
554* Alternate Interface::	Using Readline in a `callback' fashion.
555* A Readline Example::		An example Readline function.
556@end menu
557
558@node Function Naming
559@subsection Naming a Function
560
561The user can dynamically change the bindings of keys while using
562Readline.  This is done by representing the function with a descriptive
563name.  The user is able to type the descriptive name when referring to
564the function.  Thus, in an init file, one might find
565
566@example
567Meta-Rubout:	backward-kill-word
568@end example
569
570This binds the keystroke @key{Meta-Rubout} to the function
571@emph{descriptively} named @code{backward-kill-word}.  You, as the
572programmer, should bind the functions you write to descriptive names as
573well.  Readline provides a function for doing that:
574
575@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
576Add @var{name} to the list of named functions.  Make @var{function} be
577the function that gets called.  If @var{key} is not -1, then bind it to
578@var{function} using @code{rl_bind_key()}.
579@end deftypefun
580
581Using this function alone is sufficient for most applications.  It is
582the recommended way to add a few functions to the default functions that
583Readline has built in.  If you need to do something other
584than adding a function to Readline, you may need to use the
585underlying functions described below.
586
587@node Keymaps
588@subsection Selecting a Keymap
589
590Key bindings take place on a @dfn{keymap}.  The keymap is the
591association between the keys that the user types and the functions that
592get run.  You can make your own keymaps, copy existing keymaps, and tell
593Readline which keymap to use.
594
595@deftypefun Keymap rl_make_bare_keymap (void)
596Returns a new, empty keymap.  The space for the keymap is allocated with
597@code{malloc()}; the caller should free it by calling
598@code{rl_discard_keymap()} when done.
599@end deftypefun
600
601@deftypefun Keymap rl_copy_keymap (Keymap map)
602Return a new keymap which is a copy of @var{map}.
603@end deftypefun
604
605@deftypefun Keymap rl_make_keymap (void)
606Return a new keymap with the printing characters bound to rl_insert,
607the lowercase Meta characters bound to run their equivalents, and
608the Meta digits bound to produce numeric arguments.
609@end deftypefun
610
611@deftypefun void rl_discard_keymap (Keymap keymap)
612Free the storage associated with @var{keymap}.
613@end deftypefun
614
615Readline has several internal keymaps.  These functions allow you to
616change which keymap is active.
617
618@deftypefun Keymap rl_get_keymap (void)
619Returns the currently active keymap.
620@end deftypefun
621
622@deftypefun void rl_set_keymap (Keymap keymap)
623Makes @var{keymap} the currently active keymap.
624@end deftypefun
625
626@deftypefun Keymap rl_get_keymap_by_name (const char *name)
627Return the keymap matching @var{name}.  @var{name} is one which would
628be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
629@end deftypefun
630
631@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
632Return the name matching @var{keymap}.  @var{name} is one which would
633be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
634@end deftypefun
635
636@node Binding Keys
637@subsection Binding Keys
638
639Key sequences are associate with functions through the keymap.
640Readline has several internal keymaps: @code{emacs_standard_keymap},
641@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
642@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
643@code{emacs_standard_keymap} is the default, and the examples in
644this manual assume that.
645
646Since @code{readline()} installs a set of default key bindings the first
647time it is called, there is always the danger that a custom binding
648installed before the first call to @code{readline()} will be overridden.
649An alternate mechanism is to install custom key bindings in an
650initialization function assigned to the @code{rl_startup_hook} variable
651(@pxref{Readline Variables}).
652
653These functions manage key bindings.
654
655@deftypefun int rl_bind_key (int key, rl_command_func_t *function)
656Binds @var{key} to @var{function} in the currently active keymap.
657Returns non-zero in the case of an invalid @var{key}.
658@end deftypefun
659
660@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
661Bind @var{key} to @var{function} in @var{map}.  Returns non-zero in the case
662of an invalid @var{key}.
663@end deftypefun
664
665@deftypefun int rl_unbind_key (int key)
666Bind @var{key} to the null function in the currently active keymap.
667Returns non-zero in case of error.
668@end deftypefun
669
670@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
671Bind @var{key} to the null function in @var{map}.
672Returns non-zero in case of error.
673@end deftypefun
674
675@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
676Unbind all keys that execute @var{function} in @var{map}.
677@end deftypefun
678
679@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
680Unbind all keys that are bound to @var{command} in @var{map}.
681@end deftypefun
682
683@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
684Bind the key sequence represented by the string @var{keyseq} to the function
685@var{function}.  This makes new keymaps as
686necessary.  The initial keymap in which to do bindings is @var{map}.
687@end deftypefun
688
689@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
690Bind the key sequence represented by the string @var{keyseq} to the arbitrary
691pointer @var{data}.  @var{type} says what kind of data is pointed to by
692@var{data}; this can be a function (@code{ISFUNC}), a macro
693(@code{ISMACR}), or a keymap (@code{ISKMAP}).  This makes new keymaps as
694necessary.  The initial keymap in which to do bindings is @var{map}.
695@end deftypefun
696
697@deftypefun int rl_parse_and_bind (char *line)
698Parse @var{line} as if it had been read from the @code{inputrc} file and
699perform any key bindings and variable assignments found
700(@pxref{Readline Init File}).
701@end deftypefun
702
703@deftypefun int rl_read_init_file (const char *filename)
704Read keybindings and variable assignments from @var{filename}
705(@pxref{Readline Init File}).
706@end deftypefun
707
708@node Associating Function Names and Bindings
709@subsection Associating Function Names and Bindings
710
711These functions allow you to find out what keys invoke named functions
712and the functions invoked by a particular key sequence.  You may also
713associate a new function name with an arbitrary function.
714
715@deftypefun {rl_command_func_t *} rl_named_function (const char *name)
716Return the function with name @var{name}.
717@end deftypefun
718
719@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
720Return the function invoked by @var{keyseq} in keymap @var{map}.
721If @var{map} is @code{NULL}, the current keymap is used.  If @var{type} is
722not @code{NULL}, the type of the object is returned in the @code{int} variable
723it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
724@end deftypefun
725
726@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
727Return an array of strings representing the key sequences used to
728invoke @var{function} in the current keymap.
729@end deftypefun
730
731@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
732Return an array of strings representing the key sequences used to
733invoke @var{function} in the keymap @var{map}.
734@end deftypefun
735
736@deftypefun void rl_function_dumper (int readable)
737Print the readline function names and the key sequences currently
738bound to them to @code{rl_outstream}.  If @var{readable} is non-zero,
739the list is formatted in such a way that it can be made part of an
740@code{inputrc} file and re-read.
741@end deftypefun
742
743@deftypefun void rl_list_funmap_names (void)
744Print the names of all bindable Readline functions to @code{rl_outstream}.
745@end deftypefun
746
747@deftypefun {const char **} rl_funmap_names (void)
748Return a NULL terminated array of known function names.  The array is
749sorted.  The array itself is allocated, but not the strings inside.  You
750should @code{free()} the array when you are done, but not the pointers.
751@end deftypefun
752
753@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
754Add @var{name} to the list of bindable Readline command names, and make
755@var{function} the function to be called when @var{name} is invoked.
756@end deftypefun
757
758@node Allowing Undoing
759@subsection Allowing Undoing
760
761Supporting the undo command is a painless thing, and makes your
762functions much more useful.  It is certainly easy to try
763something if you know you can undo it.
764
765If your function simply inserts text once, or deletes text once, and
766uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
767undoing is already done for you automatically.
768
769If you do multiple insertions or multiple deletions, or any combination
770of these operations, you should group them together into one operation.
771This is done with @code{rl_begin_undo_group()} and
772@code{rl_end_undo_group()}.
773
774The types of events that can be undone are:
775
776@smallexample
777enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
778@end smallexample
779
780Notice that @code{UNDO_DELETE} means to insert some text, and
781@code{UNDO_INSERT} means to delete some text.  That is, the undo code
782tells what to undo, not how to undo it.  @code{UNDO_BEGIN} and
783@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
784@code{rl_end_undo_group()}.
785
786@deftypefun int rl_begin_undo_group (void)
787Begins saving undo information in a group construct.  The undo
788information usually comes from calls to @code{rl_insert_text()} and
789@code{rl_delete_text()}, but could be the result of calls to
790@code{rl_add_undo()}.
791@end deftypefun
792
793@deftypefun int rl_end_undo_group (void)
794Closes the current undo group started with @code{rl_begin_undo_group
795()}.  There should be one call to @code{rl_end_undo_group()}
796for each call to @code{rl_begin_undo_group()}.
797@end deftypefun
798
799@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
800Remember how to undo an event (according to @var{what}).  The affected
801text runs from @var{start} to @var{end}, and encompasses @var{text}.
802@end deftypefun
803
804@deftypefun void rl_free_undo_list (void)
805Free the existing undo list.
806@end deftypefun
807
808@deftypefun int rl_do_undo (void)
809Undo the first thing on the undo list.  Returns @code{0} if there was
810nothing to undo, non-zero if something was undone.
811@end deftypefun
812
813Finally, if you neither insert nor delete text, but directly modify the
814existing text (e.g., change its case), call @code{rl_modifying()}
815once, just before you modify the text.  You must supply the indices of
816the text range that you are going to modify.
817
818@deftypefun int rl_modifying (int start, int end)
819Tell Readline to save the text between @var{start} and @var{end} as a
820single undo unit.  It is assumed that you will subsequently modify
821that text.
822@end deftypefun
823
824@node Redisplay
825@subsection Redisplay
826
827@deftypefun void rl_redisplay (void)
828Change what's displayed on the screen to reflect the current contents
829of @code{rl_line_buffer}.
830@end deftypefun
831
832@deftypefun int rl_forced_update_display (void)
833Force the line to be updated and redisplayed, whether or not
834Readline thinks the screen display is correct.
835@end deftypefun
836
837@deftypefun int rl_on_new_line (void)
838Tell the update functions that we have moved onto a new (empty) line,
839usually after ouputting a newline.
840@end deftypefun
841
842@deftypefun int rl_on_new_line_with_prompt (void)
843Tell the update functions that we have moved onto a new line, with
844@var{rl_prompt} already displayed.
845This could be used by applications that want to output the prompt string
846themselves, but still need Readline to know the prompt string length for
847redisplay.
848It should be used after setting @var{rl_already_prompted}.
849@end deftypefun
850
851@deftypefun int rl_reset_line_state (void)
852Reset the display state to a clean state and redisplay the current line
853starting on a new line.
854@end deftypefun
855
856@deftypefun int rl_crlf (void)
857Move the cursor to the start of the next screen line.
858@end deftypefun
859
860@deftypefun int rl_show_char (int c)
861Display character @var{c} on @code{rl_outstream}.
862If Readline has not been set to display meta characters directly, this
863will convert meta characters to a meta-prefixed key sequence.
864This is intended for use by applications which wish to do their own
865redisplay.
866@end deftypefun
867
868@deftypefun int rl_message (const char *, @dots{})
869The arguments are a format string as would be supplied to @code{printf},
870possibly containing conversion specifications such as @samp{%d}, and
871any additional arguments necessary to satisfy the conversion specifications.
872The resulting string is displayed in the @dfn{echo area}.  The echo area
873is also used to display numeric arguments and search strings.
874@end deftypefun
875
876@deftypefun int rl_clear_message (void)
877Clear the message in the echo area.
878@end deftypefun
879
880@deftypefun void rl_save_prompt (void)
881Save the local Readline prompt display state in preparation for
882displaying a new message in the message area with @code{rl_message()}.
883@end deftypefun
884
885@deftypefun void rl_restore_prompt (void)
886Restore the local Readline prompt display state saved by the most
887recent call to @code{rl_save_prompt}.
888@end deftypefun
889
890@deftypefun int rl_expand_prompt (char *prompt)
891Expand any special character sequences in @var{prompt} and set up the
892local Readline prompt redisplay variables.
893This function is called by @code{readline()}.  It may also be called to
894expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
895function or @code{rl_already_prompted} variable is used.
896It returns the number of visible characters on the last line of the
897(possibly multi-line) prompt.
898@end deftypefun
899
900@deftypefun int rl_set_prompt (const char *prompt)
901Make Readline use @var{prompt} for subsequent redisplay.  This calls
902@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
903to the result.
904@end deftypefun
905
906@node Modifying Text
907@subsection Modifying Text
908
909@deftypefun int rl_insert_text (const char *text)
910Insert @var{text} into the line at the current cursor position.
911Returns the number of characters inserted.
912@end deftypefun
913
914@deftypefun int rl_delete_text (int start, int end)
915Delete the text between @var{start} and @var{end} in the current line.
916Returns the number of characters deleted.
917@end deftypefun
918
919@deftypefun {char *} rl_copy_text (int start, int end)
920Return a copy of the text between @var{start} and @var{end} in
921the current line.
922@end deftypefun
923
924@deftypefun int rl_kill_text (int start, int end)
925Copy the text between @var{start} and @var{end} in the current line
926to the kill ring, appending or prepending to the last kill if the
927last command was a kill command.  The text is deleted.
928If @var{start} is less than @var{end},
929the text is appended, otherwise prepended.  If the last command was
930not a kill, a new kill ring slot is used.
931@end deftypefun
932
933@deftypefun int rl_push_macro_input (char *macro)
934Cause @var{macro} to be inserted into the line, as if it had been invoked
935by a key bound to a macro.  Not especially useful; use
936@code{rl_insert_text()} instead.
937@end deftypefun
938
939@node Character Input
940@subsection Character Input
941
942@deftypefun int rl_read_key (void)
943Return the next character available from Readline's current input stream.
944This handles input inserted into
945the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
946and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
947While waiting for input, this function will call any function assigned to
948the @code{rl_event_hook} variable.
949@end deftypefun
950
951@deftypefun int rl_getc (FILE *stream)
952Return the next character available from @var{stream}, which is assumed to
953be the keyboard.
954@end deftypefun
955
956@deftypefun int rl_stuff_char (int c)
957Insert @var{c} into the Readline input stream.  It will be "read"
958before Readline attempts to read characters from the terminal with
959@code{rl_read_key()}.  Up to 512 characters may be pushed back.
960@code{rl_stuff_char} returns 1 if the character was successfully inserted;
9610 otherwise.
962@end deftypefun
963
964@deftypefun int rl_execute_next (int c)
965Make @var{c} be the next command to be executed when @code{rl_read_key()}
966is called.  This sets @var{rl_pending_input}.
967@end deftypefun
968
969@deftypefun int rl_clear_pending_input (void)
970Unset @var{rl_pending_input}, effectively negating the effect of any
971previous call to @code{rl_execute_next()}.  This works only if the
972pending input has not already been read with @code{rl_read_key()}.
973@end deftypefun
974
975@deftypefun int rl_set_keyboard_input_timeout (int u)
976While waiting for keyboard input in @code{rl_read_key()}, Readline will
977wait for @var{u} microseconds for input before calling any function
978assigned to @code{rl_event_hook}.  The default waiting period is
979one-tenth of a second.  Returns the old timeout value.
980@end deftypefun
981
982@node Terminal Management
983@subsection Terminal Management
984
985@deftypefun void rl_prep_terminal (int meta_flag)
986Modify the terminal settings for Readline's use, so @code{readline()}
987can read a single character at a time from the keyboard.
988The @var{meta_flag} argument should be non-zero if Readline should
989read eight-bit input.
990@end deftypefun
991
992@deftypefun void rl_deprep_terminal (void)
993Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
994the state in which it was before the most recent call to
995@code{rl_prep_terminal()}.
996@end deftypefun
997
998@deftypefun void rl_tty_set_default_bindings (Keymap kmap)
999Read the operating system's terminal editing characters (as would be displayed
1000by @code{stty}) to their Readline equivalents.  The bindings are performed
1001in @var{kmap}.
1002@end deftypefun
1003
1004@deftypefun int rl_reset_terminal (const char *terminal_name)
1005Reinitialize Readline's idea of the terminal settings using
1006@var{terminal_name} as the terminal type (e.g., @code{vt100}).
1007If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
1008environment variable is used.
1009@end deftypefun
1010
1011@node Utility Functions
1012@subsection Utility Functions
1013
1014@deftypefun void rl_replace_line (const char *text, int clear_undo)
1015Replace the contents of @code{rl_line_buffer} with @var{text}.
1016The point and mark are preserved, if possible.
1017If @var{clear_undo} is non-zero, the undo list associated with the
1018current line is cleared.
1019@end deftypefun
1020
1021@deftypefun int rl_extend_line_buffer (int len)
1022Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
1023characters, possibly reallocating it if necessary.
1024@end deftypefun
1025
1026@deftypefun int rl_initialize (void)
1027Initialize or re-initialize Readline's internal state.
1028It's not strictly necessary to call this; @code{readline()} calls it before
1029reading any input.
1030@end deftypefun
1031
1032@deftypefun int rl_ding (void)
1033Ring the terminal bell, obeying the setting of @code{bell-style}.
1034@end deftypefun
1035
1036@deftypefun int rl_alphabetic (int c)
1037Return 1 if @var{c} is an alphabetic character.
1038@end deftypefun
1039
1040@deftypefun void rl_display_match_list (char **matches, int len, int max)
1041A convenience function for displaying a list of strings in
1042columnar format on Readline's output stream.  @code{matches} is the list
1043of strings, in argv format, such as a list of completion matches.
1044@code{len} is the number of strings in @code{matches}, and @code{max}
1045is the length of the longest string in @code{matches}.  This function uses
1046the setting of @code{print-completions-horizontally} to select how the
1047matches are displayed (@pxref{Readline Init File Syntax}).
1048@end deftypefun
1049
1050The following are implemented as macros, defined in @code{chardefs.h}.
1051Applications should refrain from using them.
1052
1053@deftypefun int _rl_uppercase_p (int c)
1054Return 1 if @var{c} is an uppercase alphabetic character.
1055@end deftypefun
1056
1057@deftypefun int _rl_lowercase_p (int c)
1058Return 1 if @var{c} is a lowercase alphabetic character.
1059@end deftypefun
1060
1061@deftypefun int _rl_digit_p (int c)
1062Return 1 if @var{c} is a numeric character.
1063@end deftypefun
1064
1065@deftypefun int _rl_to_upper (int c)
1066If @var{c} is a lowercase alphabetic character, return the corresponding
1067uppercase character.
1068@end deftypefun
1069
1070@deftypefun int _rl_to_lower (int c)
1071If @var{c} is an uppercase alphabetic character, return the corresponding
1072lowercase character.
1073@end deftypefun
1074
1075@deftypefun int _rl_digit_value (int c)
1076If @var{c} is a number, return the value it represents.
1077@end deftypefun
1078
1079@node Miscellaneous Functions
1080@subsection Miscellaneous Functions
1081
1082@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
1083Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
1084The binding is performed in @var{map}.  When @var{keyseq} is invoked, the
1085@var{macro} will be inserted into the line.  This function is deprecated;
1086use @code{rl_generic_bind()} instead.
1087@end deftypefun
1088
1089@deftypefun void rl_macro_dumper (int readable)
1090Print the key sequences bound to macros and their values, using
1091the current keymap, to @code{rl_outstream}.
1092If @var{readable} is non-zero, the list is formatted in such a way
1093that it can be made part of an @code{inputrc} file and re-read.
1094@end deftypefun
1095
1096@deftypefun int rl_variable_bind (const char *variable, const char *value)
1097Make the Readline variable @var{variable} have @var{value}.
1098This behaves as if the readline command
1099@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
1100file (@pxref{Readline Init File Syntax}).
1101@end deftypefun
1102
1103@deftypefun void rl_variable_dumper (int readable)
1104Print the readline variable names and their current values
1105to @code{rl_outstream}.
1106If @var{readable} is non-zero, the list is formatted in such a way
1107that it can be made part of an @code{inputrc} file and re-read.
1108@end deftypefun
1109
1110@deftypefun int rl_set_paren_blink_timeout (int u)
1111Set the time interval (in microseconds) that Readline waits when showing
1112a balancing character when @code{blink-matching-paren} has been enabled.
1113@end deftypefun
1114
1115@deftypefun {char *} rl_get_termcap (const char *cap)
1116Retrieve the string value of the termcap capability @var{cap}.
1117Readline fetches the termcap entry for the current terminal name and
1118uses those capabilities to move around the screen line and perform other
1119terminal-specific operations, like erasing a line.  Readline does not
1120use all of a terminal's capabilities, and this function will return
1121values for only those capabilities Readline uses.
1122@end deftypefun
1123
1124@node Alternate Interface
1125@subsection Alternate Interface
1126
1127An alternate interface is available to plain @code{readline()}.  Some
1128applications need to interleave keyboard I/O with file, device, or
1129window system I/O, typically by using a main loop to @code{select()}
1130on various file descriptors.  To accomodate this need, readline can
1131also be invoked as a `callback' function from an event loop.  There
1132are functions available to make this easy.
1133
1134@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
1135Set up the terminal for readline I/O and display the initial
1136expanded value of @var{prompt}.  Save the value of @var{lhandler} to
1137use as a function to call when a complete line of input has been entered.
1138The function takes the text of the line as an argument.
1139@end deftypefun
1140
1141@deftypefun void rl_callback_read_char (void)
1142Whenever an application determines that keyboard input is available, it
1143should call @code{rl_callback_read_char()}, which will read the next
1144character from the current input source.
1145If that character completes the line, @code{rl_callback_read_char} will
1146invoke the @var{lhandler} function saved by @code{rl_callback_handler_install}
1147to process the line.
1148Before calling the @var{lhandler} function, the terminal settings are
1149reset to the values they had before calling
1150@code{rl_callback_handler_install}.
1151If the @var{lhandler} function returns,
1152the terminal settings are modified for Readline's use again.
1153@code{EOF} is  indicated by calling @var{lhandler} with a
1154@code{NULL} line.
1155@end deftypefun
1156
1157@deftypefun void rl_callback_handler_remove (void)
1158Restore the terminal to its initial state and remove the line handler.
1159This may be called from within a callback as well as independently.
1160If the @var{lhandler} installed by @code{rl_callback_handler_install}
1161does not exit the program, either this function or the function referred
1162to by the value of @code{rl_deprep_term_function} should be called before
1163the program exits to reset the terminal settings.
1164@end deftypefun
1165
1166@node A Readline Example
1167@subsection A Readline Example
1168
1169Here is a function which changes lowercase characters to their uppercase
1170equivalents, and uppercase characters to lowercase.  If
1171this function was bound to @samp{M-c}, then typing @samp{M-c} would
1172change the case of the character under point.  Typing @samp{M-1 0 M-c}
1173would change the case of the following 10 characters, leaving the cursor on
1174the last character changed.
1175
1176@example
1177/* Invert the case of the COUNT following characters. */
1178int
1179invert_case_line (count, key)
1180     int count, key;
1181@{
1182  register int start, end, i;
1183
1184  start = rl_point;
1185
1186  if (rl_point >= rl_end)
1187    return (0);
1188
1189  if (count < 0)
1190    @{
1191      direction = -1;
1192      count = -count;
1193    @}
1194  else
1195    direction = 1;
1196
1197  /* Find the end of the range to modify. */
1198  end = start + (count * direction);
1199
1200  /* Force it to be within range. */
1201  if (end > rl_end)
1202    end = rl_end;
1203  else if (end < 0)
1204    end = 0;
1205
1206  if (start == end)
1207    return (0);
1208
1209  if (start > end)
1210    @{
1211      int temp = start;
1212      start = end;
1213      end = temp;
1214    @}
1215
1216  /* Tell readline that we are modifying the line,
1217     so it will save the undo information. */
1218  rl_modifying (start, end);
1219
1220  for (i = start; i != end; i++)
1221    @{
1222      if (_rl_uppercase_p (rl_line_buffer[i]))
1223        rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
1224      else if (_rl_lowercase_p (rl_line_buffer[i]))
1225        rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
1226    @}
1227  /* Move point to on top of the last character changed. */
1228  rl_point = (direction == 1) ? end - 1 : start;
1229  return (0);
1230@}
1231@end example
1232
1233@node Readline Signal Handling
1234@section Readline Signal Handling
1235
1236Signals are asynchronous events sent to a process by the Unix kernel,
1237sometimes on behalf of another process.  They are intended to indicate
1238exceptional events, like a user pressing the interrupt key on his terminal,
1239or a network connection being broken.  There is a class of signals that can
1240be sent to the process currently reading input from the keyboard.  Since
1241Readline changes the terminal attributes when it is called, it needs to
1242perform special processing when such a signal is received in order to
1243restore the terminal to a sane state, or provide application writers with
1244functions to do so manually.
1245
1246Readline contains an internal signal handler that is installed for a
1247number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
1248@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
1249When one of these signals is received, the signal handler
1250will reset the terminal attributes to those that were in effect before
1251@code{readline()} was called, reset the signal handling to what it was
1252before @code{readline()} was called, and resend the signal to the calling
1253application.
1254If and when the calling application's signal handler returns, Readline
1255will reinitialize the terminal and continue to accept input.
1256When a @code{SIGINT} is received, the Readline signal handler performs
1257some additional work, which will cause any partially-entered line to be
1258aborted (see the description of @code{rl_free_line_state()} below).
1259
1260There is an additional Readline signal handler, for @code{SIGWINCH}, which
1261the kernel sends to a process whenever the terminal's size changes (for
1262example, if a user resizes an @code{xterm}).  The Readline @code{SIGWINCH}
1263handler updates Readline's internal screen size information, and then calls
1264any @code{SIGWINCH} signal handler the calling application has installed.
1265Readline calls the application's @code{SIGWINCH} signal handler without
1266resetting the terminal to its original state.  If the application's signal
1267handler does more than update its idea of the terminal size and return (for
1268example, a @code{longjmp} back to a main processing loop), it @emph{must}
1269call @code{rl_cleanup_after_signal()} (described below), to restore the
1270terminal state.
1271
1272Readline provides two variables that allow application writers to
1273control whether or not it will catch certain signals and act on them
1274when they are received.  It is important that applications change the
1275values of these variables only when calling @code{readline()}, not in
1276a signal handler, so Readline's internal signal state is not corrupted.
1277
1278@deftypevar int rl_catch_signals
1279If this variable is non-zero, Readline will install signal handlers for
1280@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
1281@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
1282
1283The default value of @code{rl_catch_signals} is 1.
1284@end deftypevar
1285
1286@deftypevar int rl_catch_sigwinch
1287If this variable is non-zero, Readline will install a signal handler for
1288@code{SIGWINCH}.
1289
1290The default value of @code{rl_catch_sigwinch} is 1.
1291@end deftypevar
1292
1293If an application does not wish to have Readline catch any signals, or
1294to handle signals other than those Readline catches (@code{SIGHUP},
1295for example),
1296Readline provides convenience functions to do the necessary terminal
1297and internal state cleanup upon receipt of a signal.
1298
1299@deftypefun void rl_cleanup_after_signal (void)
1300This function will reset the state of the terminal to what it was before
1301@code{readline()} was called, and remove the Readline signal handlers for
1302all signals, depending on the values of @code{rl_catch_signals} and
1303@code{rl_catch_sigwinch}.
1304@end deftypefun
1305
1306@deftypefun void rl_free_line_state (void)
1307This will free any partial state associated with the current input line
1308(undo information, any partial history entry, any partially-entered
1309keyboard macro, and any partially-entered numeric argument).  This
1310should be called before @code{rl_cleanup_after_signal()}.  The
1311Readline signal handler for @code{SIGINT} calls this to abort the
1312current input line.
1313@end deftypefun
1314
1315@deftypefun void rl_reset_after_signal (void)
1316This will reinitialize the terminal and reinstall any Readline signal
1317handlers, depending on the values of @code{rl_catch_signals} and
1318@code{rl_catch_sigwinch}.
1319@end deftypefun
1320
1321If an application does not wish Readline to catch @code{SIGWINCH}, it may
1322call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
1323Readline to update its idea of the terminal size when a @code{SIGWINCH}
1324is received.
1325
1326@deftypefun void rl_resize_terminal (void)
1327Update Readline's internal screen size by reading values from the kernel.
1328@end deftypefun
1329
1330@deftypefun void rl_set_screen_size (int rows, int cols)
1331Set Readline's idea of the terminal size to @var{rows} rows and
1332@var{cols} columns.
1333@end deftypefun
1334
1335If an application does not want to install a @code{SIGWINCH} handler, but
1336is still interested in the screen dimensions, Readline's idea of the screen
1337size may be queried.
1338
1339@deftypefun void rl_get_screen_size (int *rows, int *cols)
1340Return Readline's idea of the terminal's size in the
1341variables pointed to by the arguments.
1342@end deftypefun
1343
1344The following functions install and remove Readline's signal handlers.
1345
1346@deftypefun int rl_set_signals (void)
1347Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
1348@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
1349@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
1350@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
1351@end deftypefun
1352
1353@deftypefun int rl_clear_signals (void)
1354Remove all of the Readline signal handlers installed by
1355@code{rl_set_signals()}.
1356@end deftypefun
1357
1358@node Custom Completers
1359@section Custom Completers
1360
1361Typically, a program that reads commands from the user has a way of
1362disambiguating commands and data.  If your program is one of these, then
1363it can provide completion for commands, data, or both.
1364The following sections describe how your program and Readline
1365cooperate to provide this service.
1366
1367@menu
1368* How Completing Works::	The logic used to do completion.
1369* Completion Functions::	Functions provided by Readline.
1370* Completion Variables::	Variables which control completion.
1371* A Short Completion Example::	An example of writing completer subroutines.
1372@end menu
1373
1374@node How Completing Works
1375@subsection How Completing Works
1376
1377In order to complete some text, the full list of possible completions
1378must be available.  That is, it is not possible to accurately
1379expand a partial word without knowing all of the possible words
1380which make sense in that context.  The Readline library provides
1381the user interface to completion, and two of the most common
1382completion functions:  filename and username.  For completing other types
1383of text, you must write your own completion function.  This section
1384describes exactly what such functions must do, and provides an example.
1385
1386There are three major functions used to perform completion:
1387
1388@enumerate
1389@item
1390The user-interface function @code{rl_complete()}.  This function is
1391called with the same arguments as other bindable Readline functions:
1392@var{count} and @var{invoking_key}.
1393It isolates the word to be completed and calls
1394@code{rl_completion_matches()} to generate a list of possible completions.
1395It then either lists the possible completions, inserts the possible
1396completions, or actually performs the
1397completion, depending on which behavior is desired.
1398
1399@item
1400The internal function @code{rl_completion_matches()} uses an
1401application-supplied @dfn{generator} function to generate the list of
1402possible matches, and then returns the array of these matches.
1403The caller should place the address of its generator function in
1404@code{rl_completion_entry_function}.
1405
1406@item
1407The generator function is called repeatedly from
1408@code{rl_completion_matches()}, returning a string each time.  The
1409arguments to the generator function are @var{text} and @var{state}.
1410@var{text} is the partial word to be completed.  @var{state} is zero the
1411first time the function is called, allowing the generator to perform
1412any necessary initialization, and a positive non-zero integer for
1413each subsequent call.  The generator function returns
1414@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
1415no more possibilities left.  Usually the generator function computes the
1416list of possible completions when @var{state} is zero, and returns them
1417one at a time on subsequent calls.  Each string the generator function
1418returns as a match must be allocated with @code{malloc()}; Readline
1419frees the strings when it has finished with them.
1420
1421@end enumerate
1422
1423@deftypefun int rl_complete (int ignore, int invoking_key)
1424Complete the word at or before point.  You have supplied the function
1425that does the initial simple matching selection algorithm (see
1426@code{rl_completion_matches()}).  The default is to do filename completion.
1427@end deftypefun
1428
1429@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1430This is a pointer to the generator function for
1431@code{rl_completion_matches()}.
1432If the value of @code{rl_completion_entry_function} is
1433@code{NULL} then the default filename generator
1434function, @code{rl_filename_completion_function()}, is used.
1435@end deftypevar
1436
1437@node Completion Functions
1438@subsection Completion Functions
1439
1440Here is the complete list of callable completion functions present in
1441Readline.
1442
1443@deftypefun int rl_complete_internal (int what_to_do)
1444Complete the word at or before point.  @var{what_to_do} says what to do
1445with the completion.  A value of @samp{?} means list the possible
1446completions.  @samp{TAB} means do standard completion.  @samp{*} means
1447insert all of the possible completions.  @samp{!} means to display
1448all of the possible completions, if there is more than one, as well as
1449performing partial completion.
1450@end deftypefun
1451
1452@deftypefun int rl_complete (int ignore, int invoking_key)
1453Complete the word at or before point.  You have supplied the function
1454that does the initial simple matching selection algorithm (see
1455@code{rl_completion_matches()} and @code{rl_completion_entry_function}).
1456The default is to do filename
1457completion.  This calls @code{rl_complete_internal()} with an
1458argument depending on @var{invoking_key}.
1459@end deftypefun
1460
1461@deftypefun int rl_possible_completions (int count, int invoking_key)
1462List the possible completions.  See description of @code{rl_complete
1463()}.  This calls @code{rl_complete_internal()} with an argument of
1464@samp{?}.
1465@end deftypefun
1466
1467@deftypefun int rl_insert_completions (int count, int invoking_key)
1468Insert the list of possible completions into the line, deleting the
1469partially-completed word.  See description of @code{rl_complete()}.
1470This calls @code{rl_complete_internal()} with an argument of @samp{*}.
1471@end deftypefun
1472
1473@deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
1474Returns the apppriate value to pass to @code{rl_complete_internal()}
1475depending on whether @var{cfunc} was called twice in succession and
1476the value of the @code{show-all-if-ambiguous} variable.
1477Application-specific completion functions may use this function to present
1478the same interface as @code{rl_complete()}.
1479@end deftypefun
1480
1481@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
1482Returns an array of strings which is a list of completions for
1483@var{text}.  If there are no completions, returns @code{NULL}.
1484The first entry in the returned array is the substitution for @var{text}.
1485The remaining entries are the possible completions.  The array is
1486terminated with a @code{NULL} pointer.
1487
1488@var{entry_func} is a function of two args, and returns a
1489@code{char *}.  The first argument is @var{text}.  The second is a
1490state argument; it is zero on the first call, and non-zero on subsequent
1491calls.  @var{entry_func} returns a @code{NULL}  pointer to the caller
1492when there are no more matches.
1493@end deftypefun
1494
1495@deftypefun {char *} rl_filename_completion_function (const char *text, int state)
1496A generator function for filename completion in the general case.
1497@var{text} is a partial filename.
1498The Bash source is a useful reference for writing custom
1499completion functions (the Bash completion functions call this and other
1500Readline functions).
1501@end deftypefun
1502
1503@deftypefun {char *} rl_username_completion_function (const char *text, int state)
1504A completion generator for usernames.  @var{text} contains a partial
1505username preceded by a random character (usually @samp{~}).  As with all
1506completion generators, @var{state} is zero on the first call and non-zero
1507for subsequent calls.
1508@end deftypefun
1509
1510@node Completion Variables
1511@subsection Completion Variables
1512
1513@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1514A pointer to the generator function for @code{rl_completion_matches()}.
1515@code{NULL} means to use @code{rl_filename_completion_function()}, the default
1516filename completer.
1517@end deftypevar
1518
1519@deftypevar {rl_completion_func_t *} rl_attempted_completion_function
1520A pointer to an alternative function to create matches.
1521The function is called with @var{text}, @var{start}, and @var{end}.
1522@var{start} and @var{end} are indices in @code{rl_line_buffer} defining
1523the boundaries of @var{text}, which is a character string.
1524If this function exists and returns @code{NULL}, or if this variable is
1525set to @code{NULL}, then @code{rl_complete()} will call the value of
1526@code{rl_completion_entry_function} to generate matches, otherwise the
1527array of strings returned will be used.
1528If this function sets the @code{rl_attempted_completion_over}
1529variable to a non-zero value, Readline will not perform its default
1530completion even if this function returns no matches.
1531@end deftypevar
1532
1533@deftypevar {rl_quote_func_t *} rl_filename_quoting_function
1534A pointer to a function that will quote a filename in an
1535application-specific fashion.  This is called if filename completion is being
1536attempted and one of the characters in @code{rl_filename_quote_characters}
1537appears in a completed filename.  The function is called with
1538@var{text}, @var{match_type}, and @var{quote_pointer}.  The @var{text}
1539is the filename to be quoted.  The @var{match_type} is either
1540@code{SINGLE_MATCH}, if there is only one completion match, or
1541@code{MULT_MATCH}.  Some functions use this to decide whether or not to
1542insert a closing quote character.  The @var{quote_pointer} is a pointer
1543to any opening quote character the user typed.  Some functions choose
1544to reset this character.
1545@end deftypevar
1546
1547@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
1548A pointer to a function that will remove application-specific quoting
1549characters from a filename before completion is attempted, so those
1550characters do not interfere with matching the text against names in
1551the filesystem.  It is called with @var{text}, the text of the word
1552to be dequoted, and @var{quote_char}, which is the quoting character
1553that delimits the filename (usually @samp{'} or @samp{"}).  If
1554@var{quote_char} is zero, the filename was not in an embedded string.
1555@end deftypevar
1556
1557@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
1558A pointer to a function to call that determines whether or not a specific
1559character in the line buffer is quoted, according to whatever quoting
1560mechanism the program calling Readline uses.  The function is called with
1561two arguments: @var{text}, the text of the line, and @var{index}, the
1562index of the character in the line.  It is used to decide whether a
1563character found in @code{rl_completer_word_break_characters} should be
1564used to break words for the completer.
1565@end deftypevar
1566
1567@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
1568This function, if defined, is called by the completer when real filename
1569completion is done, after all the matching names have been generated.
1570It is passed a @code{NULL} terminated array of matches.
1571The first element (@code{matches[0]}) is the
1572maximal substring common to all matches. This function can
1573re-arrange the list of matches as required, but each element deleted
1574from the array must be freed.
1575@end deftypevar
1576
1577@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
1578This function, if defined, is allowed to modify the directory portion
1579of filenames Readline completes.  It is called with the address of a
1580string (the current directory name) as an argument, and may modify that string.
1581If the string is replaced with a new string, the old value should be freed.
1582Any modified directory name should have a trailing slash.
1583The modified value will be displayed as part of the completion, replacing
1584the directory portion of the pathname the user typed.
1585It returns an integer that should be non-zero if the function modifies
1586its directory argument.
1587It could be used to expand symbolic links or shell variables in pathnames.
1588@end deftypevar
1589
1590@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
1591If non-zero, then this is the address of a function to call when
1592completing a word would normally display the list of possible matches.
1593This function is called in lieu of Readline displaying the list.
1594It takes three arguments:
1595(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
1596where @var{matches} is the array of matching strings,
1597@var{num_matches} is the number of strings in that array, and
1598@var{max_length} is the length of the longest string in that array.
1599Readline provides a convenience function, @code{rl_display_match_list},
1600that takes care of doing the display to Readline's output stream.  That
1601function may be called from this hook.
1602@end deftypevar
1603
1604@deftypevar {const char *} rl_basic_word_break_characters
1605The basic list of characters that signal a break between words for the
1606completer routine.  The default value of this variable is the characters
1607which break words for completion in Bash:
1608@code{" \t\n\"\\'`@@$><=;|&@{("}.
1609@end deftypevar
1610
1611@deftypevar {const char *} rl_basic_quote_characters
1612A list of quote characters which can cause a word break.
1613@end deftypevar
1614
1615@deftypevar {const char *} rl_completer_word_break_characters
1616The list of characters that signal a break between words for
1617@code{rl_complete_internal()}.  The default list is the value of
1618@code{rl_basic_word_break_characters}.
1619@end deftypevar
1620
1621@deftypevar {const char *} rl_completer_quote_characters
1622A list of characters which can be used to quote a substring of the line.
1623Completion occurs on the entire substring, and within the substring
1624@code{rl_completer_word_break_characters} are treated as any other character,
1625unless they also appear within this list.
1626@end deftypevar
1627
1628@deftypevar {const char *} rl_filename_quote_characters
1629A list of characters that cause a filename to be quoted by the completer
1630when they appear in a completed filename.  The default is the null string.
1631@end deftypevar
1632
1633@deftypevar {const char *} rl_special_prefixes
1634The list of characters that are word break characters, but should be
1635left in @var{text} when it is passed to the completion function.
1636Programs can use this to help determine what kind of completing to do.
1637For instance, Bash sets this variable to "$@@" so that it can complete
1638shell variables and hostnames.
1639@end deftypevar
1640
1641@deftypevar int rl_completion_query_items
1642Up to this many items will be displayed in response to a
1643possible-completions call.  After that, we ask the user if she is sure
1644she wants to see them all.  The default value is 100.
1645@end deftypevar
1646
1647@deftypevar {int} rl_completion_append_character
1648When a single completion alternative matches at the end of the command
1649line, this character is appended to the inserted completion text.  The
1650default is a space character (@samp{ }).  Setting this to the null
1651character (@samp{\0}) prevents anything being appended automatically.
1652This can be changed in custom completion functions to
1653provide the ``most sensible word separator character'' according to
1654an application-specific command line syntax specification.
1655@end deftypevar
1656
1657@deftypevar int rl_completion_suppress_append
1658If non-zero, @var{rl_completion_append_character} is not appended to
1659matches at the end of the command line, as described above.  It is
1660set to 0 before any application-specific completion function is called.
1661@end deftypevar
1662
1663@deftypevar int rl_completion_mark_symlink_dirs
1664If non-zero, a slash will be appended to completed filenames that are
1665symbolic links to directory names, subject to the value of the
1666user-settable @var{mark-directories} variable.
1667This variable exists so that application completion functions can
1668override the user's global preference (set via the
1669@var{mark-symlinked-directories} Readline variable) if appropriate.
1670This variable is set to the user's preference before any
1671application completion function is called, so unless that function
1672modifies the value, the user's preferences are honored.
1673@end deftypevar
1674
1675@deftypevar int rl_ignore_completion_duplicates
1676If non-zero, then duplicates in the matches are removed.
1677The default is 1.
1678@end deftypevar
1679
1680@deftypevar int rl_filename_completion_desired
1681Non-zero means that the results of the matches are to be treated as
1682filenames.  This is @emph{always} zero on entry, and can only be changed
1683within a completion entry generator function.  If it is set to a non-zero
1684value, directory names have a slash appended and Readline attempts to
1685quote completed filenames if they contain any characters in
1686@code{rl_filename_quote_characters} and @code{rl_filename_quoting_desired}
1687is set to a non-zero value.
1688@end deftypevar
1689
1690@deftypevar int rl_filename_quoting_desired
1691Non-zero means that the results of the matches are to be quoted using
1692double quotes (or an application-specific quoting mechanism) if the
1693completed filename contains any characters in
1694@code{rl_filename_quote_chars}.  This is @emph{always} non-zero
1695on entry, and can only be changed within a completion entry generator
1696function.  The quoting is effected via a call to the function pointed to
1697by @code{rl_filename_quoting_function}.
1698@end deftypevar
1699
1700@deftypevar int rl_attempted_completion_over
1701If an application-specific completion function assigned to
1702@code{rl_attempted_completion_function} sets this variable to a non-zero
1703value, Readline will not perform its default filename completion even
1704if the application's completion function returns no matches.
1705It should be set only by an application's completion function.
1706@end deftypevar
1707
1708@deftypevar int rl_completion_type
1709Set to a character describing the type of completion Readline is currently
1710attempting; see the description of @code{rl_complete_internal()}
1711(@pxref{Completion Functions}) for the list of characters.
1712@end deftypevar
1713
1714@deftypevar int rl_inhibit_completion
1715If this variable is non-zero, completion is inhibited.  The completion
1716character will be inserted as any other bound to @code{self-insert}.
1717@end deftypevar
1718
1719@node A Short Completion Example
1720@subsection A Short Completion Example
1721
1722Here is a small application demonstrating the use of the GNU Readline
1723library.  It is called @code{fileman}, and the source code resides in
1724@file{examples/fileman.c}.  This sample application provides
1725completion of command names, line editing features, and access to the
1726history list.
1727
1728@page
1729@smallexample
1730/* fileman.c -- A tiny application which demonstrates how to use the
1731   GNU Readline library.  This application interactively allows users
1732   to manipulate files and their modes. */
1733
1734#include <stdio.h>
1735#include <sys/types.h>
1736#include <sys/file.h>
1737#include <sys/stat.h>
1738#include <sys/errno.h>
1739
1740#include <readline/readline.h>
1741#include <readline/history.h>
1742
1743extern char *xmalloc ();
1744
1745/* The names of functions that actually do the manipulation. */
1746int com_list __P((char *));
1747int com_view __P((char *));
1748int com_rename __P((char *));
1749int com_stat __P((char *));
1750int com_pwd __P((char *));
1751int com_delete __P((char *));
1752int com_help __P((char *));
1753int com_cd __P((char *));
1754int com_quit __P((char *));
1755
1756/* A structure which contains information on the commands this program
1757   can understand. */
1758
1759typedef struct @{
1760  char *name;			/* User printable name of the function. */
1761  rl_icpfunc_t *func;		/* Function to call to do the job. */
1762  char *doc;			/* Documentation for this function.  */
1763@} COMMAND;
1764
1765COMMAND commands[] = @{
1766  @{ "cd", com_cd, "Change to directory DIR" @},
1767  @{ "delete", com_delete, "Delete FILE" @},
1768  @{ "help", com_help, "Display this text" @},
1769  @{ "?", com_help, "Synonym for `help'" @},
1770  @{ "list", com_list, "List files in DIR" @},
1771  @{ "ls", com_list, "Synonym for `list'" @},
1772  @{ "pwd", com_pwd, "Print the current working directory" @},
1773  @{ "quit", com_quit, "Quit using Fileman" @},
1774  @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
1775  @{ "stat", com_stat, "Print out statistics on FILE" @},
1776  @{ "view", com_view, "View the contents of FILE" @},
1777  @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
1778@};
1779
1780/* Forward declarations. */
1781char *stripwhite ();
1782COMMAND *find_command ();
1783
1784/* The name of this program, as taken from argv[0]. */
1785char *progname;
1786
1787/* When non-zero, this means the user is done using this program. */
1788int done;
1789
1790char *
1791dupstr (s)
1792     int s;
1793@{
1794  char *r;
1795
1796  r = xmalloc (strlen (s) + 1);
1797  strcpy (r, s);
1798  return (r);
1799@}
1800
1801main (argc, argv)
1802     int argc;
1803     char **argv;
1804@{
1805  char *line, *s;
1806
1807  progname = argv[0];
1808
1809  initialize_readline ();	/* Bind our completer. */
1810
1811  /* Loop reading and executing lines until the user quits. */
1812  for ( ; done == 0; )
1813    @{
1814      line = readline ("FileMan: ");
1815
1816      if (!line)
1817        break;
1818
1819      /* Remove leading and trailing whitespace from the line.
1820         Then, if there is anything left, add it to the history list
1821         and execute it. */
1822      s = stripwhite (line);
1823
1824      if (*s)
1825        @{
1826          add_history (s);
1827          execute_line (s);
1828        @}
1829
1830      free (line);
1831    @}
1832  exit (0);
1833@}
1834
1835/* Execute a command line. */
1836int
1837execute_line (line)
1838     char *line;
1839@{
1840  register int i;
1841  COMMAND *command;
1842  char *word;
1843
1844  /* Isolate the command word. */
1845  i = 0;
1846  while (line[i] && whitespace (line[i]))
1847    i++;
1848  word = line + i;
1849
1850  while (line[i] && !whitespace (line[i]))
1851    i++;
1852
1853  if (line[i])
1854    line[i++] = '\0';
1855
1856  command = find_command (word);
1857
1858  if (!command)
1859    @{
1860      fprintf (stderr, "%s: No such command for FileMan.\n", word);
1861      return (-1);
1862    @}
1863
1864  /* Get argument to command, if any. */
1865  while (whitespace (line[i]))
1866    i++;
1867
1868  word = line + i;
1869
1870  /* Call the function. */
1871  return ((*(command->func)) (word));
1872@}
1873
1874/* Look up NAME as the name of a command, and return a pointer to that
1875   command.  Return a NULL pointer if NAME isn't a command name. */
1876COMMAND *
1877find_command (name)
1878     char *name;
1879@{
1880  register int i;
1881
1882  for (i = 0; commands[i].name; i++)
1883    if (strcmp (name, commands[i].name) == 0)
1884      return (&commands[i]);
1885
1886  return ((COMMAND *)NULL);
1887@}
1888
1889/* Strip whitespace from the start and end of STRING.  Return a pointer
1890   into STRING. */
1891char *
1892stripwhite (string)
1893     char *string;
1894@{
1895  register char *s, *t;
1896
1897  for (s = string; whitespace (*s); s++)
1898    ;
1899
1900  if (*s == 0)
1901    return (s);
1902
1903  t = s + strlen (s) - 1;
1904  while (t > s && whitespace (*t))
1905    t--;
1906  *++t = '\0';
1907
1908  return s;
1909@}
1910
1911/* **************************************************************** */
1912/*                                                                  */
1913/*                  Interface to Readline Completion                */
1914/*                                                                  */
1915/* **************************************************************** */
1916
1917char *command_generator __P((const char *, int));
1918char **fileman_completion __P((const char *, int, int));
1919
1920/* Tell the GNU Readline library how to complete.  We want to try to
1921   complete on command names if this is the first word in the line, or
1922   on filenames if not. */
1923initialize_readline ()
1924@{
1925  /* Allow conditional parsing of the ~/.inputrc file. */
1926  rl_readline_name = "FileMan";
1927
1928  /* Tell the completer that we want a crack first. */
1929  rl_attempted_completion_function = fileman_completion;
1930@}
1931
1932/* Attempt to complete on the contents of TEXT.  START and END
1933   bound the region of rl_line_buffer that contains the word to
1934   complete.  TEXT is the word to complete.  We can use the entire
1935   contents of rl_line_buffer in case we want to do some simple
1936   parsing.  Returnthe array of matches, or NULL if there aren't any. */
1937char **
1938fileman_completion (text, start, end)
1939     const char *text;
1940     int start, end;
1941@{
1942  char **matches;
1943
1944  matches = (char **)NULL;
1945
1946  /* If this word is at the start of the line, then it is a command
1947     to complete.  Otherwise it is the name of a file in the current
1948     directory. */
1949  if (start == 0)
1950    matches = rl_completion_matches (text, command_generator);
1951
1952  return (matches);
1953@}
1954
1955/* Generator function for command completion.  STATE lets us
1956   know whether to start from scratch; without any state
1957   (i.e. STATE == 0), then we start at the top of the list. */
1958char *
1959command_generator (text, state)
1960     const char *text;
1961     int state;
1962@{
1963  static int list_index, len;
1964  char *name;
1965
1966  /* If this is a new word to complete, initialize now.  This
1967     includes saving the length of TEXT for efficiency, and
1968     initializing the index variable to 0. */
1969  if (!state)
1970    @{
1971      list_index = 0;
1972      len = strlen (text);
1973    @}
1974
1975  /* Return the next name which partially matches from the
1976     command list. */
1977  while (name = commands[list_index].name)
1978    @{
1979      list_index++;
1980
1981      if (strncmp (name, text, len) == 0)
1982        return (dupstr(name));
1983    @}
1984
1985  /* If no names matched, then return NULL. */
1986  return ((char *)NULL);
1987@}
1988
1989/* **************************************************************** */
1990/*                                                                  */
1991/*                       FileMan Commands                           */
1992/*                                                                  */
1993/* **************************************************************** */
1994
1995/* String to pass to system ().  This is for the LIST, VIEW and RENAME
1996   commands. */
1997static char syscom[1024];
1998
1999/* List the file(s) named in arg. */
2000com_list (arg)
2001     char *arg;
2002@{
2003  if (!arg)
2004    arg = "";
2005
2006  sprintf (syscom, "ls -FClg %s", arg);
2007  return (system (syscom));
2008@}
2009
2010com_view (arg)
2011     char *arg;
2012@{
2013  if (!valid_argument ("view", arg))
2014    return 1;
2015
2016  sprintf (syscom, "more %s", arg);
2017  return (system (syscom));
2018@}
2019
2020com_rename (arg)
2021     char *arg;
2022@{
2023  too_dangerous ("rename");
2024  return (1);
2025@}
2026
2027com_stat (arg)
2028     char *arg;
2029@{
2030  struct stat finfo;
2031
2032  if (!valid_argument ("stat", arg))
2033    return (1);
2034
2035  if (stat (arg, &finfo) == -1)
2036    @{
2037      perror (arg);
2038      return (1);
2039    @}
2040
2041  printf ("Statistics for `%s':\n", arg);
2042
2043  printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
2044          finfo.st_nlink,
2045          (finfo.st_nlink == 1) ? "" : "s",
2046          finfo.st_size,
2047          (finfo.st_size == 1) ? "" : "s");
2048  printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
2049  printf ("      Last access at: %s", ctime (&finfo.st_atime));
2050  printf ("    Last modified at: %s", ctime (&finfo.st_mtime));
2051  return (0);
2052@}
2053
2054com_delete (arg)
2055     char *arg;
2056@{
2057  too_dangerous ("delete");
2058  return (1);
2059@}
2060
2061/* Print out help for ARG, or for all of the commands if ARG is
2062   not present. */
2063com_help (arg)
2064     char *arg;
2065@{
2066  register int i;
2067  int printed = 0;
2068
2069  for (i = 0; commands[i].name; i++)
2070    @{
2071      if (!*arg || (strcmp (arg, commands[i].name) == 0))
2072        @{
2073          printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
2074          printed++;
2075        @}
2076    @}
2077
2078  if (!printed)
2079    @{
2080      printf ("No commands match `%s'.  Possibilties are:\n", arg);
2081
2082      for (i = 0; commands[i].name; i++)
2083        @{
2084          /* Print in six columns. */
2085          if (printed == 6)
2086            @{
2087              printed = 0;
2088              printf ("\n");
2089            @}
2090
2091          printf ("%s\t", commands[i].name);
2092          printed++;
2093        @}
2094
2095      if (printed)
2096        printf ("\n");
2097    @}
2098  return (0);
2099@}
2100
2101/* Change to the directory ARG. */
2102com_cd (arg)
2103     char *arg;
2104@{
2105  if (chdir (arg) == -1)
2106    @{
2107      perror (arg);
2108      return 1;
2109    @}
2110
2111  com_pwd ("");
2112  return (0);
2113@}
2114
2115/* Print out the current working directory. */
2116com_pwd (ignore)
2117     char *ignore;
2118@{
2119  char dir[1024], *s;
2120
2121  s = getcwd (dir, sizeof(dir) - 1);
2122  if (s == 0)
2123    @{
2124      printf ("Error getting pwd: %s\n", dir);
2125      return 1;
2126    @}
2127
2128  printf ("Current directory is %s\n", dir);
2129  return 0;
2130@}
2131
2132/* The user wishes to quit using this program.  Just set DONE
2133   non-zero. */
2134com_quit (arg)
2135     char *arg;
2136@{
2137  done = 1;
2138  return (0);
2139@}
2140
2141/* Function which tells you that you can't do this. */
2142too_dangerous (caller)
2143     char *caller;
2144@{
2145  fprintf (stderr,
2146           "%s: Too dangerous for me to distribute.\n"
2147           caller);
2148  fprintf (stderr, "Write it yourself.\n");
2149@}
2150
2151/* Return non-zero if ARG is a valid argument for CALLER,
2152   else print an error message and return zero. */
2153int
2154valid_argument (caller, arg)
2155     char *caller, *arg;
2156@{
2157  if (!arg || !*arg)
2158    @{
2159      fprintf (stderr, "%s: Argument required.\n", caller);
2160      return (0);
2161    @}
2162
2163  return (1);
2164@}
2165@end smallexample
2166