(readline.info.gz) Readline Signal Handling

Info Catalog

(readline.info.gz) Readline Convenience Functions

(readline.info.gz) Programming with GNU Readline

(readline.info.gz) Custom Completers

 
 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 either ROWS or COLUMNS is less than or equal to 0,
      Readline's idea of that terminal dimension is unchanged.
 
    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.
 
  -- Function: void rl_reset_screen_size (void)
      Cause Readline to reobtain the screen size and recalculate its
      dimensions.
 
    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()'.
 

Info Catalog

(readline.info.gz) Readline Convenience Functions

(readline.info.gz) Programming with GNU Readline

(readline.info.gz) Custom Completers