2.5 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().