in the consitency of user interface across discrete programs that need
to provide a command line interface.
-Copyright (C) 1988, 1994, 1996 Free Software Foundation, Inc.
+Copyright (C) 1988, 1994, 1996, 1998, 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
* Readline Variables:: Variables accessible to custom
functions.
* Readline Convenience Functions:: Functions which Readline supplies to
- aid in writing your own
+ 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
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}.
+
@menu
* The Function Type:: C declarations to make code readable.
* Function Writing:: Variables and calling conventions.
@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}.
+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
way to stuff a single character into the input stream.
@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.
@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 {char *} rl_library_version
The version number of this revision of the library.
@end deftypevar
before @code{readline} prints the first prompt.
@end deftypevar
+@deftypevar {Function *} 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 {Function *} rl_event_hook
If non-zero, this is the address of a function to call periodically
when readline is waiting for terminal input.
@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, Function *function)
Print the names of all bindable Readline functions to @code{rl_outstream}.
@end deftypefun
+@deftypefun {char **} rl_funmap_names ()
+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 when you done, but not the pointrs.
+@end deftypefun
+
@node Allowing Undoing
@subsection Allowing Undoing
@end deftypefun
@deftypefun int rl_on_new_line ()
-Tell the update routines that we have moved onto a new (empty) line,
+Tell the update functions that we have moved onto a new (empty) line,
usually after ouputting a newline.
@end deftypefun
+@deftypefun int rl_on_new_line_with_prompt ()
+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_reset_line_state ()
Reset the display state to a clean state and redisplay the current line
starting on a new line.
Clear the message in the echo area.
@end deftypefun
+@deftypefun void rl_save_prompt ()
+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 ()
+Restore the local Readline prompt display state saved by the most
+recent call to @code{rl_save_prompt}.
+@end deftypefun
+
@node Modifying Text
@subsection Modifying Text
@code{rl_read_key ()}.
@end deftypefun
-@deftypefun rl_extend_line_buffer (int len)
+@deftypefun int 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_reset_terminal (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 NULL, the value of the @code{TERM}
+environment variable is used.
@end deftypefun
@deftypefun int alphabetic (int c)
Ring the terminal bell, obeying the setting of @code{bell-style}.
@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}).
+@end deftypefun
+
The following are implemented as macros, defined in @code{chartypes.h}.
@deftypefun int uppercase_p (int c)
@}
@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 a signal is
+received 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{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 ()}).
+
+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 state, 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.
+
+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{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 non-zero, Readline will install a signal handler for
+@code{SIGWINCH}.
+
+The default value of @code{rl_catch_sigwinch} 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 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 does not wish Readline to catch @code{SIGWINCH}, it may
+call @code{rl_resize_terminal ()} to force Readline to update its idea of
+the terminal size when a @code{SIGWINCH} is received.
+
+@deftypefun void rl_resize_terminal (void)
+Update Readline's internal screen size.
+@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{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
@deftypevar {Function *} rl_completion_entry_function
A pointer to the generator function for @code{completion_matches ()}.
-@code{NULL} means to use @code{filename_entry_function ()}, the default
+@code{NULL} means to use @code{filename_completion_function ()}, the default
filename completer.
@end deftypevar
to expand symbolic links or shell variables in pathnames.
@end deftypevar
+@deftypevar {VFunction *} 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. That
+function may be called from this hook.
+@end deftypevar
+
@node A Short Completion Example
@subsection A Short Completion Example
projects / deliverable / binutils-gdb.git / blobdiff