rltech.texi

linux中bash shell的源代码

@deftypefun int rl_push_macro_input (char *macro)
Cause @var{macro} to be inserted into the line, as if it had been invoked
by a key bound to a macro.  Not especially useful; use
@code{rl_insert_text()} instead.
@end deftypefun

@node Character Input
@subsection Character Input

@deftypefun int rl_read_key (void)
Return the next character available from Readline's current input stream.
This handles input inserted into
the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
While waiting for input, this function will call any function assigned to
the @code{rl_event_hook} variable.
@end deftypefun

@deftypefun int rl_getc (FILE *stream)
Return the next character available from @var{stream}, which is assumed to
be the keyboard.
@end deftypefun

@deftypefun int rl_stuff_char (int c)
Insert @var{c} into the Readline input stream.  It will be "read"
before Readline attempts to read characters from the terminal with
@code{rl_read_key()}.  Up to 512 characters may be pushed back.
@code{rl_stuff_char} returns 1 if the character was successfully inserted;
0 otherwise.
@end deftypefun

@deftypefun int rl_execute_next (int c)
Make @var{c} be the next command to be executed when @code{rl_read_key()}
is called.  This sets @var{rl_pending_input}.
@end deftypefun

@deftypefun int rl_clear_pending_input (void)
Unset @var{rl_pending_input}, effectively negating the effect of any
previous call to @code{rl_execute_next()}.  This works only if the
pending input has not already been read with @code{rl_read_key()}.
@end deftypefun

@deftypefun int rl_set_keyboard_input_timeout (int u)
While waiting for keyboard input in @code{rl_read_key()}, Readline will
wait for @var{u} microseconds for input before calling any function
assigned to @code{rl_event_hook}.  The default waiting period is
one-tenth of a second.  Returns the old timeout value.
@end deftypefun

@node Terminal Management
@subsection Terminal Management

@deftypefun void rl_prep_terminal (int meta_flag)
Modify the terminal settings for Readline's use, so @code{readline()}
can read a single character at a time from the keyboard.
The @var{meta_flag} argument should be non-zero if Readline should
read eight-bit input.
@end deftypefun

@deftypefun void rl_deprep_terminal (void)
Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
the state in which it was before the most recent call to
@code{rl_prep_terminal()}.
@end deftypefun

@deftypefun void rl_tty_set_default_bindings (Keymap kmap)
Read the operating system's terminal editing characters (as would be
displayed by @code{stty}) to their Readline equivalents.
The bindings are performed in @var{kmap}.
@end deftypefun

@deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
that the terminal editing characters are bound to @code{rl_insert}.
The bindings are performed in @var{kmap}.
@end deftypefun

@deftypefun int rl_reset_terminal (const char *terminal_name)
Reinitialize Readline's idea of the terminal settings using
@var{terminal_name} as the terminal type (e.g., @code{vt100}).
If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
environment variable is used.
@end deftypefun

@node Utility Functions
@subsection Utility Functions

@deftypefun void rl_replace_line (const char *text, int clear_undo)
Replace the contents of @code{rl_line_buffer} with @var{text}.
The point and mark are preserved, if possible.
If @var{clear_undo} is non-zero, the undo list associated with the
current line is cleared.
@end deftypefun

@deftypefun int rl_extend_line_buffer (int len)
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
characters, possibly reallocating it if necessary.
@end deftypefun

@deftypefun int rl_initialize (void)
Initialize or re-initialize Readline's internal state.
It's not strictly necessary to call this; @code{readline()} calls it before
reading any input.
@end deftypefun

@deftypefun int rl_ding (void)
Ring the terminal bell, obeying the setting of @code{bell-style}.
@end deftypefun

@deftypefun int rl_alphabetic (int c)
Return 1 if @var{c} is an alphabetic character.
@end deftypefun

@deftypefun void rl_display_match_list (char **matches, int len, int max)
A convenience function for displaying a list of strings in
columnar format on Readline's output stream.  @code{matches} is the list
of strings, in argv format, such as a list of completion matches.
@code{len} is the number of strings in @code{matches}, and @code{max}
is the length of the longest string in @code{matches}.  This function uses
the setting of @code{print-completions-horizontally} to select how the
matches are displayed (@pxref{Readline Init File Syntax}).
@end deftypefun

The following are implemented as macros, defined in @code{chardefs.h}.
Applications should refrain from using them.

@deftypefun int _rl_uppercase_p (int c)
Return 1 if @var{c} is an uppercase alphabetic character.
@end deftypefun

@deftypefun int _rl_lowercase_p (int c)
Return 1 if @var{c} is a lowercase alphabetic character.
@end deftypefun

@deftypefun int _rl_digit_p (int c)
Return 1 if @var{c} is a numeric character.
@end deftypefun

@deftypefun int _rl_to_upper (int c)
If @var{c} is a lowercase alphabetic character, return the corresponding
uppercase character.
@end deftypefun

@deftypefun int _rl_to_lower (int c)
If @var{c} is an uppercase alphabetic character, return the corresponding
lowercase character.
@end deftypefun

@deftypefun int _rl_digit_value (int c)
If @var{c} is a number, return the value it represents.
@end deftypefun

@node Miscellaneous Functions
@subsection Miscellaneous Functions

@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
The binding is performed in @var{map}.  When @var{keyseq} is invoked, the
@var{macro} will be inserted into the line.  This function is deprecated;
use @code{rl_generic_bind()} instead.
@end deftypefun

@deftypefun void rl_macro_dumper (int readable)
Print the key sequences bound to macros and their values, using
the current keymap, to @code{rl_outstream}.
If @var{readable} is non-zero, the list is formatted in such a way
that it can be made part of an @code{inputrc} file and re-read.
@end deftypefun

@deftypefun int rl_variable_bind (const char *variable, const char *value)
Make the Readline variable @var{variable} have @var{value}.
This behaves as if the readline command
@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
file (@pxref{Readline Init File Syntax}).
@end deftypefun

@deftypefun {char *} rl_variable_value (const char *variable)
Return a string representing the value of the Readline variable @var{variable}.
For boolean variables, this string is either @samp{on} or @samp{off}.
@end deftypefun

@deftypefun void rl_variable_dumper (int readable)
Print the readline variable names and their current values
to @code{rl_outstream}.
If @var{readable} is non-zero, the list is formatted in such a way
that it can be made part of an @code{inputrc} file and re-read.
@end deftypefun

@deftypefun int rl_set_paren_blink_timeout (int u)
Set the time interval (in microseconds) that Readline waits when showing
a balancing character when @code{blink-matching-paren} has been enabled.
@end deftypefun

@deftypefun {char *} rl_get_termcap (const char *cap)
Retrieve the string value of the termcap capability @var{cap}.
Readline fetches the termcap entry for the current terminal name and
uses those capabilities to move around the screen line and perform other
terminal-specific operations, like erasing a line.  Readline does not
use all of a terminal's capabilities, and this function will return
values for only those capabilities Readline uses.
@end deftypefun

@node Alternate Interface
@subsection Alternate Interface

An alternate interface is available to plain @code{readline()}.  Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to @code{select()}
on various file descriptors.  To accomodate this need, readline can
also be invoked as a `callback' function from an event loop.  There
are functions available to make this easy.

@deftypefun 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 @var{prompt}.  Save the value of @var{lhandler} to
use as a function to call when a complete line of input has been entered.
The function takes the text of the line as an argument.
@end deftypefun

@deftypefun void rl_callback_read_char (void)
Whenever an application determines that keyboard input is available, it
should call @code{rl_callback_read_char()}, which will read the next
character from the current input source.
If that character completes the line, @code{rl_callback_read_char} will
invoke the @var{lhandler} function saved by @code{rl_callback_handler_install}
to process the line.
Before calling the @var{lhandler} function, the terminal settings are
reset to the values they had before calling
@code{rl_callback_handler_install}.
If the @var{lhandler} function returns,
the terminal settings are modified for Readline's use again.
@code{EOF} is  indicated by calling @var{lhandler} with a
@code{NULL} line.
@end deftypefun

@deftypefun void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line handler.
This may be called from within a callback as well as independently.
If the @var{lhandler} installed by @code{rl_callback_handler_install}
does not exit the program, either this function or the function referred
to by the value of @code{rl_deprep_term_function} should be called before
the program exits to reset the terminal settings.
@end deftypefun

@node A Readline Example
@subsection A Readline Example

Here is a function which changes lowercase characters to their uppercase
equivalents, and uppercase characters to lowercase.  If
this function was bound to @samp{M-c}, then typing @samp{M-c} would
change the case of the character under point.  Typing @samp{M-1 0 M-c}
would change the case of the following 10 characters, leaving the cursor on
the last character changed.

@example
/* Invert the case of the COUNT following characters. */
int
invert_case_line (count, key)
     int count, key;
@{
  register int start, end, i;

  start = rl_point;

  if (rl_point >= rl_end)
    return (0);

  if (count < 0)
    @{
      direction = -1;
      count = -count;
    @}
  else
    direction = 1;
      
  /* Find the end of the range to modify. */
  end = start + (count * direction);

  /* Force it to be within range. */
  if (end > rl_end)
    end = rl_end;
  else if (end < 0)
    end = 0;

  if (start == end)
    return (0);

  if (start > end)
    @{
      int temp = start;
      start = end;
      end = temp;
    @}

  /* Tell readline that we are modifying the line,
     so it will save the undo information. */
  rl_modifying (start, end);

  for (i = start; i != end; i++)
    @{
      if (_rl_uppercase_p (rl_line_buffer[i]))
        rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
      else if (_rl_lowercase_p (rl_line_buffer[i]))
        rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
    @}
  /* Move point to on top of the last character changed. */
  rl_point = (direction == 1) ? end - 1 : start;
  return (0);
@}
@end example

@node Readline Signal Handling
@section 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 (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
When one of these signals is received, the signal handler
will reset the terminal attributes to those that were in effect before
@code{readline()} was called, reset the signal handling to what it was