Move readline to the readline/readline subdirectory

readline turns out to be a bit of a stumbling block for the project to
move gdbsupport (and then gdbserver) to the top-level.

The issue is that readline headers are intended to be included with
names like "readline/readline.h".  To support this, gdb effectively
adds a -I option pointing to the top-level source directory -- but,
importantly, this option is not used when the system readline is used.

For gdbsupport, a -I option like this would always be needed, but that
in turn would break the system readline case.  This was PR build/17077,
fixed in commit a8a5dbcab8df0b3a9e04745d4fe8d64740acb323.

Previously, we had discussed this on the gdb-patches list in terms of
removing readline from the tree

    https://sourceware.org/ml/gdb-patches/2019-09/msg00317.html

However, Eli expressed some concerns, and Joel did as well (off-list).

Given those concerns, and the fact that a patch-free local readline is
relatively new in gdb (it was locally patched for years), I changed my
mind and decided to handle this situation by moving the readline
sources down a level.

That is, upstream readline is now in readline/readline, and the
top-level readline directory just contains the minimal configury
needed to build that.

This fixes the problem because, when gdb unconditionally adds a
-I$(top_srcdir), this will not find readline headers.  A separate -I
will be needed instead, which is exactly what's needed for
--with-system-readline.

gdb/ChangeLog
2019-10-23  Tom Tromey  <tom@tromey.com>

	* Makefile.in (READLINE_DIR): Update.

gdb/doc/ChangeLog
2019-10-23  Tom Tromey  <tom@tromey.com>

	* Makefile.in (READLINE_DIR): Update.

readline/ChangeLog
2019-10-23  Tom Tromey  <tom@tromey.com>

	Move old contents to readline/ subdirectory.
	* aclocal.m4, configure, configure.ac, .gitignore, Makefile.am,
	Makefile.in, README: New files.

Change-Id: Ice156a2ee09ea68722b48f64d97146d7428ea9e4

1 files changed, 0 insertions, 2731 deletions

diff --git a/readline/doc/rltech.texi b/readline/doc/rltech.texi
deleted file mode 100644
index 28a02d9..0000000
--- a/readline/doc/rltech.texi
+++ /dev/null
@@ -1,2731 +0,0 @@
-@comment %**start of header (This is for running Texinfo on a region.)
-@setfilename rltech.info
-@comment %**end of header (This is for running Texinfo on a region.)
-
-@ifinfo
-This document describes the GNU Readline Library, a utility for aiding
-in the consistency of user interface across discrete programs that need
-to provide a command line interface.
-
-Copyright (C) 1988--2016 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-pare preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Foundation.
-@end ifinfo
-
-@node Programming with GNU Readline
-@chapter Programming with GNU Readline
-
-This chapter describes the interface between the @sc{gnu} Readline Library and
-other programs.  If you are a programmer, and you wish to include the
-features found in @sc{gnu} Readline
-such as completion, line editing, and interactive history manipulation
-in your own programs, this section is for you.
-
-@menu
-* Basic Behavior::	Using the default behavior of Readline.
-* Custom Functions::	Adding your own functions to Readline.
-* Readline Variables::			Variables accessible to custom
-					functions.
-* Readline Convenience Functions::	Functions which Readline supplies to
-					aid in writing your own custom
-					functions.
-* Readline Signal Handling::	How Readline behaves when it receives signals.
-* Custom Completers::	Supplanting or supplementing Readline's
-			completion functions.
-@end menu
-
-@node Basic Behavior
-@section Basic Behavior
-
-Many programs provide a command line interface, such as @code{mail},
-@code{ftp}, and @code{sh}.  For such programs, the default behaviour of
-Readline is sufficient.  This section describes how to use Readline in
-the simplest way possible, perhaps to replace calls in your code to
-@code{gets()} or @code{fgets()}.
-
-@findex readline
-@cindex readline, function
-
-The function @code{readline()} prints a prompt @var{prompt}
-and then reads and returns a single line of text from the user.
-If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
-The line @code{readline} returns is allocated with @code{malloc()};
-the caller should @code{free()} the line when it has finished with it.
-The declaration for @code{readline} in ANSI C is
-
-@example
-@code{char *readline (const char *@var{prompt});}
-@end example
-
-@noindent
-So, one might say
-@example
-@code{char *line = readline ("Enter a line: ");}
-@end example
-@noindent
-in order to read a line of text from the user.
-The line returned has the final newline removed, so only the
-text remains.
-
-If @code{readline} encounters an @code{EOF} while reading the line, and the
-line is empty at that point, then @code{(char *)NULL} is returned.
-Otherwise, the line is ended just as if a newline had been typed.
-
-Readline performs some expansion on the @var{prompt} before it is
-displayed on the screen.  See the description of @code{rl_expand_prompt}
-(@pxref{Redisplay}) for additional details, especially if @var{prompt}
-will contain characters that do not consume physical screen space when
-displayed.
-
-If you want the user to be able to get at the line later, (with
-@key{C-p} for example), you must call @code{add_history()} to save the
-line away in a @dfn{history} list of such lines.
-
-@example
-@code{add_history (line)};
-@end example
-
-@noindent
-For full details on the GNU History Library, see the associated manual.
-
-It is preferable to avoid saving empty lines on the history list, since
-users rarely have a burning need to reuse a blank line.  Here is
-a function which usefully replaces the standard @code{gets()} library
-function, and has the advantage of no static buffer to overflow:
-
-@example
-/* A static variable for holding the line. */
-static char *line_read = (char *)NULL;
-
-/* Read a string, and return a pointer to it.
-   Returns NULL on EOF. */
-char *
-rl_gets ()
-@{
-  /* If the buffer has already been allocated,
-     return the memory to the free pool. */
-  if (line_read)
-    @{
-      free (line_read);
-      line_read = (char *)NULL;
-    @}
-
-  /* Get a line from the user. */
-  line_read = readline ("");
-
-  /* If the line has any text in it,
-     save it on the history. */
-  if (line_read && *line_read)
-    add_history (line_read);
-
-  return (line_read);
-@}
-@end example
-
-This function gives the user the default behaviour of @key{TAB}
-completion: completion on file names.  If you do not want Readline to
-complete on filenames, you can change the binding of the @key{TAB} key
-with @code{rl_bind_key()}.
-
-@example
-@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
-@end example
-
-@code{rl_bind_key()} takes two arguments: @var{key} is the character that
-you want to bind, and @var{function} is the address of the function to
-call when @var{key} is pressed.  Binding @key{TAB} to @code{rl_insert()}
-makes @key{TAB} insert itself.
-@code{rl_bind_key()} returns non-zero if @var{key} is not a valid
-ASCII character code (between 0 and 255).
-
-Thus, to disable the default @key{TAB} behavior, the following suffices:
-@example
-@code{rl_bind_key ('\t', rl_insert);}
-@end example
-
-This code should be executed once at the start of your program; you
-might write a function called @code{initialize_readline()} which
-performs this and other desired initializations, such as installing
-custom completers (@pxref{Custom Completers}).
-
-@node Custom Functions
-@section Custom Functions
-
-Readline provides many functions for manipulating the text of
-the line, but it isn't possible to anticipate the needs of all
-programs.  This section describes the various functions and variables
-defined within the Readline library which allow a user program to add
-customized functionality to Readline.
-
-Before declaring any functions that customize Readline's behavior, or
-using any functionality Readline provides in other code, an
-application writer should include the file @code{<readline/readline.h>}
-in any file that uses Readline's features.  Since some of the definitions
-in @code{readline.h} use the @code{stdio} library, the file
-@code{<stdio.h>} should be included before @code{readline.h}.
-
-@code{readline.h} defines a C preprocessor variable that should
-be treated as an integer, @code{RL_READLINE_VERSION}, which may
-be used to conditionally compile application code depending on
-the installed Readline version.  The value is a hexadecimal
-encoding of the major and minor version numbers of the library,
-of the form 0x@var{MMmm}.  @var{MM} is the two-digit major
-version number; @var{mm} is the two-digit minor version number. 
-For Readline 4.2, for example, the value of
-@code{RL_READLINE_VERSION} would be @code{0x0402}. 
-
-@menu
-* Readline Typedefs::	C declarations to make code readable.
-* Function Writing::	Variables and calling conventions.
-@end menu
-
-@node Readline Typedefs
-@subsection Readline Typedefs
-
-For readability, we declare a number of new object types, all pointers
-to functions.
-
-The reason for declaring these new types is to make it easier to write
-code describing pointers to C functions with appropriately prototyped
-arguments and return values.
-
-For instance, say we want to declare a variable @var{func} as a pointer
-to a function which takes two @code{int} arguments and returns an
-@code{int} (this is the type of all of the Readline bindable functions).
-Instead of the classic C declaration
-
-@code{int (*func)();}
-
-@noindent
-or the ANSI-C style declaration
-
-@code{int (*func)(int, int);}
-
-@noindent
-we may write
-
-@code{rl_command_func_t *func;}
-
-The full list of function pointer types available is
-
-@table @code
-@item typedef int rl_command_func_t (int, int);
-
-@item typedef char *rl_compentry_func_t (const char *, int);
-
-@item typedef char **rl_completion_func_t (const char *, int, int);
-
-@item typedef char *rl_quote_func_t (char *, int, char *);
-
-@item typedef char *rl_dequote_func_t (char *, int);
-
-@item typedef int rl_compignore_func_t (char **);
-
-@item typedef void rl_compdisp_func_t (char **, int, int);
-
-@item typedef int rl_hook_func_t (void);
-
-@item typedef int rl_getc_func_t (FILE *);
-
-@item typedef int rl_linebuf_func_t (char *, int);
-
-@item typedef int rl_intfunc_t (int);
-@item #define rl_ivoidfunc_t rl_hook_func_t
-@item typedef int rl_icpfunc_t (char *);
-@item typedef int rl_icppfunc_t (char **);
-
-@item typedef void rl_voidfunc_t (void);
-@item typedef void rl_vintfunc_t (int);
-@item typedef void rl_vcpfunc_t (char *);
-@item typedef void rl_vcppfunc_t (char **);
-
-@end table
-
-@node Function Writing
-@subsection Writing a New Function
-
-In order to write new functions for Readline, you need to know the
-calling conventions for keyboard-invoked functions, and the names of the
-variables that describe the current state of the line read so far.
-
-The calling sequence for a command @code{foo} looks like
-
-@example
-@code{int foo (int count, int key)}
-@end example
-
-@noindent
-where @var{count} is the numeric argument (or 1 if defaulted) and
-@var{key} is the key that invoked this function.
-
-It is completely up to the function as to what should be done with the
-numeric argument.  Some functions use it as a repeat count, some
-as a flag, and others to choose alternate behavior (refreshing the current
-line as opposed to refreshing the screen, for example).  Some choose to
-ignore it.  In general, if a
-function uses the numeric argument as a repeat count, it should be able
-to do something useful with both negative and positive arguments.
-At the very least, it should be aware that it can be passed a
-negative argument.
-
-A command function should return 0 if its action completes successfully,
-and a value greater than zero if some error occurs.
-This is the convention obeyed by all of the builtin Readline bindable
-command functions.
-
-@node Readline Variables
-@section Readline Variables
-
-These variables are available to function writers.
-
-@deftypevar {char *} rl_line_buffer
-This is the line gathered so far.  You are welcome to modify the
-contents of the line, but see @ref{Allowing Undoing}.  The
-function @code{rl_extend_line_buffer} is available to increase
-the memory allocated to @code{rl_line_buffer}.
-@end deftypevar
-
-@deftypevar int rl_point
-The offset of the current cursor position in @code{rl_line_buffer}
-(the @emph{point}).
-@end deftypevar
-
-@deftypevar int rl_end
-The number of characters present in @code{rl_line_buffer}.  When
-@code{rl_point} is at the end of the line, @code{rl_point} and
-@code{rl_end} are equal.
-@end deftypevar
-
-@deftypevar int rl_mark
-The @var{mark} (saved position) in the current line.  If set, the mark
-and point define a @emph{region}.
-@end deftypevar
-
-@deftypevar int rl_done
-Setting this to a non-zero value causes Readline to return the current
-line immediately.
-@end deftypevar
-
-@deftypevar int rl_num_chars_to_read
-Setting this to a positive value before calling @code{readline()} causes
-Readline to return after accepting that many characters, rather
-than reading up to a character bound to @code{accept-line}.
-@end deftypevar
-
-@deftypevar int rl_pending_input
-Setting this to a value makes it the next keystroke read.  This is a
-way to stuff a single character into the input stream.
-@end deftypevar
-
-@deftypevar int rl_dispatching
-Set to a non-zero value if a function is being called from a key binding;
-zero otherwise.  Application functions can test this to discover whether
-they were called directly or by Readline's dispatching mechanism.
-@end deftypevar
-
-@deftypevar int rl_erase_empty_line
-Setting this to a non-zero value causes Readline to completely erase
-the current line, including any prompt, any time a newline is typed as
-the only character on an otherwise-empty line.  The cursor is moved to
-the beginning of the newly-blank line.
-@end deftypevar
-
-@deftypevar {char *} rl_prompt
-The prompt Readline uses.  This is set from the argument to
-@code{readline()}, and should not be assigned to directly.
-The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
-be used to modify the prompt string after calling @code{readline()}.
-@end deftypevar
-
-@deftypevar {char *} rl_display_prompt
-The string displayed as the prompt.  This is usually identical to
-@var{rl_prompt}, but may be changed temporarily by functions that
-use the prompt string as a message area, such as incremental search.
-@end deftypevar
-
-@deftypevar int rl_already_prompted
-If an application wishes to display the prompt itself, rather than have
-Readline do it the first time @code{readline()} is called, it should set
-this variable to a non-zero value after displaying the prompt.
-The prompt must also be passed as the argument to @code{readline()} so
-the redisplay functions can update the display properly.
-The calling application is responsible for managing the value; Readline
-never sets it.
-@end deftypevar
-
-@deftypevar {const char *} rl_library_version
-The version number of this revision of the library.
-@end deftypevar
-
-@deftypevar int rl_readline_version
-An integer encoding the current version of the library.  The encoding is
-of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
-number, and @var{mm} is the two-digit minor version number.
-For example, for Readline-4.2, @code{rl_readline_version} would have the
-value 0x0402.
-@end deftypevar
-
-@deftypevar {int} rl_gnu_readline_p
-Always set to 1, denoting that this is @sc{gnu} readline rather than some
-emulation.
-@end deftypevar
-
-@deftypevar {const char *} rl_terminal_name
-The terminal type, used for initialization.  If not set by the application,
-Readline sets this to the value of the @env{TERM} environment variable
-the first time it is called.
-@end deftypevar
-
-@deftypevar {const char *} rl_readline_name
-This variable is set to a unique name by each application using Readline.
-The value allows conditional parsing of the inputrc file
-(@pxref{Conditional Init Constructs}).
-@end deftypevar
-
-@deftypevar {FILE *} rl_instream
-The stdio stream from which Readline reads input.
-If @code{NULL}, Readline defaults to @var{stdin}.
-@end deftypevar
-
-@deftypevar {FILE *} rl_outstream
-The stdio stream to which Readline performs output.
-If @code{NULL}, Readline defaults to @var{stdout}.
-@end deftypevar
-
-@deftypevar int rl_prefer_env_winsize
-If non-zero, Readline gives values found in the @env{LINES} and
-@env{COLUMNS} environment variables greater precedence than values fetched
-from the kernel when computing the screen dimensions.
-@end deftypevar
-
-@deftypevar {rl_command_func_t *} rl_last_func
-The address of the last command function Readline executed.  May be used to
-test whether or not a function is being executed twice in succession, for
-example.
-@end deftypevar
-
-@deftypevar {rl_hook_func_t *} rl_startup_hook
-If non-zero, this is the address of a function to call just
-before @code{readline} prints the first prompt.
-@end deftypevar
-
-@deftypevar {rl_hook_func_t *} rl_pre_input_hook
-If non-zero, this is the address of a function to call after
-the first prompt has been printed and just before @code{readline}
-starts reading input characters.
-@end deftypevar
-
-@deftypevar {rl_hook_func_t *} rl_event_hook
-If non-zero, this is the address of a function to call periodically
-when Readline is waiting for terminal input.
-By default, this will be called at most ten times a second if there
-is no keyboard input.
-@end deftypevar
-
-@deftypevar {rl_getc_func_t *} rl_getc_function
-If non-zero, Readline will call indirectly through this pointer
-to get a character from the input stream.  By default, it is set to
-@code{rl_getc}, the default Readline character input function
-(@pxref{Character Input}).
-In general, an application that sets @var{rl_getc_function} should consider
-setting @var{rl_input_available_hook} as well.
-@end deftypevar
-
-@deftypevar {rl_hook_func_t *} rl_signal_event_hook
-If non-zero, this is the address of a function to call if a read system
-call is interrupted when Readline is reading terminal input.
-@end deftypevar
-
-@deftypevar {rl_hook_func_t *} rl_input_available_hook
-If non-zero, Readline will use this function's return value when it needs
-to determine whether or not there is available input on the current input
-source.
-The default hook checks @code{rl_instream}; if an application is using a
-different input source, it should set the hook appropriately.
-Readline queries for available input when implementing intra-key-sequence
-timeouts during input and incremental searches.
-This may use an application-specific timeout before returning a value;
-Readline uses the value passed to @code{rl_set_keyboard_input_timeout()}
-or the value of the user-settable @var{keyseq-timeout} variable.
-This is designed for use by applications using Readline's callback interface
-(@pxref{Alternate Interface}), which may not use the traditional
-@code{read(2)} and file descriptor interface, or other applications using
-a different input mechanism.
-If an application uses an input mechanism or hook that can potentially exceed
-the value of @var{keyseq-timeout}, it should increase the timeout or set
-this hook appropriately even when not using the callback interface.
-In general, an application that sets @var{rl_getc_function} should consider
-setting @var{rl_input_available_hook} as well.
-@end deftypevar
-
-@deftypevar {rl_voidfunc_t *} rl_redisplay_function
-If non-zero, Readline will call indirectly through this pointer
-to update the display with the current contents of the editing buffer.
-By default, it is set to @code{rl_redisplay}, the default Readline
-redisplay function (@pxref{Redisplay}).
-@end deftypevar
-
-@deftypevar {rl_vintfunc_t *} rl_prep_term_function
-If non-zero, Readline will call indirectly through this pointer
-to initialize the terminal.  The function takes a single argument, an
-@code{int} flag that says whether or not to use eight-bit characters.
-By default, this is set to @code{rl_prep_terminal}
-(@pxref{Terminal Management}).
-@end deftypevar
-
-@deftypevar {rl_voidfunc_t *} rl_deprep_term_function
-If non-zero, Readline will call indirectly through this pointer
-to reset the terminal.  This function should undo the effects of
-@code{rl_prep_term_function}.
-By default, this is set to @code{rl_deprep_terminal}
-(@pxref{Terminal Management}).
-@end deftypevar
-
-@deftypevar {Keymap} rl_executing_keymap
-This variable is set to the keymap (@pxref{Keymaps}) in which the
-currently executing readline function was found.
-@end deftypevar 
-
-@deftypevar {Keymap} rl_binding_keymap
-This variable is set to the keymap (@pxref{Keymaps}) in which the
-last key binding occurred.
-@end deftypevar 
-
-@deftypevar {char *} rl_executing_macro
-This variable is set to the text of any currently-executing macro.
-@end deftypevar
-
-@deftypevar int rl_executing_key
-The key that caused the dispatch to the currently-executing Readline function.
-@end deftypevar
-
-@deftypevar {char *} rl_executing_keyseq
-The full key sequence that caused the dispatch to the currently-executing
-Readline function.
-@end deftypevar
-
-@deftypevar int rl_key_sequence_length
-The number of characters in @var{rl_executing_keyseq}.
-@end deftypevar
-
-@deftypevar {int} rl_readline_state
-A variable with bit values that encapsulate the current Readline state.
-A bit is set with the @code{RL_SETSTATE} macro, and unset with the
-@code{RL_UNSETSTATE} macro.  Use the @code{RL_ISSTATE} macro to test
-whether a particular state bit is set.  Current state bits include:
-
-@table @code
-@item RL_STATE_NONE
-Readline has not yet been called, nor has it begun to initialize.
-@item RL_STATE_INITIALIZING
-Readline is initializing its internal data structures.
-@item RL_STATE_INITIALIZED
-Readline has completed its initialization.
-@item RL_STATE_TERMPREPPED
-Readline has modified the terminal modes to do its own input and redisplay.
-@item RL_STATE_READCMD
-Readline is reading a command from the keyboard.
-@item RL_STATE_METANEXT
-Readline is reading more input after reading the meta-prefix character.
-@item RL_STATE_DISPATCHING
-Readline is dispatching to a command.
-@item RL_STATE_MOREINPUT
-Readline is reading more input while executing an editing command.
-@item RL_STATE_ISEARCH
-Readline is performing an incremental history search.
-@item RL_STATE_NSEARCH
-Readline is performing a non-incremental history search.
-@item RL_STATE_SEARCH
-Readline is searching backward or forward through the history for a string.
-@item RL_STATE_NUMERICARG
-Readline is reading a numeric argument.
-@item RL_STATE_MACROINPUT
-Readline is currently getting its input from a previously-defined keyboard
-macro.
-@item RL_STATE_MACRODEF
-Readline is currently reading characters defining a keyboard macro.
-@item RL_STATE_OVERWRITE
-Readline is in overwrite mode.
-@item RL_STATE_COMPLETING
-Readline is performing word completion.
-@item RL_STATE_SIGHANDLER
-Readline is currently executing the readline signal handler.
-@item RL_STATE_UNDOING
-Readline is performing an undo.
-@item RL_STATE_INPUTPENDING
-Readline has input pending due to a call to @code{rl_execute_next()}.
-@item RL_STATE_TTYCSAVED
-Readline has saved the values of the terminal's special characters.
-@item RL_STATE_CALLBACK
-Readline is currently using the alternate (callback) interface
-(@pxref{Alternate Interface}).
-@item RL_STATE_VIMOTION
-Readline is reading the argument to a vi-mode "motion" command.
-@item RL_STATE_MULTIKEY
-Readline is reading a multiple-keystroke command.
-@item RL_STATE_VICMDONCE
-Readline has entered vi command (movement) mode at least one time during
-the current call to @code{readline()}.
-@item RL_STATE_DONE
-Readline has read a key sequence bound to @code{accept-line}
-and is about to return the line to the caller.
-@end table
-
-@end deftypevar
-
-@deftypevar {int} rl_explicit_arg
-Set to a non-zero value if an explicit numeric argument was specified by
-the user.  Only valid in a bindable command function.
-@end deftypevar
-
-@deftypevar {int} rl_numeric_arg
-Set to the value of any numeric argument explicitly specified by the user
-before executing the current Readline function.  Only valid in a bindable
-command function.
-@end deftypevar
-
-@deftypevar {int} rl_editing_mode
-Set to a value denoting Readline's current editing mode.  A value of
-@var{1} means Readline is currently in emacs mode; @var{0}
-means that vi mode is active.
-@end deftypevar
-
-
-@node Readline Convenience Functions
-@section Readline Convenience Functions
-
-@menu
-* Function Naming::	How to give a function you write a name.
-* Keymaps::		Making keymaps.
-* Binding Keys::	Changing Keymaps.
-* Associating Function Names and Bindings::	Translate function names to
-						key sequences.
-* Allowing Undoing::	How to make your functions undoable.
-* Redisplay::		Functions to control line display.
-* Modifying Text::	Functions to modify @code{rl_line_buffer}.
-* Character Input::	Functions to read keyboard input.
-* Terminal Management::	Functions to manage terminal settings.
-* Utility Functions::	Generally useful functions and hooks.
-* Miscellaneous Functions::	Functions that don't fall into any category.
-* Alternate Interface::	Using Readline in a `callback' fashion.
-* A Readline Example::		An example Readline function.
-* Alternate Interface Example::	An example program using the alternate interface.
-@end menu
-
-@node Function Naming
-@subsection Naming a Function
-
-The user can dynamically change the bindings of keys while using
-Readline.  This is done by representing the function with a descriptive
-name.  The user is able to type the descriptive name when referring to
-the function.  Thus, in an init file, one might find
-
-@example
-Meta-Rubout:	backward-kill-word
-@end example
-
-This binds the keystroke @key{Meta-Rubout} to the function
-@emph{descriptively} named @code{backward-kill-word}.  You, as the
-programmer, should bind the functions you write to descriptive names as
-well.  Readline provides a function for doing that:
-
-@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
-Add @var{name} to the list of named functions.  Make @var{function} be
-the function that gets called.  If @var{key} is not -1, then bind it to
-@var{function} using @code{rl_bind_key()}.
-@end deftypefun
-
-Using this function alone is sufficient for most applications.
-It is the recommended way to add a few functions to the default
-functions that Readline has built in.
-If you need to do something other than adding a function to Readline,
-you may need to use the underlying functions described below.
-
-@node Keymaps
-@subsection Selecting a Keymap
-
-Key bindings take place on a @dfn{keymap}.  The keymap is the
-association between the keys that the user types and the functions that
-get run.  You can make your own keymaps, copy existing keymaps, and tell
-Readline which keymap to use.
-
-@deftypefun Keymap rl_make_bare_keymap (void)
-Returns a new, empty keymap.  The space for the keymap is allocated with
-@code{malloc()}; the caller should free it by calling
-@code{rl_free_keymap()} when done.
-@end deftypefun
-
-@deftypefun Keymap rl_copy_keymap (Keymap map)
-Return a new keymap which is a copy of @var{map}.
-@end deftypefun
-
-@deftypefun Keymap rl_make_keymap (void)
-Return a new keymap with the printing characters bound to rl_insert,
-the lowercase Meta characters bound to run their equivalents, and
-the Meta digits bound to produce numeric arguments.
-@end deftypefun
-
-@deftypefun void rl_discard_keymap (Keymap keymap)
-Free the storage associated with the data in @var{keymap}.
-The caller should free @var{keymap}.
-@end deftypefun
-
-@deftypefun void rl_free_keymap (Keymap keymap)
-Free all storage associated with @var{keymap}.  This calls
-@code{rl_discard_keymap} to free subordindate keymaps and macros.
-@end deftypefun
-
-@deftypefun int rl_empty_keymap (Keymap keymap)
-Return non-zero if there are no keys bound to functions in @var{keymap};
-zero if there are any keys bound.
-@end deftypefun
-
-Readline has several internal keymaps.  These functions allow you to
-change which keymap is active.
-
-@deftypefun Keymap rl_get_keymap (void)
-Returns the currently active keymap.
-@end deftypefun
-
-@deftypefun void rl_set_keymap (Keymap keymap)
-Makes @var{keymap} the currently active keymap.
-@end deftypefun
-
-@deftypefun Keymap rl_get_keymap_by_name (const char *name)
-Return the keymap matching @var{name}.  @var{name} is one which would
-be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
-@end deftypefun
-
-@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
-Return the name matching @var{keymap}.  @var{name} is one which would
-be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
-@end deftypefun
-
-@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap)
-Set the name of @var{keymap}.  This name will then be "registered" and
-available for use in a @code{set keymap} inputrc directive
-@pxref{Readline Init File}).
-The @var{name} may not be one of Readline's builtin keymap names;
-you may not add a different name for one of Readline's builtin keymaps.
-You may replace the name associated with a given keymap by calling this
-function more than once with the same @var{keymap} argument.
-You may associate a registered @var{name} with a new keymap by calling this
-function more than once  with the same @var{name} argument.
-There is no way to remove a named keymap once the name has been
-registered.
-Readline will make a copy of @var{name}.
-The return value is greater than zero unless @var{name} is one of
-Readline's builtin keymap names or @var{keymap} is one of Readline's
-builtin keymaps.
-@end deftypefun
-
-@node Binding Keys
-@subsection Binding Keys
-
-Key sequences are associate with functions through the keymap.
-Readline has several internal keymaps: @code{emacs_standard_keymap},
-@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
-@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
-@code{emacs_standard_keymap} is the default, and the examples in
-this manual assume that.
-
-Since @code{readline()} installs a set of default key bindings the first
-time it is called, there is always the danger that a custom binding
-installed before the first call to @code{readline()} will be overridden.
-An alternate mechanism is to install custom key bindings in an
-initialization function assigned to the @code{rl_startup_hook} variable
-(@pxref{Readline Variables}).
-
-These functions manage key bindings.
-
-@deftypefun int rl_bind_key (int key, rl_command_func_t *function)
-Binds @var{key} to @var{function} in the currently active keymap.
-Returns non-zero in the case of an invalid @var{key}.
-@end deftypefun
-
-@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
-Bind @var{key} to @var{function} in @var{map}.
-Returns non-zero in the case of an invalid @var{key}.
-@end deftypefun
-
-@deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function)
-Binds @var{key} to @var{function} if it is not already bound in the
-currently active keymap.
-Returns non-zero in the case of an invalid @var{key} or if @var{key} is
-already bound.
-@end deftypefun
-
-@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
-Binds @var{key} to @var{function} if it is not already bound in @var{map}.
-Returns non-zero in the case of an invalid @var{key} or if @var{key} is
-already bound.
-@end deftypefun
-
-@deftypefun int rl_unbind_key (int key)
-Bind @var{key} to the null function in the currently active keymap.
-Returns non-zero in case of error.
-@end deftypefun
-
-@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
-Bind @var{key} to the null function in @var{map}.
-Returns non-zero in case of error.
-@end deftypefun
-
-@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
-Unbind all keys that execute @var{function} in @var{map}.
-@end deftypefun
-
-@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
-Unbind all keys that are bound to @var{command} in @var{map}.
-@end deftypefun
-
-@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
-Bind the key sequence represented by the string @var{keyseq} to the function
-@var{function}, beginning in the current keymap.
-This makes new keymaps as necessary.
-The return value is non-zero if @var{keyseq} is invalid.
-@end deftypefun
-
-@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
-Bind the key sequence represented by the string @var{keyseq} to the function
-@var{function}.  This makes new keymaps as necessary.
-Initial bindings are performed in @var{map}.
-The return value is non-zero if @var{keyseq} is invalid.
-@end deftypefun
-
-@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
-Equivalent to @code{rl_bind_keyseq_in_map}.
-@end deftypefun
-
-@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
-Binds @var{keyseq} to @var{function} if it is not already bound in the
-currently active keymap.
-Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
-already bound.
-@end deftypefun
-
-@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
-Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
-Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
-already bound.
-@end deftypefun
-
-@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
-Bind the key sequence represented by the string @var{keyseq} to the arbitrary
-pointer @var{data}.  @var{type} says what kind of data is pointed to by
-@var{data}; this can be a function (@code{ISFUNC}), a macro
-(@code{ISMACR}), or a keymap (@code{ISKMAP}).  This makes new keymaps as
-necessary.  The initial keymap in which to do bindings is @var{map}.
-@end deftypefun
-
-@deftypefun int rl_parse_and_bind (char *line)
-Parse @var{line} as if it had been read from the @code{inputrc} file and
-perform any key bindings and variable assignments found
-(@pxref{Readline Init File}).
-@end deftypefun
-
-@deftypefun int rl_read_init_file (const char *filename)
-Read keybindings and variable assignments from @var{filename}
-(@pxref{Readline Init File}).
-@end deftypefun
-
-@node Associating Function Names and Bindings
-@subsection Associating Function Names and Bindings
-
-These functions allow you to find out what keys invoke named functions
-and the functions invoked by a particular key sequence.  You may also
-associate a new function name with an arbitrary function.
-
-@deftypefun {rl_command_func_t *} rl_named_function (const char *name)
-Return the function with name @var{name}.
-@end deftypefun
-
-@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
-Return the function invoked by @var{keyseq} in keymap @var{map}.
-If @var{map} is @code{NULL}, the current keymap is used.  If @var{type} is
-not @code{NULL}, the type of the object is returned in the @code{int} variable
-it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
-It takes a "translated" key sequence and should not be used if the key sequence
-can include NUL.
-@end deftypefun
-
-@deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type)
-Return the function invoked by @var{keyseq} of length @var{len}
-in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the
-addition of the @var{len} parameter.
-It takes a "translated" key sequence and should be used if the key sequence
-can include NUL.
-@end deftypefun
-
-@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
-Return an array of strings representing the key sequences used to
-invoke @var{function} in the current keymap.
-@end deftypefun
-
-@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
-Return an array of strings representing the key sequences used to
-invoke @var{function} in the keymap @var{map}.
-@end deftypefun
-
-@deftypefun void rl_function_dumper (int readable)
-Print the readline function names and the key sequences currently
-bound to them to @code{rl_outstream}.  If @var{readable} is non-zero,
-the list is formatted in such a way that it can be made part of an
-@code{inputrc} file and re-read.
-@end deftypefun
-
-@deftypefun void rl_list_funmap_names (void)
-Print the names of all bindable Readline functions to @code{rl_outstream}.
-@end deftypefun
-
-@deftypefun {const char **} rl_funmap_names (void)
-Return a NULL terminated array of known function names.  The array is
-sorted.  The array itself is allocated, but not the strings inside.  You
-should free the array, but not the pointers, using @code{free} or
-@code{rl_free} when you are done.
-@end deftypefun
-
-@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
-Add @var{name} to the list of bindable Readline command names, and make
-@var{function} the function to be called when @var{name} is invoked.
-@end deftypefun
-
-@node Allowing Undoing
-@subsection Allowing Undoing
-
-Supporting the undo command is a painless thing, and makes your
-functions much more useful.  It is certainly easy to try
-something if you know you can undo it.
-
-If your function simply inserts text once, or deletes text once, and
-uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
-undoing is already done for you automatically.
-
-If you do multiple insertions or multiple deletions, or any combination
-of these operations, you should group them together into one operation.
-This is done with @code{rl_begin_undo_group()} and
-@code{rl_end_undo_group()}.
-
-The types of events that can be undone are:
-
-@smallexample
-enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @}; 
-@end smallexample
-
-Notice that @code{UNDO_DELETE} means to insert some text, and
-@code{UNDO_INSERT} means to delete some text.  That is, the undo code
-tells what to undo, not how to undo it.  @code{UNDO_BEGIN} and
-@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
-@code{rl_end_undo_group()}.
-
-@deftypefun int rl_begin_undo_group (void)
-Begins saving undo information in a group construct.  The undo
-information usually comes from calls to @code{rl_insert_text()} and
-@code{rl_delete_text()}, but could be the result of calls to
-@code{rl_add_undo()}.
-@end deftypefun
-
-@deftypefun int rl_end_undo_group (void)
-Closes the current undo group started with @code{rl_begin_undo_group
-()}.  There should be one call to @code{rl_end_undo_group()}
-for each call to @code{rl_begin_undo_group()}.
-@end deftypefun
-
-@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
-Remember how to undo an event (according to @var{what}).  The affected
-text runs from @var{start} to @var{end}, and encompasses @var{text}.
-@end deftypefun
-
-@deftypefun void rl_free_undo_list (void)
-Free the existing undo list.
-@end deftypefun
-
-@deftypefun int rl_do_undo (void)
-Undo the first thing on the undo list.  Returns @code{0} if there was
-nothing to undo, non-zero if something was undone.
-@end deftypefun
-
-Finally, if you neither insert nor delete text, but directly modify the
-existing text (e.g., change its case), call @code{rl_modifying()}
-once, just before you modify the text.  You must supply the indices of
-the text range that you are going to modify.
-
-@deftypefun int rl_modifying (int start, int end)
-Tell Readline to save the text between @var{start} and @var{end} as a
-single undo unit.  It is assumed that you will subsequently modify
-that text.
-@end deftypefun
-
-@node Redisplay
-@subsection Redisplay
-
-@deftypefun void rl_redisplay (void)
-Change what's displayed on the screen to reflect the current contents
-of @code{rl_line_buffer}.
-@end deftypefun
-
-@deftypefun int rl_forced_update_display (void)
-Force the line to be updated and redisplayed, whether or not
-Readline thinks the screen display is correct.
-@end deftypefun
-
-@deftypefun int rl_on_new_line (void)
-Tell the update functions that we have moved onto a new (empty) line,
-usually after outputting a newline.
-@end deftypefun
-
-@deftypefun int rl_on_new_line_with_prompt (void)
-Tell the update functions that we have moved onto a new line, with
-@var{rl_prompt} already displayed.
-This could be used by applications that want to output the prompt string
-themselves, but still need Readline to know the prompt string length for
-redisplay.
-It should be used after setting @var{rl_already_prompted}.
-@end deftypefun
-
-@deftypefun int rl_clear_visible_line (void)
-Clear the screen lines corresponding to the current line's contents.
-@end deftypefun
-
-@deftypefun int rl_reset_line_state (void)
-Reset the display state to a clean state and redisplay the current line
-starting on a new line.
-@end deftypefun
-
-@deftypefun int rl_crlf (void)
-Move the cursor to the start of the next screen line.
-@end deftypefun
-
-@deftypefun int rl_show_char (int c)
-Display character @var{c} on @code{rl_outstream}.
-If Readline has not been set to display meta characters directly, this
-will convert meta characters to a meta-prefixed key sequence.
-This is intended for use by applications which wish to do their own
-redisplay.
-@end deftypefun
-
-@deftypefun int rl_message (const char *, @dots{})
-The arguments are a format string as would be supplied to @code{printf},
-possibly containing conversion specifications such as @samp{%d}, and
-any additional arguments necessary to satisfy the conversion specifications.
-The resulting string is displayed in the @dfn{echo area}.  The echo area
-is also used to display numeric arguments and search strings.
-You should call @code{rl_save_prompt} to save the prompt information
-before calling this function.
-@end deftypefun
-
-@deftypefun int rl_clear_message (void)
-Clear the message in the echo area.  If the prompt was saved with a call to
-@code{rl_save_prompt} before the last call to @code{rl_message},
-call @code{rl_restore_prompt} before calling this function.
-@end deftypefun
-
-@deftypefun void rl_save_prompt (void)
-Save the local Readline prompt display state in preparation for
-displaying a new message in the message area with @code{rl_message()}.
-@end deftypefun
-
-@deftypefun void rl_restore_prompt (void)
-Restore the local Readline prompt display state saved by the most
-recent call to @code{rl_save_prompt}.
-if @code{rl_save_prompt} was called to save the prompt before a call
-to @code{rl_message}, this function should be called before the
-corresponding call to @code{rl_clear_message}.
-@end deftypefun
-
-@deftypefun int rl_expand_prompt (char *prompt)
-Expand any special character sequences in @var{prompt} and set up the
-local Readline prompt redisplay variables.
-This function is called by @code{readline()}.  It may also be called to
-expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
-function or @code{rl_already_prompted} variable is used.
-It returns the number of visible characters on the last line of the
-(possibly multi-line) prompt.
-Applications may indicate that the prompt contains characters that take
-up no physical screen space when displayed by bracketing a sequence of
-such characters with the special markers @code{RL_PROMPT_START_IGNORE}
-and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}).  This may
-be used to embed terminal-specific escape sequences in prompts.
-@end deftypefun
-
-@deftypefun int rl_set_prompt (const char *prompt)
-Make Readline use @var{prompt} for subsequent redisplay.  This calls
-@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
-to the result.
-@end deftypefun
-
-@node Modifying Text
-@subsection Modifying Text
-
-@deftypefun int rl_insert_text (const char *text)
-Insert @var{text} into the line at the current cursor position.
-Returns the number of characters inserted.
-@end deftypefun
-
-@deftypefun int rl_delete_text (int start, int end)
-Delete the text between @var{start} and @var{end} in the current line.
-Returns the number of characters deleted.
-@end deftypefun
-
-@deftypefun {char *} rl_copy_text (int start, int end)
-Return a copy of the text between @var{start} and @var{end} in
-the current line.
-@end deftypefun
-
-@deftypefun int rl_kill_text (int start, int end)
-Copy the text between @var{start} and @var{end} in the current line
-to the kill ring, appending or prepending to the last kill if the
-last command was a kill command.  The text is deleted.
-If @var{start} is less than @var{end},
-the text is appended, otherwise prepended.  If the last command was
-not a kill, a new kill ring slot is used.
-@end deftypefun
-
-@deftypefun int rl_push_macro_input (char *macro)
-Cause @var{macro} to be inserted into the line, as if it had been invoked
-by a key bound to a macro.  Not especially useful; use
-@code{rl_insert_text()} instead.
-@end deftypefun
-
-@node Character Input
-@subsection Character Input
-
-@deftypefun int rl_read_key (void)
-Return the next character available from Readline's current input stream.
-This handles input inserted into
-the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
-and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
-While waiting for input, this function will call any function assigned to
-the @code{rl_event_hook} variable.
-@end deftypefun
-
-@deftypefun int rl_getc (FILE *stream)
-Return the next character available from @var{stream}, which is assumed to
-be the keyboard.
-@end deftypefun
-
-@deftypefun int rl_stuff_char (int c)
-Insert @var{c} into the Readline input stream.  It will be "read"
-before Readline attempts to read characters from the terminal with
-@code{rl_read_key()}.  Up to 512 characters may be pushed back.
-@code{rl_stuff_char} returns 1 if the character was successfully inserted;
-0 otherwise.
-@end deftypefun
-
-@deftypefun int rl_execute_next (int c)
-Make @var{c} be the next command to be executed when @code{rl_read_key()}
-is called.  This sets @var{rl_pending_input}.
-@end deftypefun
-
-@deftypefun int rl_clear_pending_input (void)
-Unset @var{rl_pending_input}, effectively negating the effect of any
-previous call to @code{rl_execute_next()}.  This works only if the
-pending input has not already been read with @code{rl_read_key()}.
-@end deftypefun
-
-@deftypefun int rl_set_keyboard_input_timeout (int u)
-While waiting for keyboard input in @code{rl_read_key()}, Readline will
-wait for @var{u} microseconds for input before calling any function
-assigned to @code{rl_event_hook}.  @var{u} must be greater than or equal
-to zero (a zero-length timeout is equivalent to a poll).
-The default waiting period is one-tenth of a second.
-Returns the old timeout value.
-@end deftypefun
-
-@node Terminal Management
-@subsection Terminal Management
-
-@deftypefun void rl_prep_terminal (int meta_flag)
-Modify the terminal settings for Readline's use, so @code{readline()}
-can read a single character at a time from the keyboard.
-The @var{meta_flag} argument should be non-zero if Readline should
-read eight-bit input.
-@end deftypefun
-
-@deftypefun void rl_deprep_terminal (void)
-Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
-the state in which it was before the most recent call to
-@code{rl_prep_terminal()}.
-@end deftypefun
-
-@deftypefun void rl_tty_set_default_bindings (Keymap kmap)
-Read the operating system's terminal editing characters (as would be
-displayed by @code{stty}) to their Readline equivalents.
-The bindings are performed in @var{kmap}.
-@end deftypefun
-
-@deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
-Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
-that the terminal editing characters are bound to @code{rl_insert}.
-The bindings are performed in @var{kmap}.
-@end deftypefun
-
-@deftypefun int rl_tty_set_echoing (int value)
-Set Readline's idea of whether or not it is echoing output to its output
-stream (@var{rl_outstream}).  If @var{value} is 0, Readline does not display
-output to @var{rl_outstream}; any other value enables output.  The initial
-value is set when Readline initializes the terminal settings.
-This function returns the previous value.
-@end deftypefun
-
-@deftypefun int rl_reset_terminal (const char *terminal_name)
-Reinitialize Readline's idea of the terminal settings using
-@var{terminal_name} as the terminal type (e.g., @code{vt100}).
-If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
-environment variable is used.
-@end deftypefun
-
-@node Utility Functions
-@subsection Utility Functions
-
-@deftypefun int rl_save_state (struct readline_state *sp)
-Save a snapshot of Readline's internal state to @var{sp}.
-The contents of the @var{readline_state} structure are documented
-in @file{readline.h}.
-The caller is responsible for allocating the structure.
-@end deftypefun
-
-@deftypefun int rl_restore_state (struct readline_state *sp)
-Restore Readline's internal state to that stored in @var{sp}, which must
-have been saved by a call to @code{rl_save_state}.
-The contents of the @var{readline_state} structure are documented
-in @file{readline.h}.
-The caller is responsible for freeing the structure.
-@end deftypefun
-
-@deftypefun void rl_free (void *mem)
-Deallocate the memory pointed to by @var{mem}.  @var{mem} must have been
-allocated by @code{malloc}.
-@end deftypefun
-
-@deftypefun void rl_replace_line (const char *text, int clear_undo)
-Replace the contents of @code{rl_line_buffer} with @var{text}.
-The point and mark are preserved, if possible.
-If @var{clear_undo} is non-zero, the undo list associated with the
-current line is cleared.
-@end deftypefun
-
-@deftypefun void rl_extend_line_buffer (int len)
-Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
-characters, possibly reallocating it if necessary.
-@end deftypefun
-
-@deftypefun int rl_initialize (void)
-Initialize or re-initialize Readline's internal state.
-It's not strictly necessary to call this; @code{readline()} calls it before
-reading any input.
-@end deftypefun
-
-@deftypefun int rl_ding (void)
-Ring the terminal bell, obeying the setting of @code{bell-style}.
-@end deftypefun
-
-@deftypefun int rl_alphabetic (int c)
-Return 1 if @var{c} is an alphabetic character.
-@end deftypefun
-
-@deftypefun void rl_display_match_list (char **matches, int len, int max)
-A convenience function for displaying a list of strings in
-columnar format on Readline's output stream.  @code{matches} is the list
-of strings, in argv format, such as a list of completion matches.
-@code{len} is the number of strings in @code{matches}, and @code{max}
-is the length of the longest string in @code{matches}.  This function uses
-the setting of @code{print-completions-horizontally} to select how the
-matches are displayed (@pxref{Readline Init File Syntax}).
-When displaying completions, this function sets the number of columns used
-for display to the value of @code{completion-display-width}, the value of
-the environment variable @env{COLUMNS}, or the screen width, in that order.
-@end deftypefun
-
-The following are implemented as macros, defined in @code{chardefs.h}.
-Applications should refrain from using them.
-
-@deftypefun int _rl_uppercase_p (int c)
-Return 1 if @var{c} is an uppercase alphabetic character.
-@end deftypefun
-
-@deftypefun int _rl_lowercase_p (int c)
-Return 1 if @var{c} is a lowercase alphabetic character.
-@end deftypefun
-
-@deftypefun int _rl_digit_p (int c)
-Return 1 if @var{c} is a numeric character.
-@end deftypefun
-
-@deftypefun int _rl_to_upper (int c)
-If @var{c} is a lowercase alphabetic character, return the corresponding
-uppercase character.
-@end deftypefun
-
-@deftypefun int _rl_to_lower (int c)
-If @var{c} is an uppercase alphabetic character, return the corresponding
-lowercase character.
-@end deftypefun
-
-@deftypefun int _rl_digit_value (int c)
-If @var{c} is a number, return the value it represents.
-@end deftypefun
-
-@node Miscellaneous Functions
-@subsection Miscellaneous Functions
-
-@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
-Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
-The binding is performed in @var{map}.  When @var{keyseq} is invoked, the
-@var{macro} will be inserted into the line.  This function is deprecated;
-use @code{rl_generic_bind()} instead.
-@end deftypefun
-
-@deftypefun void rl_macro_dumper (int readable)
-Print the key sequences bound to macros and their values, using
-the current keymap, to @code{rl_outstream}.
-If @var{readable} is non-zero, the list is formatted in such a way
-that it can be made part of an @code{inputrc} file and re-read.
-@end deftypefun
-
-@deftypefun int rl_variable_bind (const char *variable, const char *value)
-Make the Readline variable @var{variable} have @var{value}.
-This behaves as if the readline command
-@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
-file (@pxref{Readline Init File Syntax}).
-@end deftypefun
-
-@deftypefun {char *} rl_variable_value (const char *variable)
-Return a string representing the value of the Readline variable @var{variable}.
-For boolean variables, this string is either @samp{on} or @samp{off}.
-@end deftypefun
-
-@deftypefun void rl_variable_dumper (int readable)
-Print the readline variable names and their current values
-to @code{rl_outstream}.
-If @var{readable} is non-zero, the list is formatted in such a way
-that it can be made part of an @code{inputrc} file and re-read.
-@end deftypefun
-
-@deftypefun int rl_set_paren_blink_timeout (int u)
-Set the time interval (in microseconds) that Readline waits when showing
-a balancing character when @code{blink-matching-paren} has been enabled.
-@end deftypefun
-
-@deftypefun {char *} rl_get_termcap (const char *cap)
-Retrieve the string value of the termcap capability @var{cap}.
-Readline fetches the termcap entry for the current terminal name and
-uses those capabilities to move around the screen line and perform other
-terminal-specific operations, like erasing a line.  Readline does not
-use all of a terminal's capabilities, and this function will return
-values for only those capabilities Readline uses.
-@end deftypefun
-
-@deftypefun {void} rl_clear_history (void)
-Clear the history list by deleting all of the entries, in the same manner
-as the History library's @code{clear_history()} function.
-This differs from @code{clear_history} because it frees private data
-Readline saves in the history list.
-@end deftypefun
-
-@node Alternate Interface
-@subsection Alternate Interface
-
-An alternate interface is available to plain @code{readline()}.  Some
-applications need to interleave keyboard I/O with file, device, or
-window system I/O, typically by using a main loop to @code{select()}
-on various file descriptors.  To accommodate this need, readline can
-also be invoked as a `callback' function from an event loop.  There
-are functions available to make this easy.
-
-@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
-Set up the terminal for readline I/O and display the initial
-expanded value of @var{prompt}.  Save the value of @var{lhandler} to
-use as a handler function to call when a complete line of input has been
-entered.
-The handler function receives the text of the line as an argument.
-As with @code{readline()}, the handler function should @code{free} the
-line when it it finished with it.
-@end deftypefun
-
-@deftypefun void rl_callback_read_char (void)
-Whenever an application determines that keyboard input is available, it
-should call @code{rl_callback_read_char()}, which will read the next
-character from the current input source.
-If that character completes the line, @code{rl_callback_read_char} will
-invoke the @var{lhandler} function installed by
-@code{rl_callback_handler_install} to process the line.
-Before calling the @var{lhandler} function, the terminal settings are
-reset to the values they had before calling
-@code{rl_callback_handler_install}.
-If the @var{lhandler} function returns,
-and the line handler remains installed,
-the terminal settings are modified for Readline's use again.
-@code{EOF} is indicated by calling @var{lhandler} with a
-@code{NULL} line.
-@end deftypefun
-
-@deftypefun void rl_callback_sigcleanup (void)
-Clean up any internal state the callback interface uses to maintain state
-between calls to rl_callback_read_char (e.g., the state of any active
-incremental searches).  This is intended to be used by applications that
-wish to perform their own signal handling; Readline's internal signal handler
-calls this when appropriate.
-@end deftypefun
-
-@deftypefun void rl_callback_handler_remove (void)
-Restore the terminal to its initial state and remove the line handler.
-You may call this function from within a callback as well as independently.
-If the @var{lhandler} installed by @code{rl_callback_handler_install}
-does not exit the program, either this function or the function referred
-to by the value of @code{rl_deprep_term_function} should be called before
-the program exits to reset the terminal settings.
-@end deftypefun
-
-@node A Readline Example
-@subsection A Readline Example
-
-Here is a function which changes lowercase characters to their uppercase
-equivalents, and uppercase characters to lowercase.  If
-this function was bound to @samp{M-c}, then typing @samp{M-c} would
-change the case of the character under point.  Typing @samp{M-1 0 M-c}
-would change the case of the following 10 characters, leaving the cursor on
-the last character changed.
-
-@example
-/* Invert the case of the COUNT following characters. */
-int
-invert_case_line (count, key)
-     int count, key;
-@{
-  register int start, end, i;
-
-  start = rl_point;
-
-  if (rl_point >= rl_end)
-    return (0);
-
-  if (count < 0)
-    @{
-      direction = -1;
-      count = -count;
-    @}
-  else
-    direction = 1;
-      
-  /* Find the end of the range to modify. */
-  end = start + (count * direction);
-
-  /* Force it to be within range. */
-  if (end > rl_end)
-    end = rl_end;
-  else if (end < 0)
-    end = 0;
-
-  if (start == end)
-    return (0);
-
-  if (start > end)
-    @{
-      int temp = start;
-      start = end;
-      end = temp;
-    @}
-
-  /* Tell readline that we are modifying the line,
-     so it will save the undo information. */
-  rl_modifying (start, end);
-
-  for (i = start; i != end; i++)
-    @{
-      if (_rl_uppercase_p (rl_line_buffer[i]))
-        rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
-      else if (_rl_lowercase_p (rl_line_buffer[i]))
-        rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
-    @}
-  /* Move point to on top of the last character changed. */
-  rl_point = (direction == 1) ? end - 1 : start;
-  return (0);
-@}
-@end example
-
-@node Alternate Interface Example
-@subsection Alternate Interface Example
-
-Here is a complete program that illustrates Readline's alternate interface.
-It reads lines from the terminal and displays them, providing the
-standard history and TAB completion functions.
-It understands the EOF character or "exit" to exit the program.
-
-@example
-/* Standard include files. stdio.h is required. */
-#include <stdlib.h>
-#include <string.h>
-#include <unistd.h>
-#include <locale.h>
-
-/* Used for select(2) */
-#include <sys/types.h>
-#include <sys/select.h>
-
-#include <signal.h>
-
-#include <stdio.h>
-
-/* Standard readline include files. */
-#include <readline/readline.h>
-#include <readline/history.h>
-
-static void cb_linehandler (char *);
-static void sighandler (int);
-
-int running;
-int sigwinch_received;
-const char *prompt = "rltest$ ";
-
-/* Handle SIGWINCH and window size changes when readline is not active and
-   reading a character. */
-static void
-sighandler (int sig)
-@{
-  sigwinch_received = 1;
-@}
-
-/* Callback function called for each line when accept-line executed, EOF
-   seen, or EOF character read.  This sets a flag and returns; it could
-   also call exit(3). */
-static void
-cb_linehandler (char *line)
-@{
-  /* Can use ^D (stty eof) or `exit' to exit. */
-  if (line == NULL || strcmp (line, "exit") == 0)
-    @{
-      if (line == 0)
-        printf ("\n");
-      printf ("exit\n");
-      /* This function needs to be called to reset the terminal settings,
-         and calling it from the line handler keeps one extra prompt from
-         being displayed. */
-      rl_callback_handler_remove ();
-
-      running = 0;
-    @}
-  else
-    @{
-      if (*line)
-        add_history (line);
-      printf ("input line: %s\n", line);
-      free (line);
-    @}
-@}
-
-int
-main (int c, char **v)
-@{
-  fd_set fds;
-  int r;
-
-  /* Set the default locale values according to environment variables. */
-  setlocale (LC_ALL, "");
-
-  /* Handle window size changes when readline is not active and reading
-     characters. */
-  signal (SIGWINCH, sighandler);
-
-  /* Install the line handler. */
-  rl_callback_handler_install (prompt, cb_linehandler);
-
-  /* Enter a simple event loop.  This waits until something is available
-     to read on readline's input stream (defaults to standard input) and
-     calls the builtin character read callback to read it.  It does not
-     have to modify the user's terminal settings. */
-  running = 1;
-  while (running)
-    @{
-      FD_ZERO (&fds);
-      FD_SET (fileno (rl_instream), &fds);    
-
-      r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
-      if (r < 0 && errno != EINTR)
-        @{
-          perror ("rltest: select");
-          rl_callback_handler_remove ();
-          break;
-        @}
-      if (sigwinch_received)
-	@{
-	  rl_resize_terminal ();
-	  sigwinch_received = 0;
-	@}
-      if (r < 0)
-	continue;     
-
-      if (FD_ISSET (fileno (rl_instream), &fds))
-        rl_callback_read_char ();
-    @}
-
-  printf ("rltest: Event loop has exited\n");
-  return 0;
-@}
-@end example
-
-@node Readline Signal Handling
-@section Readline Signal Handling
-
-Signals are asynchronous events sent to a process by the Unix kernel,
-sometimes on behalf of another process.  They are intended to indicate
-exceptional events, like a user pressing the interrupt key on his terminal,
-or a network connection being broken.  There is a class of signals that can
-be sent to the process currently reading input from the keyboard.  Since
-Readline changes the terminal attributes when it is called, it needs to
-perform special processing when such a signal is received in order to
-restore the terminal to a sane state, or provide application writers with
-functions to do so manually. 
-
-Readline contains an internal signal handler that is installed for a
-number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
-@code{SIGHUP}, 
-@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
-When one of these signals is received, the signal handler
-will reset the terminal attributes to those that were in effect before
-@code{readline()} was called, reset the signal handling to what it was
-before @code{readline()} was called, and resend the signal to the calling
-application.
-If and when the calling application's signal handler returns, Readline
-will reinitialize the terminal and continue to accept input.
-When a @code{SIGINT} is received, the Readline signal handler performs
-some additional work, which will cause any partially-entered line to be
-aborted (see the description of @code{rl_free_line_state()} below).
-
-There is an additional Readline signal handler, for @code{SIGWINCH}, which
-the kernel sends to a process whenever the terminal's size changes (for
-example, if a user resizes an @code{xterm}).  The Readline @code{SIGWINCH}
-handler updates Readline's internal screen size information, and then calls
-any @code{SIGWINCH} signal handler the calling application has installed. 
-Readline calls the application's @code{SIGWINCH} signal handler without
-resetting the terminal to its original state.  If the application's signal
-handler does more than update its idea of the terminal size and return (for
-example, a @code{longjmp} back to a main processing loop), it @emph{must}
-call @code{rl_cleanup_after_signal()} (described below), to restore the
-terminal state.
-
-When an application is using the callback interface
-(@pxref{Alternate Interface}), Readline installs signal handlers only for
-the duration of the call to @code{rl_callback_read_char}.  Applications
-using the callback interface should be prepared to clean up Readline's
-state if they wish to handle the signal before the line handler completes
-and restores the terminal state.
-
-If an application using the callback interface wishes to have Readline
-install its signal handlers at the time the application calls
-@code{rl_callback_handler_install} and remove them only when a complete
-line of input has been read, it should set the
-@code{rl_persistent_signal_handlers} variable to a non-zero value.
-This allows an application to defer all of the handling of the signals
-Readline catches to Readline.
-Applications should use this variable with care; it can result in Readline
-catching signals and not acting on them (or allowing the application to react
-to them) until the application calls @code{rl_callback_read_char}.  This
-can result in an application becoming less responsive to keyboard signals
-like SIGINT.
-If an application does not want or need to perform any signal handling, or
-does not need to do any processing between calls to @code{rl_callback_read_char},
-setting this variable may be desirable.
-
-Readline provides two variables that allow application writers to
-control whether or not it will catch certain signals and act on them
-when they are received.  It is important that applications change the
-values of these variables only when calling @code{readline()}, not in
-a signal handler, so Readline's internal signal state is not corrupted.
-
-@deftypevar int rl_catch_signals
-If this variable is non-zero, Readline will install signal handlers for
-@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
-@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
-
-The default value of @code{rl_catch_signals} is 1.
-@end deftypevar
-
-@deftypevar int rl_catch_sigwinch
-If this variable is set to a non-zero value,
-Readline will install a signal handler for @code{SIGWINCH}.
-
-The default value of @code{rl_catch_sigwinch} is 1.
-@end deftypevar
-
-@deftypevar int rl_persistent_signal_handlers
-If an application using the callback interface wishes Readline's signal
-handlers to be installed and active during the set of calls to
-@code{rl_callback_read_char} that constitutes an entire single line,
-it should set this variable to a non-zero value.
-
-The default value of @code{rl_persistent_signal_handlers} is 0.
-@end deftypevar
-
-@deftypevar int rl_change_environment
-If this variable is set to a non-zero value,
-and Readline is handling @code{SIGWINCH}, Readline will modify the
-@var{LINES} and @var{COLUMNS} environment variables upon receipt of a
-@code{SIGWINCH}
-
-The default value of @code{rl_change_environment} is 1.
-@end deftypevar
-
-If an application does not wish to have Readline catch any signals, or
-to handle signals other than those Readline catches (@code{SIGHUP},
-for example), 
-Readline provides convenience functions to do the necessary terminal
-and internal state cleanup upon receipt of a signal.
-
-@deftypefun int rl_pending_signal (void)
-Return the signal number of the most recent signal Readline received but
-has not yet handled, or 0 if there is no pending signal.
-@end deftypefun
-
-@deftypefun void rl_cleanup_after_signal (void)
-This function will reset the state of the terminal to what it was before
-@code{readline()} was called, and remove the Readline signal handlers for
-all signals, depending on the values of @code{rl_catch_signals} and
-@code{rl_catch_sigwinch}.
-@end deftypefun
-
-@deftypefun void rl_free_line_state (void)
-This will free any partial state associated with the current input line
-(undo information, any partial history entry, any partially-entered
-keyboard macro, and any partially-entered numeric argument).  This
-should be called before @code{rl_cleanup_after_signal()}.  The
-Readline signal handler for @code{SIGINT} calls this to abort the
-current input line.
-@end deftypefun
-
-@deftypefun void rl_reset_after_signal (void)
-This will reinitialize the terminal and reinstall any Readline signal
-handlers, depending on the values of @code{rl_catch_signals} and
-@code{rl_catch_sigwinch}.
-@end deftypefun
-
-If an application wants to force Readline to handle any signals that
-have arrived while it has been executing, @code{rl_check_signals()}
-will call Readline's internal signal handler if there are any pending
-signals.  This is primarily intended for those applications that use
-a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish
-to handle signals received while waiting for input.
-
-@deftypefun void rl_check_signals (void)
-If there are any pending signals, call Readline's internal signal handling
-functions to process them. @code{rl_pending_signal()} can be used independently
-to determine whether or not there are any pending signals.
-@end deftypefun
-
-If an application does not wish Readline to catch @code{SIGWINCH}, it may
-call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
-Readline to update its idea of the terminal size when a @code{SIGWINCH}
-is received.
-
-@deftypefun void rl_echo_signal_char (int sig)
-If an application wishes to install its own signal handlers, but still
-have readline display characters that generate signals, calling this
-function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or
-@code{SIGTSTP} will display the character generating that signal.
-@end deftypefun
-
-@deftypefun void rl_resize_terminal (void)
-Update Readline's internal screen size by reading values from the kernel.
-@end deftypefun
-
-@deftypefun void rl_set_screen_size (int rows, int cols)
-Set Readline's idea of the terminal size to @var{rows} rows and
-@var{cols} columns.  If either @var{rows} or @var{columns} is less than
-or equal to 0, Readline's idea of that terminal dimension is unchanged.
-@end deftypefun
-
-If an application does not want to install a @code{SIGWINCH} handler, but
-is still interested in the screen dimensions, Readline's idea of the screen
-size may be queried.
-
-@deftypefun void rl_get_screen_size (int *rows, int *cols)
-Return Readline's idea of the terminal's size in the
-variables pointed to by the arguments.
-@end deftypefun
-
-@deftypefun void rl_reset_screen_size (void)
-Cause Readline to reobtain the screen size and recalculate its dimensions.
-@end deftypefun
-
-The following functions install and remove Readline's signal handlers.
-
-@deftypefun int rl_set_signals (void)
-Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
-@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
-@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
-@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
-@end deftypefun
-
-@deftypefun int rl_clear_signals (void)
-Remove all of the Readline signal handlers installed by
-@code{rl_set_signals()}.
-@end deftypefun
-
-@node Custom Completers
-@section Custom Completers
-@cindex application-specific completion functions
-
-Typically, a program that reads commands from the user has a way of
-disambiguating commands and data.  If your program is one of these, then
-it can provide completion for commands, data, or both.
-The following sections describe how your program and Readline
-cooperate to provide this service.
-
-@menu
-* How Completing Works::	The logic used to do completion.
-* Completion Functions::	Functions provided by Readline.
-* Completion Variables::	Variables which control completion.
-* A Short Completion Example::	An example of writing completer subroutines.
-@end menu
-
-@node How Completing Works
-@subsection How Completing Works
-
-In order to complete some text, the full list of possible completions
-must be available.  That is, it is not possible to accurately
-expand a partial word without knowing all of the possible words
-which make sense in that context.  The Readline library provides
-the user interface to completion, and two of the most common
-completion functions:  filename and username.  For completing other types
-of text, you must write your own completion function.  This section
-describes exactly what such functions must do, and provides an example.
-
-There are three major functions used to perform completion:
-
-@enumerate
-@item
-The user-interface function @code{rl_complete()}.  This function is
-called with the same arguments as other bindable Readline functions:
-@var{count} and @var{invoking_key}.
-It isolates the word to be completed and calls
-@code{rl_completion_matches()} to generate a list of possible completions.
-It then either lists the possible completions, inserts the possible
-completions, or actually performs the
-completion, depending on which behavior is desired.
-
-@item
-The internal function @code{rl_completion_matches()} uses an
-application-supplied @dfn{generator} function to generate the list of
-possible matches, and then returns the array of these matches.
-The caller should place the address of its generator function in
-@code{rl_completion_entry_function}.
-
-@item
-The generator function is called repeatedly from
-@code{rl_completion_matches()}, returning a string each time.  The
-arguments to the generator function are @var{text} and @var{state}.
-@var{text} is the partial word to be completed.  @var{state} is zero the
-first time the function is called, allowing the generator to perform
-any necessary initialization, and a positive non-zero integer for
-each subsequent call.  The generator function returns
-@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
-no more possibilities left.  Usually the generator function computes the
-list of possible completions when @var{state} is zero, and returns them
-one at a time on subsequent calls.  Each string the generator function
-returns as a match must be allocated with @code{malloc()}; Readline
-frees the strings when it has finished with them.
-Such a generator function is referred to as an
-@dfn{application-specific completion function}.
-
-@end enumerate
-
-@deftypefun int rl_complete (int ignore, int invoking_key)
-Complete the word at or before point.  You have supplied the function
-that does the initial simple matching selection algorithm (see
-@code{rl_completion_matches()}).  The default is to do filename completion.
-@end deftypefun
-
-@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
-This is a pointer to the generator function for
-@code{rl_completion_matches()}.
-If the value of @code{rl_completion_entry_function} is
-@code{NULL} then the default filename generator
-function, @code{rl_filename_completion_function()}, is used.
-An @dfn{application-specific completion function} is a function whose
-address is assigned to @code{rl_completion_entry_function} and whose
-return values are used to  generate possible completions.
-@end deftypevar
-
-@node Completion Functions
-@subsection Completion Functions
-
-Here is the complete list of callable completion functions present in
-Readline.
-
-@deftypefun int rl_complete_internal (int what_to_do)
-Complete the word at or before point.  @var{what_to_do} says what to do
-with the completion.  A value of @samp{?} means list the possible
-completions.  @samp{TAB} means do standard completion.  @samp{*} means
-insert all of the possible completions.  @samp{!} means to display
-all of the possible completions, if there is more than one, as well as
-performing partial completion.  @samp{@@} is similar to @samp{!}, but
-possible completions are not listed if the possible completions share
-a common prefix.
-@end deftypefun
-
-@deftypefun int rl_complete (int ignore, int invoking_key)
-Complete the word at or before point.  You have supplied the function
-that does the initial simple matching selection algorithm (see
-@code{rl_completion_matches()} and @code{rl_completion_entry_function}).
-The default is to do filename
-completion.  This calls @code{rl_complete_internal()} with an
-argument depending on @var{invoking_key}.
-@end deftypefun
-
-@deftypefun int rl_possible_completions (int count, int invoking_key)
-List the possible completions.  See description of @code{rl_complete
-()}.  This calls @code{rl_complete_internal()} with an argument of
-@samp{?}.
-@end deftypefun
-
-@deftypefun int rl_insert_completions (int count, int invoking_key)
-Insert the list of possible completions into the line, deleting the
-partially-completed word.  See description of @code{rl_complete()}.
-This calls @code{rl_complete_internal()} with an argument of @samp{*}.
-@end deftypefun
-
-@deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
-Returns the appropriate value to pass to @code{rl_complete_internal()}
-depending on whether @var{cfunc} was called twice in succession and
-the values of the @code{show-all-if-ambiguous} and
-@code{show-all-if-unmodified} variables.
-Application-specific completion functions may use this function to present
-the same interface as @code{rl_complete()}.
-@end deftypefun
-
-@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
-Returns an array of strings which is a list of completions for
-@var{text}.  If there are no completions, returns @code{NULL}.
-The first entry in the returned array is the substitution for @var{text}.
-The remaining entries are the possible completions.  The array is
-terminated with a @code{NULL} pointer.
-
-@var{entry_func} is a function of two args, and returns a
-@code{char *}.  The first argument is @var{text}.  The second is a
-state argument; it is zero on the first call, and non-zero on subsequent
-calls.  @var{entry_func} returns a @code{NULL}  pointer to the caller
-when there are no more matches.
-@end deftypefun
-
-@deftypefun {char *} rl_filename_completion_function (const char *text, int state)
-A generator function for filename completion in the general case.
-@var{text} is a partial filename.
-The Bash source is a useful reference for writing application-specific
-completion functions (the Bash completion functions call this and other
-Readline functions).
-@end deftypefun
-
-@deftypefun {char *} rl_username_completion_function (const char *text, int state)
-A completion generator for usernames.  @var{text} contains a partial
-username preceded by a random character (usually @samp{~}).  As with all
-completion generators, @var{state} is zero on the first call and non-zero
-for subsequent calls.
-@end deftypefun
-
-@node Completion Variables
-@subsection Completion Variables
-
-@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
-A pointer to the generator function for @code{rl_completion_matches()}.
-@code{NULL} means to use @code{rl_filename_completion_function()},
-the default filename completer.
-@end deftypevar
-
-@deftypevar {rl_completion_func_t *} rl_attempted_completion_function
-A pointer to an alternative function to create matches.
-The function is called with @var{text}, @var{start}, and @var{end}.
-@var{start} and @var{end} are indices in @code{rl_line_buffer} defining
-the boundaries of @var{text}, which is a character string.
-If this function exists and returns @code{NULL}, or if this variable is
-set to @code{NULL}, then @code{rl_complete()} will call the value of
-@code{rl_completion_entry_function} to generate matches, otherwise the
-array of strings returned will be used.
-If this function sets the @code{rl_attempted_completion_over}
-variable to a non-zero value, Readline will not perform its default
-completion even if this function returns no matches.
-@end deftypevar
-
-@deftypevar {rl_quote_func_t *} rl_filename_quoting_function
-A pointer to a function that will quote a filename in an
-application-specific fashion.  This is called if filename completion is being
-attempted and one of the characters in @code{rl_filename_quote_characters}
-appears in a completed filename.  The function is called with
-@var{text}, @var{match_type}, and @var{quote_pointer}.  The @var{text}
-is the filename to be quoted.  The @var{match_type} is either
-@code{SINGLE_MATCH}, if there is only one completion match, or
-@code{MULT_MATCH}.  Some functions use this to decide whether or not to
-insert a closing quote character.  The @var{quote_pointer} is a pointer
-to any opening quote character the user typed.  Some functions choose
-to reset this character.
-@end deftypevar
-
-@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
-A pointer to a function that will remove application-specific quoting
-characters from a filename before completion is attempted, so those
-characters do not interfere with matching the text against names in
-the filesystem.  It is called with @var{text}, the text of the word
-to be dequoted, and @var{quote_char}, which is the quoting character 
-that delimits the filename (usually @samp{'} or @samp{"}).  If
-@var{quote_char} is zero, the filename was not in an embedded string.
-@end deftypevar
-
-@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
-A pointer to a function to call that determines whether or not a specific
-character in the line buffer is quoted, according to whatever quoting
-mechanism the program calling Readline uses.  The function is called with
-two arguments: @var{text}, the text of the line, and @var{index}, the
-index of the character in the line.  It is used to decide whether a
-character found in @code{rl_completer_word_break_characters} should be
-used to break words for the completer.
-@end deftypevar
-
-@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
-This function, if defined, is called by the completer when real filename
-completion is done, after all the matching names have been generated.
-It is passed a @code{NULL} terminated array of matches.
-The first element (@code{matches[0]}) is the
-maximal substring common to all matches. This function can
-re-arrange the list of matches as required, but each element deleted
-from the array must be freed.
-@end deftypevar
-
-@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
-This function, if defined, is allowed to modify the directory portion
-of filenames Readline completes.
-It could be used to expand symbolic links or shell variables in pathnames.
-It is called with the address of a string (the current directory name) as an
-argument, and may modify that string.
-If the string is replaced with a new string, the old value should be freed.
-Any modified directory name should have a trailing slash.
-The modified value will be used as part of the completion, replacing
-the directory portion of the pathname the user typed.
-At the least, even if no other expansion is performed, this function should
-remove any quote characters from the directory name, because its result will
-be passed directly to @code{opendir()}.
-
-The directory completion hook returns an integer that should be non-zero if
-the function modifies its directory argument.
-The function should not modify the directory argument if it returns 0.
-@end deftypevar
-
-@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook;
-If non-zero, this is the address of a function to call when completing
-a directory name.  This function takes the address of the directory name
-to be modified as an argument.  Unlike @code{rl_directory_completion_hook},
-it only modifies the directory name used in @code{opendir}, not what is
-displayed when the possible completions are printed or inserted.  It is
-called before rl_directory_completion_hook.
-At the least, even if no other expansion is performed, this function should
-remove any quote characters from the directory name, because its result will
-be passed directly to @code{opendir()}.
-
-The directory rewrite hook returns an integer that should be non-zero if
-the function modfies its directory argument.
-The function should not modify the directory argument if it returns 0.
-@end deftypevar
-
-@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook
-If non-zero, this is the address of a function for the completer to
-call before deciding which character to append to a completed name.
-This function modifies its filename name argument, and the modified value
-is passed to @code{stat()} to determine the file's type and characteristics.
-This function does not need to remove quote characters from the filename.
-
-The stat hook returns an integer that should be non-zero if
-the function modfies its directory argument.
-The function should not modify the directory argument if it returns 0.
-@end deftypevar
-
-@deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook
-If non-zero, this is the address of a function called when reading
-directory entries from the filesystem for completion and comparing
-them to the partial word to be completed.  The function should
-perform any necessary application or system-specific conversion on
-the filename, such as converting between character sets or converting
-from a filesystem format to a character input format.
-The function takes two arguments: @var{fname}, the filename to be converted,
-and @var{fnlen}, its length in bytes.
-It must either return its first argument (if no conversion takes place)
-or the converted filename in newly-allocated memory.  The converted
-form is used to compare against the word to be completed, and, if it
-matches, is added to the list of matches.  Readline will free the
-allocated string.
-@end deftypevar
-
-@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
-If non-zero, then this is the address of a function to call when
-completing a word would normally display the list of possible matches.
-This function is called in lieu of Readline displaying the list.
-It takes three arguments:
-(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
-where @var{matches} is the array of matching strings,
-@var{num_matches} is the number of strings in that array, and
-@var{max_length} is the length of the longest string in that array.
-Readline provides a convenience function, @code{rl_display_match_list},
-that takes care of doing the display to Readline's output stream.
-You may call that function from this hook.
-@end deftypevar
-
-@deftypevar {const char *} rl_basic_word_break_characters
-The basic list of characters that signal a break between words for the
-completer routine.  The default value of this variable is the characters
-which break words for completion in Bash:
-@code{" \t\n\"\\'`@@$><=;|&@{("}.
-@end deftypevar
-
-@deftypevar {const char *} rl_basic_quote_characters
-A list of quote characters which can cause a word break.
-@end deftypevar
-
-@deftypevar {const char *} rl_completer_word_break_characters
-The list of characters that signal a break between words for
-@code{rl_complete_internal()}.  The default list is the value of
-@code{rl_basic_word_break_characters}.
-@end deftypevar
-
-@deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook
-If non-zero, this is the address of a function to call when Readline is
-deciding where to separate words for word completion.  It should return
-a character string like @code{rl_completer_word_break_characters} to be
-used to perform the current completion.  The function may choose to set
-@code{rl_completer_word_break_characters} itself.  If the function
-returns @code{NULL}, @code{rl_completer_word_break_characters} is used.
-@end deftypevar
-
-@deftypevar {const char *} rl_completer_quote_characters
-A list of characters which can be used to quote a substring of the line.
-Completion occurs on the entire substring, and within the substring
-@code{rl_completer_word_break_characters} are treated as any other character,
-unless they also appear within this list.
-@end deftypevar
-
-@deftypevar {const char *} rl_filename_quote_characters
-A list of characters that cause a filename to be quoted by the completer
-when they appear in a completed filename.  The default is the null string.
-@end deftypevar
-
-@deftypevar {const char *} rl_special_prefixes
-The list of characters that are word break characters, but should be
-left in @var{text} when it is passed to the completion function.
-Programs can use this to help determine what kind of completing to do.
-For instance, Bash sets this variable to "$@@" so that it can complete
-shell variables and hostnames.
-@end deftypevar
-
-@deftypevar int rl_completion_query_items
-Up to this many items will be displayed in response to a
-possible-completions call.  After that, readline asks the user if she is sure
-she wants to see them all.  The default value is 100.  A negative value 
-indicates that Readline should never ask the user.
-@end deftypevar
-
-@deftypevar {int} rl_completion_append_character
-When a single completion alternative matches at the end of the command
-line, this character is appended to the inserted completion text.  The
-default is a space character (@samp{ }).  Setting this to the null
-character (@samp{\0}) prevents anything being appended automatically.
-This can be changed in application-specific completion functions to
-provide the ``most sensible word separator character'' according to
-an application-specific command line syntax specification.
-It is set to the default before any application-specific completion function
-is called, and may only be changed within such a function.
-@end deftypevar
-
-@deftypevar int rl_completion_suppress_append
-If non-zero, @var{rl_completion_append_character} is not appended to
-matches at the end of the command line, as described above.
-It is set to 0 before any application-specific completion function
-is called, and may only be changed within such a function.
-@end deftypevar
-
-@deftypevar int rl_completion_quote_character
-When Readline is completing quoted text, as delimited by one of the
-characters in @var{rl_completer_quote_characters}, it sets this variable
-to the quoting character found.
-This is set before any application-specific completion function is called.
-@end deftypevar
-
-@deftypevar int rl_completion_suppress_quote
-If non-zero, Readline does not append a matching quote character when
-performing completion on a quoted string.
-It is set to 0 before any application-specific completion function
-is called, and may only be changed within such a function.
-@end deftypevar
-
-@deftypevar int rl_completion_found_quote
-When Readline is completing quoted text, it sets this variable
-to a non-zero value if the word being completed contains or is delimited
-by any quoting characters, including backslashes.
-This is set before any application-specific completion function is called.
-@end deftypevar
-
-@deftypevar int rl_completion_mark_symlink_dirs
-If non-zero, a slash will be appended to completed filenames that are
-symbolic links to directory names, subject to the value of the
-user-settable @var{mark-directories} variable.
-This variable exists so that application-specific completion functions
-can override the user's global preference (set via the
-@var{mark-symlinked-directories} Readline variable) if appropriate.
-This variable is set to the user's preference before any
-application-specific completion function is called, so unless that
-function modifies the value, the user's preferences are honored.
-@end deftypevar
-
-@deftypevar int rl_ignore_completion_duplicates
-If non-zero, then duplicates in the matches are removed.
-The default is 1.
-@end deftypevar
-
-@deftypevar int rl_filename_completion_desired
-Non-zero means that the results of the matches are to be treated as
-filenames.  This is @emph{always} zero when completion is attempted,
-and can only be changed
-within an application-specific completion function.  If it is set to a
-non-zero value by such a function, directory names have a slash appended
-and Readline attempts to quote completed filenames if they contain any
-characters in @code{rl_filename_quote_characters} and
-@code{rl_filename_quoting_desired} is set to a non-zero value.
-@end deftypevar
-
-@deftypevar int rl_filename_quoting_desired
-Non-zero means that the results of the matches are to be quoted using
-double quotes (or an application-specific quoting mechanism) if the
-completed filename contains any characters in
-@code{rl_filename_quote_chars}.  This is @emph{always} non-zero
-when completion is attempted, and can only be changed within an
-application-specific completion function.
-The quoting is effected via a call to the function pointed to
-by @code{rl_filename_quoting_function}.
-@end deftypevar
-
-@deftypevar int rl_attempted_completion_over
-If an application-specific completion function assigned to
-@code{rl_attempted_completion_function} sets this variable to a non-zero
-value, Readline will not perform its default filename completion even
-if the application's completion function returns no matches.
-It should be set only by an application's completion function.
-@end deftypevar
-
-@deftypevar int rl_sort_completion_matches
-If an application sets this variable to 0, Readline will not sort the
-list of completions (which implies that it cannot remove any duplicate
-completions).  The default value is 1, which means that Readline will
-sort the completions and, depending on the value of
-@code{rl_ignore_completion_duplicates}, will attempt to remove duplicate
-matches.
-@end deftypevar
-
-@deftypevar int rl_completion_type
-Set to a character describing the type of completion Readline is currently
-attempting; see the description of @code{rl_complete_internal()}
-(@pxref{Completion Functions}) for the list of characters.
-This is set to the appropriate value before any application-specific
-completion function is called, allowing such functions to present
-the same interface as @code{rl_complete()}.
-@end deftypevar
-
-@deftypevar int rl_completion_invoking_key
-Set to the final character in the key sequence that invoked one of the
-completion functions that call @code{rl_complete_internal()}.  This is
-set to the appropriate value before any application-specific completion
-function is called.
-@end deftypevar
-
-@deftypevar int rl_inhibit_completion
-If this variable is non-zero, completion is inhibited.  The completion
-character will be inserted as any other bound to @code{self-insert}.
-@end deftypevar
-
-@node A Short Completion Example
-@subsection A Short Completion Example
-
-Here is a small application demonstrating the use of the GNU Readline
-library.  It is called @code{fileman}, and the source code resides in
-@file{examples/fileman.c}.  This sample application provides
-completion of command names, line editing features, and access to the
-history list.
-
-@page
-@smallexample
-/* fileman.c -- A tiny application which demonstrates how to use the
-   GNU Readline library.  This application interactively allows users
-   to manipulate files and their modes. */
-
-#ifdef HAVE_CONFIG_H
-#  include <config.h>
-#endif
-
-#include <sys/types.h>
-#ifdef HAVE_SYS_FILE_H
-#  include <sys/file.h>
-#endif
-#include <sys/stat.h>
-
-#ifdef HAVE_UNISTD_H
-#  include <unistd.h>
-#endif
-
-#include <fcntl.h>
-#include <stdio.h>
-#include <errno.h>
-
-#if defined (HAVE_STRING_H)
-#  include <string.h>
-#else /* !HAVE_STRING_H */
-#  include <strings.h>
-#endif /* !HAVE_STRING_H */
-
-#ifdef HAVE_STDLIB_H
-#  include <stdlib.h>
-#endif
-
-#include <time.h>
-
-#include <readline/readline.h>
-#include <readline/history.h>
-
-extern char *xmalloc PARAMS((size_t));
-
-/* The names of functions that actually do the manipulation. */
-int com_list PARAMS((char *));
-int com_view PARAMS((char *));
-int com_rename PARAMS((char *));
-int com_stat PARAMS((char *));
-int com_pwd PARAMS((char *));
-int com_delete PARAMS((char *));
-int com_help PARAMS((char *));
-int com_cd PARAMS((char *));
-int com_quit PARAMS((char *));
-
-/* A structure which contains information on the commands this program
-   can understand. */
-
-typedef struct @{
-  char *name;			/* User printable name of the function. */
-  rl_icpfunc_t *func;		/* Function to call to do the job. */
-  char *doc;			/* Documentation for this function.  */
-@} COMMAND;
-
-COMMAND commands[] = @{
-  @{ "cd", com_cd, "Change to directory DIR" @},
-  @{ "delete", com_delete, "Delete FILE" @},
-  @{ "help", com_help, "Display this text" @},
-  @{ "?", com_help, "Synonym for `help'" @},
-  @{ "list", com_list, "List files in DIR" @},
-  @{ "ls", com_list, "Synonym for `list'" @},
-  @{ "pwd", com_pwd, "Print the current working directory" @},
-  @{ "quit", com_quit, "Quit using Fileman" @},
-  @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
-  @{ "stat", com_stat, "Print out statistics on FILE" @},
-  @{ "view", com_view, "View the contents of FILE" @},
-  @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
-@};
-
-/* Forward declarations. */
-char *stripwhite ();
-COMMAND *find_command ();
-
-/* The name of this program, as taken from argv[0]. */
-char *progname;
-
-/* When non-zero, this global means the user is done using this program. */
-int done;
-
-char *
-dupstr (s)
-     char *s;
-@{
-  char *r;
-
-  r = xmalloc (strlen (s) + 1);
-  strcpy (r, s);
-  return (r);
-@}
-
-main (argc, argv)
-     int argc;
-     char **argv;
-@{
-  char *line, *s;
-
-  progname = argv[0];
-
-  initialize_readline ();	/* Bind our completer. */
-
-  /* Loop reading and executing lines until the user quits. */
-  for ( ; done == 0; )
-    @{
-      line = readline ("FileMan: ");
-
-      if (!line)
-        break;
-
-      /* Remove leading and trailing whitespace from the line.
-         Then, if there is anything left, add it to the history list
-         and execute it. */
-      s = stripwhite (line);
-
-      if (*s)
-        @{
-          add_history (s);
-          execute_line (s);
-        @}
-
-      free (line);
-    @}
-  exit (0);
-@}
-
-/* Execute a command line. */
-int
-execute_line (line)
-     char *line;
-@{
-  register int i;
-  COMMAND *command;
-  char *word;
-
-  /* Isolate the command word. */
-  i = 0;
-  while (line[i] && whitespace (line[i]))
-    i++;
-  word = line + i;
-
-  while (line[i] && !whitespace (line[i]))
-    i++;
-
-  if (line[i])
-    line[i++] = '\0';
-
-  command = find_command (word);
-
-  if (!command)
-    @{
-      fprintf (stderr, "%s: No such command for FileMan.\n", word);
-      return (-1);
-    @}
-
-  /* Get argument to command, if any. */
-  while (whitespace (line[i]))
-    i++;
-
-  word = line + i;
-
-  /* Call the function. */
-  return ((*(command->func)) (word));
-@}
-
-/* Look up NAME as the name of a command, and return a pointer to that
-   command.  Return a NULL pointer if NAME isn't a command name. */
-COMMAND *
-find_command (name)
-     char *name;
-@{
-  register int i;
-
-  for (i = 0; commands[i].name; i++)
-    if (strcmp (name, commands[i].name) == 0)
-      return (&commands[i]);
-
-  return ((COMMAND *)NULL);
-@}
-
-/* Strip whitespace from the start and end of STRING.  Return a pointer
-   into STRING. */
-char *
-stripwhite (string)
-     char *string;
-@{
-  register char *s, *t;
-
-  for (s = string; whitespace (*s); s++)
-    ;
-    
-  if (*s == 0)
-    return (s);
-
-  t = s + strlen (s) - 1;
-  while (t > s && whitespace (*t))
-    t--;
-  *++t = '\0';
-
-  return s;
-@}
-
-/* **************************************************************** */
-/*                                                                  */
-/*                  Interface to Readline Completion                */
-/*                                                                  */
-/* **************************************************************** */
-
-char *command_generator PARAMS((const char *, int));
-char **fileman_completion PARAMS((const char *, int, int));
-
-/* Tell the GNU Readline library how to complete.  We want to try to complete
-   on command names if this is the first word in the line, or on filenames
-   if not. */
-initialize_readline ()
-@{
-  /* Allow conditional parsing of the ~/.inputrc file. */
-  rl_readline_name = "FileMan";
-
-  /* Tell the completer that we want a crack first. */
-  rl_attempted_completion_function = fileman_completion;
-@}
-
-/* Attempt to complete on the contents of TEXT.  START and END bound the
-   region of rl_line_buffer that contains the word to complete.  TEXT is
-   the word to complete.  We can use the entire contents of rl_line_buffer
-   in case we want to do some simple parsing.  Return the array of matches,
-   or NULL if there aren't any. */
-char **
-fileman_completion (text, start, end)
-     const char *text;
-     int start, end;
-@{
-  char **matches;
-
-  matches = (char **)NULL;
-
-  /* If this word is at the start of the line, then it is a command
-     to complete.  Otherwise it is the name of a file in the current
-     directory. */
-  if (start == 0)
-    matches = rl_completion_matches (text, command_generator);
-
-  return (matches);
-@}
-
-/* Generator function for command completion.  STATE lets us know whether
-   to start from scratch; without any state (i.e. STATE == 0), then we
-   start at the top of the list. */
-char *
-command_generator (text, state)
-     const char *text;
-     int state;
-@{
-  static int list_index, len;
-  char *name;
-
-  /* If this is a new word to complete, initialize now.  This includes
-     saving the length of TEXT for efficiency, and initializing the index
-     variable to 0. */
-  if (!state)
-    @{
-      list_index = 0;
-      len = strlen (text);
-    @}
-
-  /* Return the next name which partially matches from the command list. */
-  while (name = commands[list_index].name)
-    @{
-      list_index++;
-
-      if (strncmp (name, text, len) == 0)
-        return (dupstr(name));
-    @}
-
-  /* If no names matched, then return NULL. */
-  return ((char *)NULL);
-@}
-
-/* **************************************************************** */
-/*                                                                  */
-/*                       FileMan Commands                           */
-/*                                                                  */
-/* **************************************************************** */
-
-/* String to pass to system ().  This is for the LIST, VIEW and RENAME
-   commands. */
-static char syscom[1024];
-
-/* List the file(s) named in arg. */
-com_list (arg)
-     char *arg;
-@{
-  if (!arg)
-    arg = "";
-
-  sprintf (syscom, "ls -FClg %s", arg);
-  return (system (syscom));
-@}
-
-com_view (arg)
-     char *arg;
-@{
-  if (!valid_argument ("view", arg))
-    return 1;
-
-#if defined (__MSDOS__)
-  /* more.com doesn't grok slashes in pathnames */
-  sprintf (syscom, "less %s", arg);
-#else
-  sprintf (syscom, "more %s", arg);
-#endif
-  return (system (syscom));
-@}
-
-com_rename (arg)
-     char *arg;
-@{
-  too_dangerous ("rename");
-  return (1);
-@}
-
-com_stat (arg)
-     char *arg;
-@{
-  struct stat finfo;
-
-  if (!valid_argument ("stat", arg))
-    return (1);
-
-  if (stat (arg, &finfo) == -1)
-    @{
-      perror (arg);
-      return (1);
-    @}
-
-  printf ("Statistics for `%s':\n", arg);
-
-  printf ("%s has %d link%s, and is %d byte%s in length.\n",
-	  arg,
-          finfo.st_nlink,
-          (finfo.st_nlink == 1) ? "" : "s",
-          finfo.st_size,
-          (finfo.st_size == 1) ? "" : "s");
-  printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
-  printf ("      Last access at: %s", ctime (&finfo.st_atime));
-  printf ("    Last modified at: %s", ctime (&finfo.st_mtime));
-  return (0);
-@}
-
-com_delete (arg)
-     char *arg;
-@{
-  too_dangerous ("delete");
-  return (1);
-@}
-
-/* Print out help for ARG, or for all of the commands if ARG is
-   not present. */
-com_help (arg)
-     char *arg;
-@{
-  register int i;
-  int printed = 0;
-
-  for (i = 0; commands[i].name; i++)
-    @{
-      if (!*arg || (strcmp (arg, commands[i].name) == 0))
-        @{
-          printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
-          printed++;
-        @}
-    @}
-
-  if (!printed)
-    @{
-      printf ("No commands match `%s'.  Possibilties are:\n", arg);
-
-      for (i = 0; commands[i].name; i++)
-        @{
-          /* Print in six columns. */
-          if (printed == 6)
-            @{
-              printed = 0;
-              printf ("\n");
-            @}
-
-          printf ("%s\t", commands[i].name);
-          printed++;
-        @}
-
-      if (printed)
-        printf ("\n");
-    @}
-  return (0);
-@}
-
-/* Change to the directory ARG. */
-com_cd (arg)
-     char *arg;
-@{
-  if (chdir (arg) == -1)
-    @{
-      perror (arg);
-      return 1;
-    @}
-
-  com_pwd ("");
-  return (0);
-@}
-
-/* Print out the current working directory. */
-com_pwd (ignore)
-     char *ignore;
-@{
-  char dir[1024], *s;
-
-  s = getcwd (dir, sizeof(dir) - 1);
-  if (s == 0)
-    @{
-      printf ("Error getting pwd: %s\n", dir);
-      return 1;
-    @}
-
-  printf ("Current directory is %s\n", dir);
-  return 0;
-@}
-
-/* The user wishes to quit using this program.  Just set DONE non-zero. */
-com_quit (arg)
-     char *arg;
-@{
-  done = 1;
-  return (0);
-@}
-
-/* Function which tells you that you can't do this. */
-too_dangerous (caller)
-     char *caller;
-@{
-  fprintf (stderr,
-           "%s: Too dangerous for me to distribute.  Write it yourself.\n",
-           caller);
-@}
-
-/* Return non-zero if ARG is a valid argument for CALLER, else print
-   an error message and return zero. */
-int
-valid_argument (caller, arg)
-     char *caller, *arg;
-@{
-  if (!arg || !*arg)
-    @{
-      fprintf (stderr, "%s: Argument required.\n", caller);
-      return (0);
-    @}
-
-  return (1);
-@}
-@end smallexample