--- embedaddon/readline/doc/rltech.texi	2014/07/30 08:16:45	1.1.1.1
+++ embedaddon/readline/doc/rltech.texi	2021/03/17 01:01:01	1.1.1.2
@@ -7,7 +7,7 @@ This document describes the GNU Readline Library, a ut
 in the consistency of user interface across discrete programs that need
 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
 this manual provided the copyright notice and this permission notice
@@ -90,6 +90,12 @@ If @code{readline} encounters an @code{EOF} while read
 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.
 
+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
 @key{C-p} for example), you must call @code{add_history()} to save the
 line away in a @dfn{history} list of such lines.
@@ -282,7 +288,7 @@ At the very least, it should be aware that it can be p
 negative argument.
 
 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
 command functions.
 
@@ -688,6 +694,11 @@ Free all storage associated with @var{keymap}.  This c
 @code{rl_discard_keymap} to free subordindate keymaps and macros.
 @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
 change which keymap is active.
 
@@ -709,6 +720,24 @@ Return the name matching @var{keymap}.  @var{name} is 
 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
 @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
 @subsection Binding Keys
 
@@ -835,8 +864,18 @@ Return the function invoked by @var{keyseq} in keymap 
 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
 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
 
+@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)
 Return an array of strings representing the key sequences used to
 invoke @var{function} in the current keymap.
@@ -963,6 +1002,10 @@ redisplay.
 It should be used after setting @var{rl_already_prompted}.
 @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)
 Reset the display state to a clean state and redisplay the current line
 starting on a new line.
@@ -1020,7 +1063,7 @@ It returns the number of visible characters on the las
 Applications may indicate that the prompt contains characters that take
 up no physical screen space when displayed by bracketing a sequence of
 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.
 @end deftypefun
 
@@ -1136,6 +1179,14 @@ that the terminal editing characters are bound to @cod
 The bindings are performed in @var{kmap}.
 @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)
 Reinitialize Readline's idea of the terminal settings using
 @var{terminal_name} as the terminal type (e.g., @code{vt100}).
@@ -1291,6 +1342,29 @@ This differs from @code{clear_history} because it free
 Readline saves in the history list.
 @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
 @subsection Alternate Interface
 
@@ -1307,6 +1381,8 @@ 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
 entered.
 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
 
 @deftypefun void rl_callback_read_char (void)
@@ -1326,9 +1402,17 @@ the terminal settings are modified for Readline's use 
 @code{NULL} line.
 @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)
 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}
 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
@@ -1413,12 +1497,16 @@ It understands the EOF character or "exit" to exit the
 @example
 /* Standard include files. stdio.h is required. */
 #include <stdlib.h>
+#include <string.h>
 #include <unistd.h>
+#include <locale.h>
 
 /* Used for select(2) */
 #include <sys/types.h>
 #include <sys/select.h>
 
+#include <signal.h>
+
 #include <stdio.h>
 
 /* Standard readline include files. */
@@ -1426,10 +1514,20 @@ It understands the EOF character or "exit" to exit the
 #include <readline/history.h>
 
 static void cb_linehandler (char *);
+static void sighandler (int);
 
 int running;
+int sigwinch_received;
 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
    seen, or EOF character read.  This sets a flag and returns; it could
    also call exit(3). */
@@ -1464,6 +1562,13 @@ main (int c, char **v)
   fd_set fds;
   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. */
   rl_callback_handler_install (prompt, cb_linehandler);
 
@@ -1478,12 +1583,19 @@ main (int c, char **v)
       FD_SET (fileno (rl_instream), &fds);    
 
       r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
-      if (r < 0)
+      if (r < 0 && errno != EINTR)
         @{
           perror ("rltest: select");
           rl_callback_handler_remove ();
           break;
         @}
+      if (sigwinch_received)
+	@{
+	  rl_resize_terminal ();
+	  sigwinch_received = 0;
+	@}
+      if (r < 0)
+	continue;     
 
       if (FD_ISSET (fileno (rl_instream), &fds))
         rl_callback_read_char ();
@@ -1532,8 +1644,31 @@ resetting the terminal to its original state.  If the 
 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}
 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
 control whether or not it will catch certain signals and act on them
 when they are received.  It is important that applications change the
@@ -1555,6 +1690,15 @@ Readline will install a signal handler for @code{SIGWI
 The default value of @code{rl_catch_sigwinch} is 1.
 @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
 If this variable is set to a non-zero value,
 and Readline is handling @code{SIGWINCH}, Readline will modify the
@@ -1570,6 +1714,11 @@ for example), 
 Readline provides convenience functions to do the necessary terminal
 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)
 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
@@ -1592,10 +1741,23 @@ handlers, depending on the values of @code{rl_catch_si
 @code{rl_catch_sigwinch}.
 @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
 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}
-is received.
+Readline to update its idea of the terminal size when it receives
+a @code{SIGWINCH}.
 
 @deftypefun void rl_echo_signal_char (int sig)
 If an application wishes to install its own signal handlers, but still
@@ -1612,11 +1774,14 @@ Update Readline's internal screen size by reading valu
 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
 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
 
 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
-size may be queried.
+is still interested in the screen dimensions, it may query Readline's idea
+of the screen size.
 
 @deftypefun void rl_get_screen_size (int *rows, int *cols)
 Return Readline's idea of the terminal's size in the
@@ -1900,7 +2065,7 @@ remove any quote characters from the directory name, b
 be passed directly to @code{opendir()}.
 
 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.
 @end deftypevar
 
@@ -1912,7 +2077,7 @@ is passed to @code{stat()} to determine the file's typ
 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 function modfies its directory argument.
+the function modifies its directory argument.
 The function should not modify the directory argument if it returns 0.
 @end deftypevar
 
@@ -1942,8 +2107,8 @@ where @var{matches} is the array of matching strings,
 @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.
 Readline provides a convenience function, @code{rl_display_match_list},
-that takes care of doing the display to Readline's output stream.  That
-function may be called from this hook.
+that takes care of doing the display to Readline's output stream.
+You may call that function from this hook.
 @end deftypevar
 
 @deftypevar {const char *} rl_basic_word_break_characters
@@ -2007,6 +2172,8 @@ character (@samp{\0}) prevents anything being appended
 This can be changed in application-specific completion functions to
 provide the ``most sensible word separator character'' according to
 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
 
 @deftypevar int rl_completion_suppress_append
@@ -2504,7 +2671,7 @@ com_help (arg)
 
   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++)
         @{