embedaddon/readline/doc/rltech.texi - diff

Return to rltech.texi CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc

Diff for /embedaddon/readline/doc/rltech.texi between versions 1.1.1.1 and 1.1.1.2

version 1.1.1.1, 2014/07/30 08:16:45	version 1.1.1.2, 2021/03/17 01:01:01
Line 7 This document describes the GNU Readline Library, a ut	Line 7 This document describes the GNU Readline Library, a ut
in the consistency of user interface across discrete programs that need	in the consistency of user interface across discrete programs that need
to provide a command line interface.	to provide a command line interface.

Copyright (C) 1988--2014 Free Software Foundation, Inc.	Copyright (C) 1988--2020 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of	Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice	this manual provided the copyright notice and this permission notice
Line 90 If @code{readline} encounters an @code{EOF} while read	Line 90 If @code{readline} encounters an @code{EOF} while read
line is empty at that point, then @code{(char *)NULL} is returned.	line is empty at that point, then @code{(char *)NULL} is returned.
Otherwise, the line is ended just as if a newline had been typed.	Otherwise, the line is ended just as if a newline had been typed.

	Readline performs some expansion on the @var{prompt} before it is
	displayed on the screen. See the description of @code{rl_expand_prompt}
	(@pxref{Redisplay}) for additional details, especially if @var{prompt}
	will contain characters that do not consume physical screen space when
	displayed.

If you want the user to be able to get at the line later, (with	If you want the user to be able to get at the line later, (with
@key{C-p} for example), you must call @code{add_history()} to save the	@key{C-p} for example), you must call @code{add_history()} to save the
line away in a @dfn{history} list of such lines.	line away in a @dfn{history} list of such lines.
Line 282 At the very least, it should be aware that it can be p	Line 288 At the very least, it should be aware that it can be p
negative argument.	negative argument.

A command function should return 0 if its action completes successfully,	A command function should return 0 if its action completes successfully,
and a non-zero value if some error occurs.	and a value greater than zero if some error occurs.
This is the convention obeyed by all of the builtin Readline bindable	This is the convention obeyed by all of the builtin Readline bindable
command functions.	command functions.

Line 688 Free all storage associated with @var{keymap}. This c	Line 694 Free all storage associated with @var{keymap}. This c
@code{rl_discard_keymap} to free subordindate keymaps and macros.	@code{rl_discard_keymap} to free subordindate keymaps and macros.
@end deftypefun	@end deftypefun

	@deftypefun int rl_empty_keymap (Keymap keymap)
	Return non-zero if there are no keys bound to functions in @var{keymap};
	zero if there are any keys bound.
	@end deftypefun

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

Line 709 Return the name matching @var{keymap}. @var{name} is	Line 720 Return the name matching @var{keymap}. @var{name} is
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).	be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun	@end deftypefun

	@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap)
	Set the name of @var{keymap}. This name will then be "registered" and
	available for use in a @code{set keymap} inputrc directive
	@pxref{Readline Init File}).
	The @var{name} may not be one of Readline's builtin keymap names;
	you may not add a different name for one of Readline's builtin keymaps.
	You may replace the name associated with a given keymap by calling this
	function more than once with the same @var{keymap} argument.
	You may associate a registered @var{name} with a new keymap by calling this
	function more than once with the same @var{name} argument.
	There is no way to remove a named keymap once the name has been
	registered.
	Readline will make a copy of @var{name}.
	The return value is greater than zero unless @var{name} is one of
	Readline's builtin keymap names or @var{keymap} is one of Readline's
	builtin keymaps.
	@end deftypefun

@node Binding Keys	@node Binding Keys
@subsection Binding Keys	@subsection Binding Keys

Line 835 Return the function invoked by @var{keyseq} in keymap	Line 864 Return the function invoked by @var{keyseq} in keymap
If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is	If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
not @code{NULL}, the type of the object is returned in the @code{int} variable	not @code{NULL}, the type of the object is returned in the @code{int} variable
it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).	it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
	It takes a "translated" key sequence and should not be used if the key sequence
	can include NUL.
@end deftypefun	@end deftypefun

	@deftypefun {rl_command_func_t } rl_function_of_keyseq_len (const char keyseq, size_t len, Keymap map, int *type)
	Return the function invoked by @var{keyseq} of length @var{len}
	in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the
	addition of the @var{len} parameter.
	It takes a "translated" key sequence and should be used if the key sequence
	can include NUL.
	@end deftypefun

@deftypefun {char *} rl_invoking_keyseqs (rl_command_func_t function)	@deftypefun {char *} rl_invoking_keyseqs (rl_command_func_t function)
Return an array of strings representing the key sequences used to	Return an array of strings representing the key sequences used to
invoke @var{function} in the current keymap.	invoke @var{function} in the current keymap.
Line 963 redisplay.	Line 1002 redisplay.
It should be used after setting @var{rl_already_prompted}.	It should be used after setting @var{rl_already_prompted}.
@end deftypefun	@end deftypefun

	@deftypefun int rl_clear_visible_line (void)
	Clear the screen lines corresponding to the current line's contents.
	@end deftypefun

@deftypefun int rl_reset_line_state (void)	@deftypefun int rl_reset_line_state (void)
Reset the display state to a clean state and redisplay the current line	Reset the display state to a clean state and redisplay the current line
starting on a new line.	starting on a new line.
Line 1020 It returns the number of visible characters on the las	Line 1063 It returns the number of visible characters on the las
Applications may indicate that the prompt contains characters that take	Applications may indicate that the prompt contains characters that take
up no physical screen space when displayed by bracketing a sequence of	up no physical screen space when displayed by bracketing a sequence of
such characters with the special markers @code{RL_PROMPT_START_IGNORE}	such characters with the special markers @code{RL_PROMPT_START_IGNORE}
and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}. This may	and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}). This may
be used to embed terminal-specific escape sequences in prompts.	be used to embed terminal-specific escape sequences in prompts.
@end deftypefun	@end deftypefun

Line 1136 that the terminal editing characters are bound to @cod	Line 1179 that the terminal editing characters are bound to @cod
The bindings are performed in @var{kmap}.	The bindings are performed in @var{kmap}.
@end deftypefun	@end deftypefun

	@deftypefun int rl_tty_set_echoing (int value)
	Set Readline's idea of whether or not it is echoing output to its output
	stream (@var{rl_outstream}). If @var{value} is 0, Readline does not display
	output to @var{rl_outstream}; any other value enables output. The initial
	value is set when Readline initializes the terminal settings.
	This function returns the previous value.
	@end deftypefun

@deftypefun int rl_reset_terminal (const char *terminal_name)	@deftypefun int rl_reset_terminal (const char *terminal_name)
Reinitialize Readline's idea of the terminal settings using	Reinitialize Readline's idea of the terminal settings using
@var{terminal_name} as the terminal type (e.g., @code{vt100}).	@var{terminal_name} as the terminal type (e.g., @code{vt100}).
Line 1291 This differs from @code{clear_history} because it free	Line 1342 This differs from @code{clear_history} because it free
Readline saves in the history list.	Readline saves in the history list.
@end deftypefun	@end deftypefun

	@deftypefun {void} rl_activate_mark (void)
	Enable an @emph{active} mark.
	When this is enabled, the text between point and mark (the @var{region}) is
	displayed in the terminal's standout mode (a @var{face}).
	This is called by various readline functions that set the mark and insert
	text, and is available for applications to call.
	@end deftypefun

	@deftypefun {void} rl_deactivate_mark (void)
	Turn off the active mark.
	@end deftypefun

	@deftypefun {void} rl_keep_mark_active (void)
	Indicate that the mark should remain active when the current readline function
	completes and after redisplay occurs.
	In most cases, the mark remains active for only the duration of a single
	bindable readline function.
	@end deftypefun

	@deftypefun {int} rl_mark_active_p (void)
	Return a non-zero value if the mark is currently active; zero otherwise.
	@end deftypefun

@node Alternate Interface	@node Alternate Interface
@subsection Alternate Interface	@subsection Alternate Interface

Line 1307 expanded value of @var{prompt}. Save the value of @va	Line 1381 expanded value of @var{prompt}. Save the value of @va
use as a handler function to call when a complete line of input has been	use as a handler function to call when a complete line of input has been
entered.	entered.
The handler function receives the text of the line as an argument.	The handler function receives the text of the line as an argument.
	As with @code{readline()}, the handler function should @code{free} the
	line when it it finished with it.
@end deftypefun	@end deftypefun

@deftypefun void rl_callback_read_char (void)	@deftypefun void rl_callback_read_char (void)
Line 1326 the terminal settings are modified for Readline's use	Line 1402 the terminal settings are modified for Readline's use
@code{NULL} line.	@code{NULL} line.
@end deftypefun	@end deftypefun

	@deftypefun 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.
	@end deftypefun

@deftypefun void rl_callback_handler_remove (void)	@deftypefun void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line handler.	Restore the terminal to its initial state and remove the line handler.
This may be called from within a callback as well as independently.	You may call this function from within a callback as well as independently.
If the @var{lhandler} installed by @code{rl_callback_handler_install}	If the @var{lhandler} installed by @code{rl_callback_handler_install}
does not exit the program, either this function or the function referred	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	to by the value of @code{rl_deprep_term_function} should be called before
Line 1413 It understands the EOF character or "exit" to exit the	Line 1497 It understands the EOF character or "exit" to exit the
@example	@example
/* Standard include files. stdio.h is required. */	/* Standard include files. stdio.h is required. */
#include <stdlib.h>	#include <stdlib.h>
	#include <string.h>
#include <unistd.h>	#include <unistd.h>
	#include <locale.h>

/* Used for select(2) */	/* Used for select(2) */
#include <sys/types.h>	#include <sys/types.h>
#include <sys/select.h>	#include <sys/select.h>

	#include <signal.h>

#include <stdio.h>	#include <stdio.h>

/* Standard readline include files. */	/* Standard readline include files. */
Line 1426 It understands the EOF character or "exit" to exit the	Line 1514 It understands the EOF character or "exit" to exit the
#include <readline/history.h>	#include <readline/history.h>

static void cb_linehandler (char *);	static void cb_linehandler (char *);
	static void sighandler (int);

int running;	int running;
	int sigwinch_received;
const char *prompt = "rltest$ ";	const char *prompt = "rltest$ ";

	/* Handle SIGWINCH and window size changes when readline is not active and
	reading a character. */
	static void
	sighandler (int sig)
	@{
	sigwinch_received = 1;
	@}

/* Callback function called for each line when accept-line executed, EOF	/* Callback function called for each line when accept-line executed, EOF
seen, or EOF character read. This sets a flag and returns; it could	seen, or EOF character read. This sets a flag and returns; it could
also call exit(3). */	also call exit(3). */
Line 1464 main (int c, char **v)	Line 1562 main (int c, char **v)
fd_set fds;	fd_set fds;
int r;	int r;

	/* Set the default locale values according to environment variables. */
	setlocale (LC_ALL, "");

	/* Handle window size changes when readline is not active and reading
	characters. */
	signal (SIGWINCH, sighandler);

/* Install the line handler. */	/* Install the line handler. */
rl_callback_handler_install (prompt, cb_linehandler);	rl_callback_handler_install (prompt, cb_linehandler);

Line 1478 main (int c, char **v)	Line 1583 main (int c, char **v)
FD_SET (fileno (rl_instream), &fds);	FD_SET (fileno (rl_instream), &fds);

r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);	r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
if (r < 0)	if (r < 0 && errno != EINTR)
@{	@{
perror ("rltest: select");	perror ("rltest: select");
rl_callback_handler_remove ();	rl_callback_handler_remove ();
break;	break;
@}	@}
	if (sigwinch_received)
	@{
	rl_resize_terminal ();
	sigwinch_received = 0;
	@}
	if (r < 0)
	continue;

if (FD_ISSET (fileno (rl_instream), &fds))	if (FD_ISSET (fileno (rl_instream), &fds))
rl_callback_read_char ();	rl_callback_read_char ();
Line 1532 resetting the terminal to its original state. If the	Line 1644 resetting the terminal to its original state. If the
handler does more than update its idea of the terminal size and return (for	handler does more than update its idea of the terminal size and return (for
example, a @code{longjmp} back to a main processing loop), it @emph{must}	example, a @code{longjmp} back to a main processing loop), it @emph{must}
call @code{rl_cleanup_after_signal()} (described below), to restore the	call @code{rl_cleanup_after_signal()} (described below), to restore the
terminal state.	terminal state.

	When an application is using the callback interface
	(@pxref{Alternate Interface}), Readline installs signal handlers only for
	the duration of the call to @code{rl_callback_read_char}. Applications
	using the callback interface should be prepared to clean up Readline's
	state if they wish to handle the signal before the line handler completes
	and restores the terminal state.

	If an application using the callback interface wishes to have Readline
	install its signal handlers at the time the application calls
	@code{rl_callback_handler_install} and remove them only when a complete
	line of input has been read, it should set the
	@code{rl_persistent_signal_handlers} variable to a non-zero value.
	This allows an application to defer all of the handling of the signals
	Readline catches to Readline.
	Applications should use this variable with care; it can result in Readline
	catching signals and not acting on them (or allowing the application to react
	to them) until the application calls @code{rl_callback_read_char}. This
	can result in an application becoming less responsive to keyboard signals
	like SIGINT.
	If an application does not want or need to perform any signal handling, or
	does not need to do any processing between calls to @code{rl_callback_read_char},
	setting this variable may be desirable.

Readline provides two variables that allow application writers to	Readline provides two variables that allow application writers to
control whether or not it will catch certain signals and act on them	control whether or not it will catch certain signals and act on them
when they are received. It is important that applications change the	when they are received. It is important that applications change the
Line 1555 Readline will install a signal handler for @code{SIGWI	Line 1690 Readline will install a signal handler for @code{SIGWI
The default value of @code{rl_catch_sigwinch} is 1.	The default value of @code{rl_catch_sigwinch} is 1.
@end deftypevar	@end deftypevar

	@deftypevar int rl_persistent_signal_handlers
	If an application using the callback interface wishes Readline's signal
	handlers to be installed and active during the set of calls to
	@code{rl_callback_read_char} that constitutes an entire single line,
	it should set this variable to a non-zero value.

	The default value of @code{rl_persistent_signal_handlers} is 0.
	@end deftypevar

@deftypevar int rl_change_environment	@deftypevar int rl_change_environment
If this variable is set to a non-zero value,	If this variable is set to a non-zero value,
and Readline is handling @code{SIGWINCH}, Readline will modify the	and Readline is handling @code{SIGWINCH}, Readline will modify the
Line 1570 for example),	Line 1714 for example),
Readline provides convenience functions to do the necessary terminal	Readline provides convenience functions to do the necessary terminal
and internal state cleanup upon receipt of a signal.	and internal state cleanup upon receipt of a signal.

	@deftypefun int rl_pending_signal (void)
	Return the signal number of the most recent signal Readline received but
	has not yet handled, or 0 if there is no pending signal.
	@end deftypefun

@deftypefun void rl_cleanup_after_signal (void)	@deftypefun void rl_cleanup_after_signal (void)
This function will reset the state of the terminal to what it was before	This function will reset the state of the terminal to what it was before
@code{readline()} was called, and remove the Readline signal handlers for	@code{readline()} was called, and remove the Readline signal handlers for
Line 1592 handlers, depending on the values of @code{rl_catch_si	Line 1741 handlers, depending on the values of @code{rl_catch_si
@code{rl_catch_sigwinch}.	@code{rl_catch_sigwinch}.
@end deftypefun	@end deftypefun

	If an application wants to force Readline to handle any signals that
	have arrived while it has been executing, @code{rl_check_signals()}
	will call Readline's internal signal handler if there are any pending
	signals. This is primarily intended for those applications that use
	a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish
	to handle signals received while waiting for input.

	@deftypefun void rl_check_signals (void)
	If there are any pending signals, call Readline's internal signal handling
	functions to process them. @code{rl_pending_signal()} can be used independently
	to determine whether or not there are any pending signals.
	@end deftypefun

If an application does not wish Readline to catch @code{SIGWINCH}, it may	If an application does not wish Readline to catch @code{SIGWINCH}, it may
call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force	call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
Readline to update its idea of the terminal size when a @code{SIGWINCH}	Readline to update its idea of the terminal size when it receives
is received.	a @code{SIGWINCH}.

@deftypefun void rl_echo_signal_char (int sig)	@deftypefun void rl_echo_signal_char (int sig)
If an application wishes to install its own signal handlers, but still	If an application wishes to install its own signal handlers, but still
Line 1612 Update Readline's internal screen size by reading valu	Line 1774 Update Readline's internal screen size by reading valu
Set Readline's idea of the terminal size to @var{rows} rows and	Set Readline's idea of the terminal size to @var{rows} rows and
@var{cols} columns. If either @var{rows} or @var{columns} is less than	@var{cols} columns. If either @var{rows} or @var{columns} is less than
or equal to 0, Readline's idea of that terminal dimension is unchanged.	or equal to 0, Readline's idea of that terminal dimension is unchanged.
	This is intended to tell Readline the physical dimensions of the terminal,
	and is used internally to calculate the maximum number of characters that
	may appear on a single line and on the screen.
@end deftypefun	@end deftypefun

If an application does not want to install a @code{SIGWINCH} handler, but	If an application does not want to install a @code{SIGWINCH} handler, but
is still interested in the screen dimensions, Readline's idea of the screen	is still interested in the screen dimensions, it may query Readline's idea
size may be queried.	of the screen size.

@deftypefun void rl_get_screen_size (int rows, int cols)	@deftypefun void rl_get_screen_size (int rows, int cols)
Return Readline's idea of the terminal's size in the	Return Readline's idea of the terminal's size in the
Line 1900 remove any quote characters from the directory name, b	Line 2065 remove any quote characters from the directory name, b
be passed directly to @code{opendir()}.	be passed directly to @code{opendir()}.

The directory rewrite hook returns an integer that should be non-zero if	The directory rewrite hook returns an integer that should be non-zero if
the function modfies its directory argument.	the function modifies its directory argument.
The function should not modify the directory argument if it returns 0.	The function should not modify the directory argument if it returns 0.
@end deftypevar	@end deftypevar

Line 1912 is passed to @code{stat()} to determine the file's typ	Line 2077 is passed to @code{stat()} to determine the file's typ
This function does not need to remove quote characters from the filename.	This function does not need to remove quote characters from the filename.

The stat hook returns an integer that should be non-zero if	The stat hook returns an integer that should be non-zero if
the function modfies its directory argument.	the function modifies its directory argument.
The function should not modify the directory argument if it returns 0.	The function should not modify the directory argument if it returns 0.
@end deftypevar	@end deftypevar

Line 1942 where @var{matches} is the array of matching strings,	Line 2107 where @var{matches} is the array of matching strings,
@var{num_matches} is the number of strings in that array, and	@var{num_matches} is the number of strings in that array, and
@var{max_length} is the length of the longest string in that array.	@var{max_length} is the length of the longest string in that array.
Readline provides a convenience function, @code{rl_display_match_list},	Readline provides a convenience function, @code{rl_display_match_list},
that takes care of doing the display to Readline's output stream. That	that takes care of doing the display to Readline's output stream.
function may be called from this hook.	You may call that function from this hook.
@end deftypevar	@end deftypevar

@deftypevar {const char *} rl_basic_word_break_characters	@deftypevar {const char *} rl_basic_word_break_characters
Line 2007 character (@samp{\0}) prevents anything being appended	Line 2172 character (@samp{\0}) prevents anything being appended
This can be changed in application-specific completion functions to	This can be changed in application-specific completion functions to
provide the ``most sensible word separator character'' according to	provide the ``most sensible word separator character'' according to
an application-specific command line syntax specification.	an application-specific command line syntax specification.
	It is set to the default before any application-specific completion function
	is called, and may only be changed within such a function.
@end deftypevar	@end deftypevar

@deftypevar int rl_completion_suppress_append	@deftypevar int rl_completion_suppress_append
Line 2504 com_help (arg)	Line 2671 com_help (arg)

if (!printed)	if (!printed)
@{	@{
printf ("No commands match `%s'. Possibilties are:\n", arg);	printf ("No commands match `%s'. Possibilities are:\n", arg);

for (i = 0; commands[i].name; i++)	for (i = 0; commands[i].name; i++)
@{	@{

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>

Removed from v.1.1.1.1
changed lines
	Added in v.1.1.1.2