readline: Alternate Interface
2.4.12 Alternate Interface
--------------------------
An alternate interface is available to plain 'readline()'. Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to 'select()' on
various file descriptors. To accommodate this need, readline can also
be invoked as a 'callback' function from an event loop. There are
functions available to make this easy.
-- Function: void rl_callback_handler_install (const char *prompt,
rl_vcpfunc_t *lhandler)
Set up the terminal for readline I/O and display the initial
expanded value of PROMPT. Save the value of LHANDLER to use as a
handler function to call when a complete line of input has been
entered. The handler function receives the text of the line as an
argument. As with 'readline()', the handler function should 'free'
the line when it it finished with it.
-- Function: void rl_callback_read_char (void)
Whenever an application determines that keyboard input is
available, it should call 'rl_callback_read_char()', which will
read the next character from the current input source. If that
character completes the line, 'rl_callback_read_char' will invoke
the LHANDLER function installed by 'rl_callback_handler_install' to
process the line. Before calling the LHANDLER function, the
terminal settings are reset to the values they had before calling
'rl_callback_handler_install'. If the LHANDLER function returns,
and the line handler remains installed, the terminal settings are
modified for Readline's use again. 'EOF' is indicated by calling
LHANDLER with a 'NULL' line.
-- Function: void rl_callback_sigcleanup (void)
Clean up any internal state the callback interface uses to maintain
state between calls to rl_callback_read_char (e.g., the state of
any active incremental searches). This is intended to be used by
applications that wish to perform their own signal handling;
Readline's internal signal handler calls this when appropriate.
-- Function: void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line
handler. You may call this function from within a callback as well
as independently. If the LHANDLER installed by
'rl_callback_handler_install' does not exit the program, either
this function or the function referred to by the value of
'rl_deprep_term_function' should be called before the program exits
to reset the terminal settings.
Info Catalog
readline: Miscellaneous Functions
readline: Readline Convenience Functions
readline: A Readline Example