diff options
Diffstat (limited to 'bin/catsh/libedit/editline.3')
| -rw-r--r-- | bin/catsh/libedit/editline.3 | 1013 |
1 files changed, 0 insertions, 1013 deletions
diff --git a/bin/catsh/libedit/editline.3 b/bin/catsh/libedit/editline.3 deleted file mode 100644 index a27e24ce..00000000 --- a/bin/catsh/libedit/editline.3 +++ /dev/null @@ -1,1013 +0,0 @@ -.\" $NetBSD: editline.3,v 1.93.4.1 2017/07/23 14:41:26 snj Exp $ -.\" -.\" Copyright (c) 1997-2014 The NetBSD Foundation, Inc. -.\" All rights reserved. -.\" -.\" This file was contributed to The NetBSD Foundation by Luke Mewburn. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS -.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS -.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -.\" POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd June 27, 2017 -.Dt EDITLINE 3 -.Os -.Sh NAME -.Nm editline , -.Nm el_init , -.Nm el_init_fd , -.Nm el_end , -.Nm el_reset , -.Nm el_gets , -.Nm el_wgets , -.Nm el_getc , -.Nm el_wgetc , -.Nm el_push , -.Nm el_wpush , -.Nm el_parse , -.Nm el_wparse , -.Nm el_set , -.Nm el_wset , -.Nm el_get , -.Nm el_wget , -.Nm el_source , -.Nm el_resize , -.Nm el_cursor , -.Nm el_line , -.Nm el_wline , -.Nm el_insertstr , -.Nm el_winsertstr , -.Nm el_deletestr , -.Nm el_wdeletestr , -.Nm history_init , -.Nm history_winit , -.Nm history_end , -.Nm history_wend , -.Nm history , -.Nm history_w , -.Nm tok_init , -.Nm tok_winit , -.Nm tok_end , -.Nm tok_wend , -.Nm tok_reset , -.Nm tok_wreset , -.Nm tok_line , -.Nm tok_wline , -.Nm tok_str , -.Nm tok_wstr -.Nd line editor, history and tokenization functions -.Sh LIBRARY -.Lb libedit -.Sh SYNOPSIS -.In histedit.h -.Ft EditLine * -.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" -.Ft EditLine * -.Fn el_init_fd "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" "int fdin" "int fdout" "int fderr" -.Ft void -.Fn el_end "EditLine *e" -.Ft void -.Fn el_reset "EditLine *e" -.Ft const char * -.Fn el_gets "EditLine *e" "int *count" -.Ft const wchar_t * -.Fn el_wgets "EditLine *e" "int *count" -.Ft int -.Fn el_getc "EditLine *e" "char *ch" -.Ft int -.Fn el_wgetc "EditLine *e" "wchar_t *wc" -.Ft void -.Fn el_push "EditLine *e" "const char *mbs" -.Ft void -.Fn el_wpush "EditLine *e" "const wchar_t *wcs" -.Ft int -.Fn el_parse "EditLine *e" "int argc" "const char *argv[]" -.Ft int -.Fn el_wparse "EditLine *e" "int argc" "const wchar_t *argv[]" -.Ft int -.Fn el_set "EditLine *e" "int op" "..." -.Ft int -.Fn el_wset "EditLine *e" "int op" "..." -.Ft int -.Fn el_get "EditLine *e" "int op" "..." -.Ft int -.Fn el_wget "EditLine *e" "int op" "..." -.Ft int -.Fn el_source "EditLine *e" "const char *file" -.Ft void -.Fn el_resize "EditLine *e" -.Ft int -.Fn el_cursor "EditLine *e" "int count" -.Ft const LineInfo * -.Fn el_line "EditLine *e" -.Ft const LineInfoW * -.Fn el_wline "EditLine *e" -.Ft int -.Fn el_insertstr "EditLine *e" "const char *str" -.Ft int -.Fn el_winsertstr "EditLine *e" "const wchar_t *str" -.Ft void -.Fn el_deletestr "EditLine *e" "int count" -.Ft void -.Fn el_wdeletestr "EditLine *e" "int count" -.Ft History * -.Fn history_init void -.Ft HistoryW * -.Fn history_winit void -.Ft void -.Fn history_end "History *h" -.Ft void -.Fn history_wend "HistoryW *h" -.Ft int -.Fn history "History *h" "HistEvent *ev" "int op" "..." -.Ft int -.Fn history_w "HistoryW *h" "HistEventW *ev" "int op" "..." -.Ft Tokenizer * -.Fn tok_init "const char *IFS" -.Ft TokenizerW * -.Fn tok_winit "const wchar_t *IFS" -.Ft void -.Fn tok_end "Tokenizer *t" -.Ft void -.Fn tok_wend "TokenizerW *t" -.Ft void -.Fn tok_reset "Tokenizer *t" -.Ft void -.Fn tok_wreset "TokenizerW *t" -.Ft int -.Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro" -.Ft int -.Fn tok_wline "TokenizerW *t" "const LineInfoW *li" "int *argc" "const wchar_t **argv[]" "int *cursorc" "int *cursoro" -.Ft int -.Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]" -.Ft int -.Fn tok_wstr "TokenizerW *t" "const wchar_t *str" "int *argc" "const wchar_t **argv[]" -.Sh DESCRIPTION -The -.Nm -library provides generic line editing, history and tokenization functions, -similar to those found in -.Xr sh 1 . -.Pp -These functions are available in the -.Nm libedit -library (which needs the -.Nm libtermcap -library). -Programs should be linked with -.Fl ledit ltermcap . -.Pp -The -.Nm -library respects the -.Ev LC_CTYPE -locale set by the application program and never uses -.Xr setlocale 3 -to change the locale. -The only locales supported are UTF-8 and the default C or POSIX locale. -If any other locale is set, behaviour is undefined. -.Sh LINE EDITING FUNCTIONS -The line editing functions use a common data structure, -.Fa EditLine , -which is created by -.Fn el_init -or -.Fn el_init_fd -and freed by -.Fn el_end . -.Pp -The wide-character functions behave the same way as their narrow -counterparts. -.Pp -The following functions are available: -.Bl -tag -width 4n -.It Fn el_init -Initialize the line editor, and return a data structure -to be used by all other line editing functions, or -.Dv NULL -on failure. -.Fa prog -is the name of the invoking program, used when reading the -.Xr editrc 5 -file to determine which settings to use. -.Fa fin , -.Fa fout -and -.Fa ferr -are the input, output, and error streams (respectively) to use. -In this documentation, references to -.Dq the tty -are actually to this input/output stream combination. -.It Fn el_init_fd -Like -.Fn el_init -but allows specifying file descriptors for the -.Xr stdio 3 -corresponding streams, in case those were created with -.Xr funopen 3 . -.It Fn el_end -Clean up and finish with -.Fa e , -assumed to have been created with -.Fn el_init -or -.Fn el_init_fd . -.It Fn el_reset -Reset the tty and the parser. -This should be called after an error which may have upset the tty's -state. -.It Fn el_gets -Read a line from the tty. -.Fa count -is modified to contain the number of characters read. -Returns the line read if successful, or -.Dv NULL -if no characters were read or if an error occurred. -If an error occurred, -.Fa count -is set to \-1 and -.Dv errno -contains the error code that caused it. -The return value may not remain valid across calls to -.Fn el_gets -and must be copied if the data is to be retained. -.It Fn el_wgetc -Read a wide character from the tty, respecting the current locale, -or from the input queue described in -.Xr editline 7 -if that is not empty, and store it in -.Fa wc . -If an invalid or incomplete character is found, it is discarded, -.Va errno -is set to -.Er EILSEQ , -and the next character is read and stored in -.Fa wc . -Returns 1 if a valid character was read, 0 on end of file, or \-1 on -.Xr read 2 -failure. -In the latter case, -.Va errno -is set to indicate the error. -.It Fn el_getc -Read a wide character as described for -.Fn el_wgetc -and return 0 on end of file or \-1 on failure. -If the wide character can be represented as a single-byte character, -convert it with -.Xr wctob 3 , -store the result in -.Fa ch , -and return 1; otherwise, set -.Va errno -to -.Er ERANGE -and return \-1. -In the C or POSIX locale, this simply reads a byte, but for any other -locale, including UTF-8, this is rarely useful. -.It Fn el_wpush -Push the wide character string -.Fa wcs -back onto the input queue described in -.Xr editline 7 . -If the queue overflows, for example due to a recursive macro, -or if an error occurs, for example because -.Fa wcs -is -.Dv NULL -or memory allocation fails, the function beeps at the user, -but does not report the problem to the caller. -.It Fn el_push -Use the current locale to convert the multibyte string -.Fa mbs -to a wide character string, and pass the result to -.Fn el_wpush . -.It Fn el_parse -Parses the -.Fa argv -array (which is -.Fa argc -elements in size) -to execute builtin -.Nm -commands. -If the command is prefixed with -.Dq prog : -then -.Fn el_parse -will only execute the command if -.Dq prog -matches the -.Fa prog -argument supplied to -.Fn el_init . -The return value is -\-1 if the command is unknown, -0 if there was no error or -.Dq prog -didn't match, or -1 if the command returned an error. -Refer to -.Xr editrc 5 -for more information. -.It Fn el_set -Set -.Nm -parameters. -.Fa op -determines which parameter to set, and each operation has its -own parameter list. -Returns 0 on success, \-1 on failure. -.Pp -The following values for -.Fa op -are supported, along with the required argument list: -.Bl -tag -width 4n -.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" -Define prompt printing function as -.Fa f , -which is to return a string that contains the prompt. -.It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" -Same as -.Dv EL_PROMPT , -but the -.Fa c -argument indicates the start/stop literal prompt character. -.Pp -If a start/stop literal character is found in the prompt, the -character itself -is not printed, but characters after it are printed directly to the -terminal without affecting the state of the current line. -A subsequent second start/stop literal character ends this behavior. -This is typically used to embed literal escape sequences that change the -color/style of the terminal in the prompt. -Note that the literal escape character cannot be the last character in the -prompt, as the escape sequence is attached to the next character in the prompt. -.Dv 0 -unsets it. -.It Dv EL_REFRESH -Re-display the current line on the next terminal line. -.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" -Define right side prompt printing function as -.Fa f , -which is to return a string that contains the prompt. -.It Dv EL_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" -Define the right prompt printing function but with a literal escape character. -.It Dv EL_TERMINAL , Fa "const char *type" -Define terminal type of the tty to be -.Fa type , -or to -.Ev TERM -if -.Fa type -is -.Dv NULL . -.It Dv EL_EDITOR , Fa "const char *mode" -Set editing mode to -.Fa mode , -which must be one of -.Dq emacs -or -.Dq vi . -.It Dv EL_SIGNAL , Fa "int flag" -If -.Fa flag -is non-zero, -.Nm -will install its own signal handler for the following signals when -reading command input: -.Dv SIGCONT , -.Dv SIGHUP , -.Dv SIGINT , -.Dv SIGQUIT , -.Dv SIGSTOP , -.Dv SIGTERM , -.Dv SIGTSTP , -and -.Dv SIGWINCH . -Otherwise, the current signal handlers will be used. -.It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL -Perform the -.Ic bind -builtin command. -Refer to -.Xr editrc 5 -for more information. -.It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL -Perform the -.Ic echotc -builtin command. -Refer to -.Xr editrc 5 -for more information. -.It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL -Perform the -.Ic settc -builtin command. -Refer to -.Xr editrc 5 -for more information. -.It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL -Perform the -.Ic setty -builtin command. -Refer to -.Xr editrc 5 -for more information. -.It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL -Perform the -.Ic telltc -builtin command. -Refer to -.Xr editrc 5 -for more information. -.It Dv EL_ADDFN , Fa "const char *name" , Fa "const char *help" , \ -Fa "unsigned char (*func)(EditLine *e, int ch)" -Add a user defined function, -.Fn func , -referred to as -.Fa name -which is invoked when a key which is bound to -.Fa name -is entered. -.Fa help -is a description of -.Fa name . -At invocation time, -.Fa ch -is the key which caused the invocation. -The return value of -.Fn func -should be one of: -.Bl -tag -width "CC_REDISPLAY" -.It Dv CC_NORM -Add a normal character. -.It Dv CC_NEWLINE -End of line was entered. -.It Dv CC_EOF -EOF was entered. -.It Dv CC_ARGHACK -Expecting further command input as arguments, do nothing visually. -.It Dv CC_REFRESH -Refresh display. -.It Dv CC_REFRESH_BEEP -Refresh display, and beep. -.It Dv CC_CURSOR -Cursor moved, so update and perform -.Dv CC_REFRESH . -.It Dv CC_REDISPLAY -Redisplay entire input line. -This is useful if a key binding outputs extra information. -.It Dv CC_ERROR -An error occurred. -Beep, and flush tty. -.It Dv CC_FATAL -Fatal error, reset tty to known state. -.El -.It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \ -Fa "const char *ptr" -Defines which history function to use, which is usually -.Fn history . -.Fa ptr -should be the value returned by -.Fn history_init . -.It Dv EL_EDITMODE , Fa "int flag" -If -.Fa flag -is non-zero, -editing is enabled (the default). -Note that this is only an indication, and does not -affect the operation of -.Nm . -At this time, it is the caller's responsibility to -check this -(using -.Fn el_get ) -to determine if editing should be enabled or not. -.It Dv EL_UNBUFFERED , Fa "int flag" -If -.Fa flag -is zero, -unbuffered mode is disabled (the default). -In unbuffered mode, -.Fn el_gets -will return immediately after processing a single character. -.It Dv EL_GETCFN , Fa "el_rfunc_t f" -Whenever reading a character, use the function -.Bd -ragged -offset indent -compact -.Ft int -.Fo f -.Fa "EditLine *e" -.Fa "wchar_t *wc" -.Fc -.Ed -which stores the character in -.Fa wc -and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding -errors. -Functions internally using it include -.Fn el_wgets , -.Fn el_wgetc , -.Fn el_gets , -and -.Fn el_getc . -Initially, a builtin function is installed, and replacing it -is discouraged because writing such a function is very error prone. -The builtin function can be restored at any time by passing the -special value -.Dv EL_BUILTIN_GETCFN -instead of a function pointer. -.It Dv EL_CLIENTDATA , Fa "void *data" -Register -.Fa data -to be associated with this EditLine structure. -It can be retrieved with the corresponding -.Fn el_get -call. -.It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp" -Set the current -.Nm editline -file pointer for -.Dq input -.Fa fd -= -.Dv 0 , -.Dq output -.Fa fd -= -.Dv 1 , -or -.Dq error -.Fa fd -= -.Dv 2 -from -.Fa fp . -.El -.It Fn el_get -Get -.Nm -parameters. -.Fa op -determines which parameter to retrieve into -.Fa result . -Returns 0 if successful, \-1 otherwise. -.Pp -The following values for -.Fa op -are supported, along with actual type of -.Fa result : -.Bl -tag -width 4n -.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" -Set -.Fa f -to a pointer to the function that displays the prompt. -If -.Fa c -is not -.Dv NULL , -set it to the start/stop literal prompt character. -.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" -Set -.Fa f -to a pointer to the function that displays the prompt. -If -.Fa c -is not -.Dv NULL , -set it to the start/stop literal prompt character. -.It Dv EL_EDITOR , Fa "const char **n" -Set the name of the editor in -.Fa n , -which will be one of -.Dq emacs -or -.Dq vi . -.It Dv EL_GETTC , Fa "const char *name" , Fa "void *value" -If -.Fa name -is a valid -.Xr termcap 5 -capability set -.Fa value -to the current value of that capability. -.It Dv EL_SIGNAL , Fa "int *s" -Set -.Fa s -to non-zero if -.Nm -has installed private signal handlers (see -.Fn el_get -above). -.It Dv EL_EDITMODE , Fa "int *c" -Set -.Fa c -to non-zero if editing is enabled. -.It Dv EL_GETCFN , Fa "el_rfunc_t *f" -Set -.Fa f -to a pointer to the function that reads characters, or to -.Dv EL_BUILTIN_GETCFN -if the builtin function is in use. -.It Dv EL_CLIENTDATA , Fa "void **data" -Set -.Fa data -to the previously registered client data set by an -.Fn el_set -call. -.It Dv EL_UNBUFFERED , Fa "int *c" -Set -.Fa c -to non-zero if unbuffered mode is enabled. -.It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp" -Set -.Fa fp -to the current -.Nm editline -file pointer for -.Dq input -.Fa fd -= -.Dv 0 , -.Dq output -.Fa fd -= -.Dv 1 , -or -.Dq error -.Fa fd -= -.Dv 2 . -.El -.It Fn el_source -Initialize -.Nm -by reading the contents of -.Fa file . -.Fn el_parse -is called for each line in -.Fa file . -If -.Fa file -is -.Dv NULL , -try -.Pa $EDITRC -and if that is not set -.Pa $HOME/.editrc . -Refer to -.Xr editrc 5 -for details on the format of -.Fa file . -.Fn el_source -returns 0 on success and \-1 on error. -.It Fn el_resize -Must be called if the terminal size changes. -If -.Dv EL_SIGNAL -has been set with -.Fn el_set , -then this is done automatically. -Otherwise, it's the responsibility of the application to call -.Fn el_resize -on the appropriate occasions. -.It Fn el_cursor -Move the cursor to the right (if positive) or to the left (if negative) -.Fa count -characters. -Returns the resulting offset of the cursor from the beginning of the line. -.It Fn el_line -Return the editing information for the current line in a -.Fa LineInfo -structure, which is defined as follows: -.Bd -literal -typedef struct lineinfo { - const char *buffer; /* address of buffer */ - const char *cursor; /* address of cursor */ - const char *lastchar; /* address of last character */ -} LineInfo; -.Ed -.Pp -.Fa buffer -is not NUL terminated. -This function may be called after -.Fn el_gets -to obtain the -.Fa LineInfo -structure pertaining to line returned by that function, -and from within user defined functions added with -.Dv EL_ADDFN . -.It Fn el_insertstr -Insert -.Fa str -into the line at the cursor. -Returns \-1 if -.Fa str -is empty or won't fit, and 0 otherwise. -.It Fn el_deletestr -Delete -.Fa count -characters before the cursor. -.El -.Sh HISTORY LIST FUNCTIONS -The history functions use a common data structure, -.Fa History , -which is created by -.Fn history_init -and freed by -.Fn history_end . -.Pp -The following functions are available: -.Bl -tag -width 4n -.It Fn history_init -Initialize the history list, and return a data structure -to be used by all other history list functions, or -.Dv NULL -on failure. -.It Fn history_end -Clean up and finish with -.Fa h , -assumed to have been created with -.Fn history_init . -.It Fn history -Perform operation -.Fa op -on the history list, with optional arguments as needed by the -operation. -.Fa ev -is changed accordingly to operation. -The following values for -.Fa op -are supported, along with the required argument list: -.Bl -tag -width 4n -.It Dv H_SETSIZE , Fa "int size" -Set size of history to -.Fa size -elements. -.It Dv H_GETSIZE -Get number of events currently in history. -.It Dv H_END -Cleans up and finishes with -.Fa h , -assumed to be created with -.Fn history_init . -.It Dv H_CLEAR -Clear the history. -.It Dv H_FUNC , Fa "void *ptr" , Fa "history_gfun_t first" , \ -Fa "history_gfun_t next" , Fa "history_gfun_t last" , \ -Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \ -Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \ -Fa "history_efun_t enter" , Fa "history_efun_t add" -Define functions to perform various history operations. -.Fa ptr -is the argument given to a function when it's invoked. -.It Dv H_FIRST -Return the first element in the history. -.It Dv H_LAST -Return the last element in the history. -.It Dv H_PREV -Return the previous element in the history. -It is newer than the current one. -.It Dv H_NEXT -Return the next element in the history. -It is older than the current one. -.It Dv H_CURR -Return the current element in the history. -.It Dv H_SET , Fa "int position" -Set the cursor to point to the requested element. -.It Dv H_ADD , Fa "const char *str" -Append -.Fa str -to the current element of the history, or perform the -.Dv H_ENTER -operation with argument -.Fa str -if there is no current element. -.It Dv H_APPEND , Fa "const char *str" -Append -.Fa str -to the last new element of the history. -.It Dv H_ENTER , Fa "const char *str" -Add -.Fa str -as a new element to the history and, if necessary, -removing the oldest entry to keep the list to the created size. -If -.Dv H_SETUNIQUE -has been called with a non-zero argument, the element -will not be entered into the history if its contents match -the ones of the current history element. -If the element is entered -.Fn history -returns 1; if it is ignored as a duplicate returns 0. -Finally -.Fn history -returns \-1 if an error occurred. -.It Dv H_PREV_STR , Fa "const char *str" -Return the closest previous event that starts with -.Fa str . -.It Dv H_NEXT_STR , Fa "const char *str" -Return the closest next event that starts with -.Fa str . -.It Dv H_PREV_EVENT , Fa "int e" -Return the previous event numbered -.Fa e . -.It Dv H_NEXT_EVENT , Fa "int e" -Return the next event numbered -.Fa e . -.It Dv H_LOAD , Fa "const char *file" -Load the history list stored in -.Fa file . -.It Dv H_SAVE , Fa "const char *file" -Save the history list to -.Fa file . -.It Dv H_SAVE_INCR , Fa "const char *file" , Fa "int e" -Append the history list since the event numbered -.Fa e -to -.Fa file . -.It Dv H_SAVE_FP , Fa "FILE *fp" -Save the history list to the opened -.Ft FILE -pointer -.Fa fp . -.It Dv H_SAVE_FP_INCR , Fa "FILE *fp" , Fa "int e" -Append the history list since the event numbered -.Fa e -to the opened -.Ft FILE -pointer -.Fa fp . -.It Dv H_SETUNIQUE , Fa "int unique" -Set flag that adjacent identical event strings should not be entered -into the history. -.It Dv H_GETUNIQUE -Retrieve the current setting if adjacent identical elements should -be entered into the history. -.It Dv H_DEL , Fa "int e" -Delete the event numbered -.Fa e . -This function is only provided for -.Xr readline 3 -compatibility. -The caller is responsible for free'ing the string in the returned -.Fa HistEvent . -.El -.Pp -.Fn history -returns >= 0 if the operation -.Fa op -succeeds. -Otherwise, \-1 is returned and -.Fa ev -is updated to contain more details about the error. -.El -.Sh TOKENIZATION FUNCTIONS -The tokenization functions use a common data structure, -.Fa Tokenizer , -which is created by -.Fn tok_init -and freed by -.Fn tok_end . -.Pp -The following functions are available: -.Bl -tag -width 4n -.It Fn tok_init -Initialize the tokenizer, and return a data structure -to be used by all other tokenizer functions. -.Fa IFS -contains the Input Field Separators, which defaults to -.Aq space , -.Aq tab , -and -.Aq newline -if -.Dv NULL . -.It Fn tok_end -Clean up and finish with -.Fa t , -assumed to have been created with -.Fn tok_init . -.It Fn tok_reset -Reset the tokenizer state. -Use after a line has been successfully tokenized -by -.Fn tok_line -or -.Fn tok_str -and before a new line is to be tokenized. -.It Fn tok_line -Tokenize -.Fa li , -If successful, modify: -.Fa argv -to contain the words, -.Fa argc -to contain the number of words, -.Fa cursorc -(if not -.Dv NULL ) -to contain the index of the word containing the cursor, -and -.Fa cursoro -(if not -.Dv NULL ) -to contain the offset within -.Fa argv[cursorc] -of the cursor. -.Pp -Returns -0 if successful, -\-1 for an internal error, -1 for an unmatched single quote, -2 for an unmatched double quote, -and -3 for a backslash quoted -.Aq newline . -A positive exit code indicates that another line should be read -and tokenization attempted again. -. -.It Fn tok_str -A simpler form of -.Fn tok_line ; -.Fa str -is a NUL terminated string to tokenize. -.El -. -.\"XXX.Sh EXAMPLES -.\"XXX: provide some examples -.Sh SEE ALSO -.Xr sh 1 , -.Xr signal 3 , -.Xr termcap 3 , -.Xr editrc 5 , -.Xr termcap 5 , -.Xr editline 7 -.Sh HISTORY -The -.Nm -library first appeared in -.Bx 4.4 . -.Dv CC_REDISPLAY -appeared in -.Nx 1.3 . -.Dv CC_REFRESH_BEEP , -.Dv EL_EDITMODE -and the readline emulation appeared in -.Nx 1.4 . -.Dv EL_RPROMPT -appeared in -.Nx 1.5 . -.Sh AUTHORS -.An -nosplit -The -.Nm -library was written by -.An Christos Zoulas . -.An Luke Mewburn -wrote this manual and implemented -.Dv CC_REDISPLAY , -.Dv CC_REFRESH_BEEP , -.Dv EL_EDITMODE , -and -.Dv EL_RPROMPT . -.An Jaromir Dolecek -implemented the readline emulation. -.An Johny Mattsson -implemented wide-character support. -.Sh BUGS -At this time, it is the responsibility of the caller to -check the result of the -.Dv EL_EDITMODE -operation of -.Fn el_get -(after an -.Fn el_source -or -.Fn el_parse ) -to determine if -.Nm -should be used for further input. -I.e., -.Dv EL_EDITMODE -is purely an indication of the result of the most recent -.Xr editrc 5 -.Ic edit -command. |