in the consistency of user interface across discrete programs that need
to provide a command line interface.
-Copyright (C) 1988--2014 Free Software Foundation, Inc.
+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
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.
@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.
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
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)
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.
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}).
@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/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). */
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);
FD_SET (fileno (rl_instream), &fds);
r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
- if (r < 0)
+ 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 ();
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
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
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
@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}
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
projects / deliverable / binutils-gdb.git / blobdiff