"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/rltech.texi" between
readline-7.0-rc1.tar.gz and readline-7.0-rc2.tar.gz

About: GNU Readline library - get a line from a user with editing. Release candidate.

rltech.texi  (readline-7.0-rc1):rltech.texi  (readline-7.0-rc2)
skipping to change at line 965 skipping to change at line 965
@deftypefun int rl_on_new_line_with_prompt (void) @deftypefun int rl_on_new_line_with_prompt (void)
Tell the update functions that we have moved onto a new line, with Tell the update functions that we have moved onto a new line, with
@var{rl_prompt} already displayed. @var{rl_prompt} already displayed.
This could be used by applications that want to output the prompt string 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 themselves, but still need Readline to know the prompt string length for
redisplay. redisplay.
It should be used after setting @var{rl_already_prompted}. It should be used after setting @var{rl_already_prompted}.
@end deftypefun @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) @deftypefun int rl_reset_line_state (void)
Reset the display state to a clean state and redisplay the current line Reset the display state to a clean state and redisplay the current line
starting on a new line. starting on a new line.
@end deftypefun @end deftypefun
@deftypefun int rl_crlf (void) @deftypefun int rl_crlf (void)
Move the cursor to the start of the next screen line. Move the cursor to the start of the next screen line.
@end deftypefun @end deftypefun
@deftypefun int rl_show_char (int c) @deftypefun int rl_show_char (int c)
skipping to change at line 1138 skipping to change at line 1142
displayed by @code{stty}) to their Readline equivalents. displayed by @code{stty}) to their Readline equivalents.
The bindings are performed in @var{kmap}. The bindings are performed in @var{kmap}.
@end deftypefun @end deftypefun
@deftypefun void rl_tty_unset_default_bindings (Keymap kmap) @deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
that the terminal editing characters are bound to @code{rl_insert}. that the terminal editing characters are bound to @code{rl_insert}.
The bindings are performed in @var{kmap}. The bindings are performed in @var{kmap}.
@end deftypefun @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) @deftypefun int rl_reset_terminal (const char *terminal_name)
Reinitialize Readline's idea of the terminal settings using Reinitialize Readline's idea of the terminal settings using
@var{terminal_name} as the terminal type (e.g., @code{vt100}). @var{terminal_name} as the terminal type (e.g., @code{vt100}).
If @var{terminal_name} is @code{NULL}, the value of the @code{TERM} If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
environment variable is used. environment variable is used.
@end deftypefun @end deftypefun
@node Utility Functions @node Utility Functions
@subsection Utility Functions @subsection Utility Functions
skipping to change at line 1425 skipping to change at line 1437
@subsection Alternate Interface Example @subsection Alternate Interface Example
Here is a complete program that illustrates Readline's alternate interface. Here is a complete program that illustrates Readline's alternate interface.
It reads lines from the terminal and displays them, providing the It reads lines from the terminal and displays them, providing the
standard history and TAB completion functions. standard history and TAB completion functions.
It understands the EOF character or "exit" to exit the program. It understands the EOF character or "exit" to exit the program.
@example @example
/* Standard include files. stdio.h is required. */ /* Standard include files. stdio.h is required. */
#include <stdlib.h> #include <stdlib.h>
#include <string.h>
#include <unistd.h> #include <unistd.h>
#include <locale.h>
/* Used for select(2) */ /* Used for select(2) */
#include <sys/types.h> #include <sys/types.h>
#include <sys/select.h> #include <sys/select.h>
#include <signal.h>
#include <stdio.h> #include <stdio.h>
/* Standard readline include files. */ /* Standard readline include files. */
#include <readline/readline.h> #include <readline/readline.h>
#include <readline/history.h> #include <readline/history.h>
static void cb_linehandler (char *); static void cb_linehandler (char *);
static void sighandler (int);
int running; int running;
int sigwinch_received;
const char *prompt = "rltest$ "; 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 /* Callback function called for each line when accept-line executed, EOF
seen, or EOF character read. This sets a flag and returns; it could seen, or EOF character read. This sets a flag and returns; it could
also call exit(3). */ also call exit(3). */
static void static void
cb_linehandler (char *line) cb_linehandler (char *line)
@{ @{
/* Can use ^D (stty eof) or `exit' to exit. */ /* Can use ^D (stty eof) or `exit' to exit. */
if (line == NULL || strcmp (line, "exit") == 0) if (line == NULL || strcmp (line, "exit") == 0)
@{ @{
if (line == 0) if (line == 0)
skipping to change at line 1476 skipping to change at line 1502
free (line); free (line);
@} @}
@} @}
int int
main (int c, char **v) main (int c, char **v)
@{ @{
fd_set fds; fd_set fds;
int r; 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. */ /* Install the line handler. */
rl_callback_handler_install (prompt, cb_linehandler); rl_callback_handler_install (prompt, cb_linehandler);
/* Enter a simple event loop. This waits until something is available /* Enter a simple event loop. This waits until something is available
to read on readline's input stream (defaults to standard input) and to read on readline's input stream (defaults to standard input) and
calls the builtin character read callback to read it. It does not calls the builtin character read callback to read it. It does not
have to modify the user's terminal settings. */ have to modify the user's terminal settings. */
running = 1; running = 1;
while (running) while (running)
@{ @{
FD_ZERO (&fds); FD_ZERO (&fds);
FD_SET (fileno (rl_instream), &fds); FD_SET (fileno (rl_instream), &fds);
r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
if (r < 0) if (r < 0 && errno != EINTR)
@{ @{
perror ("rltest: select"); perror ("rltest: select");
rl_callback_handler_remove (); rl_callback_handler_remove ();
break; break;
@} @}
if (sigwinch_received)
@{
rl_resize_terminal ();
sigwinch_received = 0;
@}
if (r < 0)
continue;
if (FD_ISSET (fileno (rl_instream), &fds)) if (FD_ISSET (fileno (rl_instream), &fds))
rl_callback_read_char (); rl_callback_read_char ();
@} @}
printf ("rltest: Event loop has exited\n"); printf ("rltest: Event loop has exited\n");
return 0; return 0;
@} @}
@end example @end example
skipping to change at line 1553 skipping to change at line 1593
call @code{rl_cleanup_after_signal()} (described below), to restore the call @code{rl_cleanup_after_signal()} (described below), to restore the
terminal state. terminal state.
When an application is using the callback interface When an application is using the callback interface
(@pxref{Alternate Interface}), Readline installs signal handlers only for (@pxref{Alternate Interface}), Readline installs signal handlers only for
the duration of the call to @code{rl_callback_read_char}. Applications the duration of the call to @code{rl_callback_read_char}. Applications
using the callback interface should be prepared to clean up Readline's 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 state if they wish to handle the signal before the line handler completes
and restores the terminal state. 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 Readline provides two variables that allow application writers to
control whether or not it will catch certain signals and act on them control whether or not it will catch certain signals and act on them
when they are received. It is important that applications change the when they are received. It is important that applications change the
values of these variables only when calling @code{readline()}, not in values of these variables only when calling @code{readline()}, not in
a signal handler, so Readline's internal signal state is not corrupted. a signal handler, so Readline's internal signal state is not corrupted.
@deftypevar int rl_catch_signals @deftypevar int rl_catch_signals
If this variable is non-zero, Readline will install signal handlers for If this variable is non-zero, Readline will install signal handlers for
@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}. @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
skipping to change at line 1574 skipping to change at line 1630
The default value of @code{rl_catch_signals} is 1. The default value of @code{rl_catch_signals} is 1.
@end deftypevar @end deftypevar
@deftypevar int rl_catch_sigwinch @deftypevar int rl_catch_sigwinch
If this variable is set to a non-zero value, If this variable is set to a non-zero value,
Readline will install a signal handler for @code{SIGWINCH}. Readline will install a signal handler for @code{SIGWINCH}.
The default value of @code{rl_catch_sigwinch} is 1. The default value of @code{rl_catch_sigwinch} is 1.
@end deftypevar @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 @deftypevar int rl_change_environment
If this variable is set to a non-zero value, If this variable is set to a non-zero value,
and Readline is handling @code{SIGWINCH}, Readline will modify the and Readline is handling @code{SIGWINCH}, Readline will modify the
@var{LINES} and @var{COLUMNS} environment variables upon receipt of a @var{LINES} and @var{COLUMNS} environment variables upon receipt of a
@code{SIGWINCH} @code{SIGWINCH}
The default value of @code{rl_change_environment} is 1. The default value of @code{rl_change_environment} is 1.
@end deftypevar @end deftypevar
If an application does not wish to have Readline catch any signals, or If an application does not wish to have Readline catch any signals, or
to handle signals other than those Readline catches (@code{SIGHUP}, to handle signals other than those Readline catches (@code{SIGHUP},
for example), for example),
Readline provides convenience functions to do the necessary terminal Readline provides convenience functions to do the necessary terminal
and internal state cleanup upon receipt of a signal. 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) @deftypefun void rl_cleanup_after_signal (void)
This function will reset the state of the terminal to what it was before 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{readline()} was called, and remove the Readline signal handlers for
all signals, depending on the values of @code{rl_catch_signals} and all signals, depending on the values of @code{rl_catch_signals} and
@code{rl_catch_sigwinch}. @code{rl_catch_sigwinch}.
@end deftypefun @end deftypefun
@deftypefun void rl_free_line_state (void) @deftypefun void rl_free_line_state (void)
This will free any partial state associated with the current input line This will free any partial state associated with the current input line
(undo information, any partial history entry, any partially-entered (undo information, any partial history entry, any partially-entered
 End of changes. 14 change blocks. 
1 lines changed or deleted 72 lines changed or added

Home  |  About  |  All  |  Newest  |  Fossies Dox  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTPS