GNU Info
(readline.info)Readline Signal Handling
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 (`SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM',
`SIGTSTP', `SIGTTIN', and `SIGTTOU'). When one of these signals is
received, the signal handler will reset the terminal attributes to
those that were in effect before `readline()' was called, reset the
signal handling to what it was before `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 `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
`rl_free_line_state()' below).
There is an additional Readline signal handler, for `SIGWINCH', which
the kernel sends to a process whenever the terminal's size changes (for
example, if a user resizes an `xterm'). The Readline `SIGWINCH'
handler updates Readline's internal screen size information, and then
calls any `SIGWINCH' signal handler the calling application has
installed. Readline calls the application's `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 `longjmp' back to a main
processing loop), it _must_ call `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 `readline()', not in a
signal handler, so Readline's internal signal state is not corrupted.
- Variable: int rl_catch_signals
If this variable is non-zero, Readline will install signal
handlers for `SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM', `SIGTSTP',
`SIGTTIN', and `SIGTTOU'.
The default value of `rl_catch_signals' is 1.
- Variable: int rl_catch_sigwinch
If this variable is non-zero, Readline will install a signal
handler for `SIGWINCH'.
The default value of `rl_catch_sigwinch' is 1.
If an application does not wish to have Readline catch any signals,
or to handle signals other than those Readline catches (`SIGHUP', for
example), Readline provides convenience functions to do the necessary
terminal and internal state cleanup upon receipt of a signal.
- Function: void rl_cleanup_after_signal (void)
This function will reset the state of the terminal to what it was
before `readline()' was called, and remove the Readline signal
handlers for all signals, depending on the values of
`rl_catch_signals' and `rl_catch_sigwinch'.
- Function: 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
`rl_cleanup_after_signal()'. The Readline signal handler for
`SIGINT' calls this to abort the current input line.
- Function: void rl_reset_after_signal (void)
This will reinitialize the terminal and reinstall any Readline
signal handlers, depending on the values of `rl_catch_signals' and
`rl_catch_sigwinch'.
If an application does not wish Readline to catch `SIGWINCH', it may
call `rl_resize_terminal()' or `rl_set_screen_size()' to force Readline
to update its idea of the terminal size when a `SIGWINCH' is received.
- Function: void rl_resize_terminal (void)
Update Readline's internal screen size by reading values from the
kernel.
- Function: void rl_set_screen_size (int rows, int cols)
Set Readline's idea of the terminal size to ROWS rows and COLS
columns.
If an application does not want to install a `SIGWINCH' handler, but
is still interested in the screen dimensions, Readline's idea of the
screen size may be queried.
- Function: 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.
The following functions install and remove Readline's signal
handlers.
- Function: int rl_set_signals (void)
Install Readline's signal handler for `SIGINT', `SIGQUIT',
`SIGTERM', `SIGALRM', `SIGTSTP', `SIGTTIN', `SIGTTOU', and
`SIGWINCH', depending on the values of `rl_catch_signals' and
`rl_catch_sigwinch'.
- Function: int rl_clear_signals (void)
Remove all of the Readline signal handlers installed by
`rl_set_signals()'.
automatically generated by info2www version 1.2.2.9