rltech.texi

linux中bash shell的源代码

way to stuff a single character into the input stream.
@end deftypevar

@deftypevar int rl_dispatching
Set to a non-zero value if a function is being called from a key binding;
zero otherwise.  Application functions can test this to discover whether
they were called directly or by Readline's dispatching mechanism.
@end deftypevar

@deftypevar int rl_erase_empty_line
Setting this to a non-zero value causes Readline to completely erase
the current line, including any prompt, any time a newline is typed as
the only character on an otherwise-empty line.  The cursor is moved to
the beginning of the newly-blank line.
@end deftypevar

@deftypevar {char *} rl_prompt
The prompt Readline uses.  This is set from the argument to
@code{readline()}, and should not be assigned to directly.
The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
be used to modify the prompt string after calling @code{readline()}.
@end deftypevar

@deftypevar int rl_already_prompted
If an application wishes to display the prompt itself, rather than have
Readline do it the first time @code{readline()} is called, it should set
this variable to a non-zero value after displaying the prompt.
The prompt must also be passed as the argument to @code{readline()} so
the redisplay functions can update the display properly.
The calling application is responsible for managing the value; Readline
never sets it.
@end deftypevar

@deftypevar {const char *} rl_library_version
The version number of this revision of the library.
@end deftypevar

@deftypevar int rl_readline_version
An integer encoding the current version of the library.  The encoding is
of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
number, and @var{mm} is the two-digit minor version number.
For example, for Readline-4.2, @code{rl_readline_version} would have the
value 0x0402.
@end deftypevar

@deftypevar {int} rl_gnu_readline_p
Always set to 1, denoting that this is @sc{gnu} readline rather than some
emulation.
@end deftypevar

@deftypevar {const char *} rl_terminal_name
The terminal type, used for initialization.  If not set by the application,
Readline sets this to the value of the @env{TERM} environment variable
the first time it is called.
@end deftypevar

@deftypevar {const char *} rl_readline_name
This variable is set to a unique name by each application using Readline.
The value allows conditional parsing of the inputrc file
(@pxref{Conditional Init Constructs}).
@end deftypevar

@deftypevar {FILE *} rl_instream
The stdio stream from which Readline reads input.
If @code{NULL}, Readline defaults to @var{stdin}.
@end deftypevar

@deftypevar {FILE *} rl_outstream
The stdio stream to which Readline performs output.
If @code{NULL}, Readline defaults to @var{stdout}.
@end deftypevar

@deftypevar int rl_prefer_env_winsize
If non-zero, Readline gives values found in the @env{LINES} and
@env{COLUMNS} environment variables greater precedence than values fetched
from the kernel when computing the screen dimensions.
@end deftypevar

@deftypevar {rl_command_func_t *} rl_last_func
The address of the last command function Readline executed.  May be used to
test whether or not a function is being executed twice in succession, for
example.
@end deftypevar

@deftypevar {rl_hook_func_t *} rl_startup_hook
If non-zero, this is the address of a function to call just
before @code{readline} prints the first prompt.
@end deftypevar

@deftypevar {rl_hook_func_t *} rl_pre_input_hook
If non-zero, this is the address of a function to call after
the first prompt has been printed and just before @code{readline}
starts reading input characters.
@end deftypevar

@deftypevar {rl_hook_func_t *} rl_event_hook
If non-zero, this is the address of a function to call periodically
when Readline is waiting for terminal input.
By default, this will be called at most ten times a second if there
is no keyboard input.
@end deftypevar

@deftypevar {rl_getc_func_t *} rl_getc_function
If non-zero, Readline will call indirectly through this pointer
to get a character from the input stream.  By default, it is set to
@code{rl_getc}, the default Readline character input function
(@pxref{Character Input}).
@end deftypevar

@deftypevar {rl_voidfunc_t *} rl_redisplay_function
If non-zero, Readline will call indirectly through this pointer
to update the display with the current contents of the editing buffer.
By default, it is set to @code{rl_redisplay}, the default Readline
redisplay function (@pxref{Redisplay}).
@end deftypevar

@deftypevar {rl_vintfunc_t *} rl_prep_term_function
If non-zero, Readline will call indirectly through this pointer
to initialize the terminal.  The function takes a single argument, an
@code{int} flag that says whether or not to use eight-bit characters.
By default, this is set to @code{rl_prep_terminal}
(@pxref{Terminal Management}).
@end deftypevar

@deftypevar {rl_voidfunc_t *} rl_deprep_term_function
If non-zero, Readline will call indirectly through this pointer
to reset the terminal.  This function should undo the effects of
@code{rl_prep_term_function}.
By default, this is set to @code{rl_deprep_terminal}
(@pxref{Terminal Management}).
@end deftypevar

@deftypevar {Keymap} rl_executing_keymap
This variable is set to the keymap (@pxref{Keymaps}) in which the
currently executing readline function was found.
@end deftypevar 

@deftypevar {Keymap} rl_binding_keymap
This variable is set to the keymap (@pxref{Keymaps}) in which the
last key binding occurred.
@end deftypevar 

@deftypevar {char *} rl_executing_macro
This variable is set to the text of any currently-executing macro.
@end deftypevar

@deftypevar {int} rl_readline_state
A variable with bit values that encapsulate the current Readline state.
A bit is set with the @code{RL_SETSTATE} macro, and unset with the
@code{RL_UNSETSTATE} macro.  Use the @code{RL_ISSTATE} macro to test
whether a particular state bit is set.  Current state bits include:

@table @code
@item RL_STATE_NONE
Readline has not yet been called, nor has it begun to intialize.
@item RL_STATE_INITIALIZING
Readline is initializing its internal data structures.
@item RL_STATE_INITIALIZED
Readline has completed its initialization.
@item RL_STATE_TERMPREPPED
Readline has modified the terminal modes to do its own input and redisplay.
@item RL_STATE_READCMD
Readline is reading a command from the keyboard.
@item RL_STATE_METANEXT
Readline is reading more input after reading the meta-prefix character.
@item RL_STATE_DISPATCHING
Readline is dispatching to a command.
@item RL_STATE_MOREINPUT
Readline is reading more input while executing an editing command.
@item RL_STATE_ISEARCH
Readline is performing an incremental history search.
@item RL_STATE_NSEARCH
Readline is performing a non-incremental history search.
@item RL_STATE_SEARCH
Readline is searching backward or forward through the history for a string.
@item RL_STATE_NUMERICARG
Readline is reading a numeric argument.
@item RL_STATE_MACROINPUT
Readline is currently getting its input from a previously-defined keyboard
macro.
@item RL_STATE_MACRODEF
Readline is currently reading characters defining a keyboard macro.
@item RL_STATE_OVERWRITE
Readline is in overwrite mode.
@item RL_STATE_COMPLETING
Readline is performing word completion.
@item RL_STATE_SIGHANDLER
Readline is currently executing the readline signal handler.
@item RL_STATE_UNDOING
Readline is performing an undo.
@item RL_STATE_DONE
Readline has read a key sequence bound to @code{accept-line}
and is about to return the line to the caller.
@end table

@end deftypevar

@deftypevar {int} rl_explicit_arg
Set to a non-zero value if an explicit numeric argument was specified by
the user.  Only valid in a bindable command function.
@end deftypevar

@deftypevar {int} rl_numeric_arg
Set to the value of any numeric argument explicitly specified by the user
before executing the current Readline function.  Only valid in a bindable
command function.
@end deftypevar

@deftypevar {int} rl_editing_mode
Set to a value denoting Readline's current editing mode.  A value of
@var{1} means Readline is currently in emacs mode; @var{0}
means that vi mode is active.
@end deftypevar


@node Readline Convenience Functions
@section Readline Convenience Functions

@menu
* Function Naming::	How to give a function you write a name.
* Keymaps::		Making keymaps.
* Binding Keys::	Changing Keymaps.
* Associating Function Names and Bindings::	Translate function names to
						key sequences.
* Allowing Undoing::	How to make your functions undoable.
* Redisplay::		Functions to control line display.
* Modifying Text::	Functions to modify @code{rl_line_buffer}.
* Character Input::	Functions to read keyboard input.
* Terminal Management::	Functions to manage terminal settings.
* Utility Functions::	Generally useful functions and hooks.
* Miscellaneous Functions::	Functions that don't fall into any category.
* Alternate Interface::	Using Readline in a `callback' fashion.
* A Readline Example::		An example Readline function.
@end menu

@node Function Naming
@subsection Naming a Function

The user can dynamically change the bindings of keys while using
Readline.  This is done by representing the function with a descriptive
name.  The user is able to type the descriptive name when referring to
the function.  Thus, in an init file, one might find

@example
Meta-Rubout:	backward-kill-word
@end example

This binds the keystroke @key{Meta-Rubout} to the function
@emph{descriptively} named @code{backward-kill-word}.  You, as the
programmer, should bind the functions you write to descriptive names as
well.  Readline provides a function for doing that:

@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
Add @var{name} to the list of named functions.  Make @var{function} be
the function that gets called.  If @var{key} is not -1, then bind it to
@var{function} using @code{rl_bind_key()}.
@end deftypefun

Using this function alone is sufficient for most applications.
It is the recommended way to add a few functions to the default
functions that Readline has built in.
If you need to do something other than adding a function to Readline,
you may need to use the underlying functions described below.

@node Keymaps
@subsection Selecting a Keymap

Key bindings take place on a @dfn{keymap}.  The keymap is the
association between the keys that the user types and the functions that
get run.  You can make your own keymaps, copy existing keymaps, and tell
Readline which keymap to use.

@deftypefun Keymap rl_make_bare_keymap (void)
Returns a new, empty keymap.  The space for the keymap is allocated with
@code{malloc()}; the caller should free it by calling
@code{rl_discard_keymap()} when done.
@end deftypefun

@deftypefun Keymap rl_copy_keymap (Keymap map)
Return a new keymap which is a copy of @var{map}.
@end deftypefun

@deftypefun Keymap rl_make_keymap (void)
Return a new keymap with the printing characters bound to rl_insert,
the lowercase Meta characters bound to run their equivalents, and
the Meta digits bound to produce numeric arguments.
@end deftypefun

@deftypefun void rl_discard_keymap (Keymap keymap)
Free the storage associated with @var{keymap}.
@end deftypefun

Readline has several internal keymaps.  These functions allow you to
change which keymap is active.

@deftypefun Keymap rl_get_keymap (void)
Returns the currently active keymap.
@end deftypefun

@deftypefun void rl_set_keymap (Keymap keymap)
Makes @var{keymap} the currently active keymap.
@end deftypefun

@deftypefun Keymap rl_get_keymap_by_name (const char *name)
Return the keymap matching @var{name}.  @var{name} is one which would
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun

@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
Return the name matching @var{keymap}.  @var{name} is one which would
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun

@node Binding Keys
@subsection Binding Keys

Key sequences are associate with functions through the keymap.
Readline has several internal keymaps: @code{emacs_standard_keymap},
@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
@code{emacs_standard_keymap} is the default, and the examples in
this manual assume that.

Since @code{readline()} installs a set of default key bindings the first
time it is called, there is always the danger that a custom binding
installed before the first call to @code{readline()} will be overridden.
An alternate mechanism is to install custom key bindings in an
initialization function assigned to the @code{rl_startup_hook} variable
(@pxref{Readline Variables}).