1.\" $OpenBSD: editline.3,v 1.46 2016/05/22 22:08:42 schwarze Exp $ 2.\" $NetBSD: editline.3,v 1.88 2016/02/25 14:59:22 wiz Exp $ 3.\" 4.\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This file was contributed to The NetBSD Foundation by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: May 22 2016 $ 31.Dt EDITLINE 3 32.Os 33.Sh NAME 34.Nm editline , 35.Nm el_init , 36.Nm el_end , 37.Nm el_reset , 38.Nm el_gets , 39.Nm el_wgets , 40.Nm el_getc , 41.Nm el_wgetc , 42.Nm el_push , 43.Nm el_wpush , 44.Nm el_parse , 45.Nm el_wparse , 46.Nm el_set , 47.Nm el_wset , 48.Nm el_get , 49.Nm el_wget , 50.Nm el_source , 51.Nm el_resize , 52.Nm el_line , 53.Nm el_wline , 54.Nm el_insertstr , 55.Nm el_winsertstr , 56.Nm el_deletestr , 57.Nm el_wdeletestr , 58.Nm history_init , 59.Nm history_winit , 60.Nm history_end , 61.Nm history_wend , 62.Nm history , 63.Nm history_w , 64.Nm tok_init , 65.Nm tok_winit , 66.Nm tok_end , 67.Nm tok_wend , 68.Nm tok_reset , 69.Nm tok_wreset , 70.Nm tok_line , 71.Nm tok_wline , 72.Nm tok_str , 73.Nm tok_wstr 74.Nd line editor, history and tokenization functions 75.Sh SYNOPSIS 76.In histedit.h 77.Ft EditLine * 78.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" 79.Ft void 80.Fn el_end "EditLine *e" 81.Ft void 82.Fn el_reset "EditLine *e" 83.Ft const char * 84.Fn el_gets "EditLine *e" "int *count" 85.Ft const wchar_t * 86.Fn el_wgets "EditLine *e" "int *count" 87.Ft int 88.Fn el_getc "EditLine *e" "char *ch" 89.Ft int 90.Fn el_wgetc "EditLine *e" "wchar_t *wc" 91.Ft void 92.Fn el_push "EditLine *e" "const char *mbs" 93.Ft void 94.Fn el_wpush "EditLine *e" "const wchar_t *wcs" 95.Ft int 96.Fn el_parse "EditLine *e" "int argc" "const char *argv[]" 97.Ft int 98.Fn el_wparse "EditLine *e" "int argc" "const wchar_t *argv[]" 99.Ft int 100.Fn el_set "EditLine *e" "int op" "..." 101.Ft int 102.Fn el_wset "EditLine *e" "int op" "..." 103.Ft int 104.Fn el_get "EditLine *e" "int op" "..." 105.Ft int 106.Fn el_wget "EditLine *e" "int op" "..." 107.Ft int 108.Fn el_source "EditLine *e" "const char *file" 109.Ft void 110.Fn el_resize "EditLine *e" 111.Ft const LineInfo * 112.Fn el_line "EditLine *e" 113.Ft const LineInfoW * 114.Fn el_wline "EditLine *e" 115.Ft int 116.Fn el_insertstr "EditLine *e" "const char *str" 117.Ft int 118.Fn el_winsertstr "EditLine *e" "const wchar_t *str" 119.Ft void 120.Fn el_deletestr "EditLine *e" "int count" 121.Ft void 122.Fn el_wdeletestr "EditLine *e" "int count" 123.Ft History * 124.Fn history_init void 125.Ft HistoryW * 126.Fn history_winit void 127.Ft void 128.Fn history_end "History *h" 129.Ft void 130.Fn history_wend "HistoryW *h" 131.Ft int 132.Fn history "History *h" "HistEvent *ev" "int op" "..." 133.Ft int 134.Fn history_w "HistoryW *h" "HistEventW *ev" "int op" "..." 135.Ft Tokenizer * 136.Fn tok_init "const char *IFS" 137.Ft TokenizerW * 138.Fn tok_winit "const wchar_t *IFS" 139.Ft void 140.Fn tok_end "Tokenizer *t" 141.Ft void 142.Fn tok_wend "TokenizerW *t" 143.Ft void 144.Fn tok_reset "Tokenizer *t" 145.Ft void 146.Fn tok_wreset "TokenizerW *t" 147.Ft int 148.Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro" 149.Ft int 150.Fn tok_wline "TokenizerW *t" "const LineInfoW *li" "int *argc" "const wchar_t **argv[]" "int *cursorc" "int *cursoro" 151.Ft int 152.Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]" 153.Ft int 154.Fn tok_wstr "TokenizerW *t" "const wchar_t *str" "int *argc" "const wchar_t **argv[]" 155.Sh DESCRIPTION 156The 157.Nm 158library provides generic line editing, history and tokenization functions, 159similar to those found in 160.Xr sh 1 . 161.Pp 162These functions are available in the 163.Nm libedit 164library (which needs the 165.Nm libcurses 166library). 167Programs should be linked with 168.Fl ledit lcurses . 169.Pp 170The 171.Nm 172library respects the 173.Ev LC_CTYPE 174locale set by the application program and never uses 175.Xr setlocale 3 176to change the locale. 177The only locales supported are UTF-8 and the default C or POSIX locale. 178If any other locale is set, behaviour is undefined. 179.Sh LINE EDITING FUNCTIONS 180The line editing functions use a common data structure, 181.Fa EditLine , 182which is created by 183.Fn el_init 184and freed by 185.Fn el_end . 186.Pp 187The wide-character functions behave the same way as their narrow 188counterparts. 189.Pp 190The following functions are available: 191.Bl -tag -width 4n 192.It Fn el_init 193Initialize the line editor, and return a data structure 194to be used by all other line editing functions, or 195.Dv NULL 196on failure. 197.Fa prog 198is the name of the invoking program, used when reading the 199.Xr editrc 5 200file to determine which settings to use. 201.Fa fin , 202.Fa fout 203and 204.Fa ferr 205are the input, output, and error streams (respectively) to use. 206In this documentation, references to 207.Dq the tty 208are actually to this input/output stream combination. 209.It Fn el_end 210Clean up and finish with 211.Fa e , 212assumed to have been created with 213.Fn el_init . 214.It Fn el_reset 215Reset the tty and the parser. 216This should be called after an error which may have upset the tty's 217state. 218.It Fn el_gets 219Read a line from the tty. 220.Fa count 221is modified to contain the number of characters read. 222Returns the line read if successful, or 223.Dv NULL 224if no characters were read or if an error occurred. 225If an error occurred, 226.Fa count 227is set to \-1 and 228.Dv errno 229contains the error code that caused it. 230The return value may not remain valid across calls to 231.Fn el_gets 232and must be copied if the data is to be retained. 233.It Fn el_wgetc 234Read a wide character from the tty, respecting the current locale, 235or from the input queue described in 236.Xr editline 7 237if that is not empty, and store it in 238.Fa wc . 239If an invalid or incomplete character is found, it is discarded, 240.Va errno 241is set to 242.Er EILSEQ , 243and the next character is read and stored in 244.Fa wc . 245Returns 1 if a valid character was read, 0 on end of file, or \-1 on 246.Xr read 2 247failure. 248In the latter case, 249.Va errno 250is set to indicate the error. 251.It Fn el_getc 252Read a wide character as described for 253.Fn el_wgetc 254and return 0 on end of file or \-1 on failure. 255If the wide character can be represented as a single-byte character, 256convert it with 257.Xr wctob 3 , 258store the result in 259.Fa ch , 260and return 1; otherwise, set 261.Va errno 262to 263.Er ERANGE 264and return \-1. 265In the C or POSIX locale, this simply reads a byte, but for any other 266locale, including UTF-8, this is rarely useful. 267.It Fn el_wpush 268Push the wide character string 269.Fa wcs 270back onto the input queue described in 271.Xr editline 7 . 272If the queue overflows, for example due to a recursive macro, 273or if an error occurs, for example because 274.Fa wcs 275is 276.Dv NULL 277or memory allocation fails, the function beeps at the user, 278but does not report the problem to the caller. 279.It Fn el_push 280Use the current locale to convert the multibyte string 281.Fa mbs 282to a wide character string, and pass the result to 283.Fn el_wpush . 284.It Fn el_parse 285Parses the 286.Fa argv 287array (which is 288.Fa argc 289elements in size) 290to execute builtin 291.Nm 292commands. 293If the command is prefixed with 294.Dq prog : 295then 296.Fn el_parse 297will only execute the command if 298.Dq prog 299matches the 300.Fa prog 301argument supplied to 302.Fn el_init . 303The return value is 304\-1 if the command is unknown, 3050 if there was no error or 306.Dq prog 307didn't match, or 3081 if the command returned an error. 309Refer to 310.Xr editrc 5 311for more information. 312.It Fn el_set 313Set 314.Nm 315parameters. 316.Fa op 317determines which parameter to set, and each operation has its 318own parameter list. 319Returns 0 on success, \-1 on failure. 320.Pp 321The following values for 322.Fa op 323are supported, along with the required argument list: 324.Bl -tag -width 4n 325.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 326Define prompt printing function as 327.Fa f , 328which is to return a string that contains the prompt. 329.It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" 330Same as 331.Dv EL_PROMPT , 332but the 333.Fa c 334argument indicates the start/stop literal prompt character. 335.Pp 336If a start/stop literal character is found in the prompt, the 337character itself 338is not printed, but characters after it are printed directly to the 339terminal without affecting the state of the current line. 340A subsequent second start/stop literal character ends this behavior. 341This is typically used to embed literal escape sequences that change the 342color/style of the terminal in the prompt. 343.Dv 0 344unsets it. 345.It Dv EL_REFRESH 346Re-display the current line on the next terminal line. 347.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 348Define right side prompt printing function as 349.Fa f , 350which is to return a string that contains the prompt. 351.It Dv EL_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" 352Define the right prompt printing function but with a literal escape character. 353.It Dv EL_TERMINAL , Fa "const char *type" 354Define terminal type of the tty to be 355.Fa type , 356or to 357.Ev TERM 358if 359.Fa type 360is 361.Dv NULL . 362.It Dv EL_EDITOR , Fa "const char *mode" 363Set editing mode to 364.Fa mode , 365which must be one of 366.Dq emacs 367or 368.Dq vi . 369.It Dv EL_SIGNAL , Fa "int flag" 370If 371.Fa flag 372is non-zero, 373.Nm 374will install its own signal handler for the following signals when 375reading command input: 376.Dv SIGCONT , 377.Dv SIGHUP , 378.Dv SIGINT , 379.Dv SIGQUIT , 380.Dv SIGSTOP , 381.Dv SIGTERM , 382.Dv SIGTSTP , 383and 384.Dv SIGWINCH . 385Otherwise, the current signal handlers will be used. 386.It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL 387Perform the 388.Ic bind 389builtin command. 390Refer to 391.Xr editrc 5 392for more information. 393.It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL 394Perform the 395.Ic echotc 396builtin command. 397Refer to 398.Xr editrc 5 399for more information. 400.It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL 401Perform the 402.Ic settc 403builtin command. 404Refer to 405.Xr editrc 5 406for more information. 407.It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL 408Perform the 409.Ic setty 410builtin command. 411Refer to 412.Xr editrc 5 413for more information. 414.It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL 415Perform the 416.Ic telltc 417builtin command. 418Refer to 419.Xr editrc 5 420for more information. 421.It Dv EL_ADDFN , Fa "const char *name" , Fa "const char *help" , \ 422Fa "unsigned char (*func)(EditLine *e, int ch)" 423Add a user defined function, 424.Fn func , 425referred to as 426.Fa name 427which is invoked when a key which is bound to 428.Fa name 429is entered. 430.Fa help 431is a description of 432.Fa name . 433At invocation time, 434.Fa ch 435is the key which caused the invocation. 436The return value of 437.Fn func 438should be one of: 439.Bl -tag -width "CC_REDISPLAY" 440.It Dv CC_NORM 441Add a normal character. 442.It Dv CC_NEWLINE 443End of line was entered. 444.It Dv CC_EOF 445EOF was entered. 446.It Dv CC_ARGHACK 447Expecting further command input as arguments, do nothing visually. 448.It Dv CC_REFRESH 449Refresh display. 450.It Dv CC_REFRESH_BEEP 451Refresh display, and beep. 452.It Dv CC_CURSOR 453Cursor moved, so update and perform 454.Dv CC_REFRESH . 455.It Dv CC_REDISPLAY 456Redisplay entire input line. 457This is useful if a key binding outputs extra information. 458.It Dv CC_ERROR 459An error occurred. 460Beep, and flush tty. 461.It Dv CC_FATAL 462Fatal error, reset tty to known state. 463.El 464.It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \ 465Fa "const char *ptr" 466Defines which history function to use, which is usually 467.Fn history . 468.Fa ptr 469should be the value returned by 470.Fn history_init . 471.It Dv EL_EDITMODE , Fa "int flag" 472If 473.Fa flag 474is non-zero, 475editing is enabled (the default). 476Note that this is only an indication, and does not 477affect the operation of 478.Nm . 479At this time, it is the caller's responsibility to 480check this 481(using 482.Fn el_get ) 483to determine if editing should be enabled or not. 484.It Dv EL_UNBUFFERED , Fa "int flag" 485If 486.Fa flag 487is zero, 488unbuffered mode is disabled (the default). 489In unbuffered mode, 490.Fn el_gets 491will return immediately after processing a single character. 492.It Dv EL_GETCFN , Fa "el_rfunc_t f" 493Whenever reading a character, use the function 494.Bd -ragged -offset indent -compact 495.Ft int 496.Fo f 497.Fa "EditLine *e" 498.Fa "wchar_t *wc" 499.Fc 500.Ed 501which stores the character in 502.Fa wc 503and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding 504errors. 505Functions internally using it include 506.Fn el_wgets , 507.Fn el_wgetc , 508.Fn el_gets , 509and 510.Fn el_getc . 511Initially, a builtin function is installed, and replacing it 512is discouraged because writing such a function is very error prone. 513The builtin function can be restored at any time by passing the 514special value 515.Dv EL_BUILTIN_GETCFN 516instead of a function pointer. 517.It Dv EL_CLIENTDATA , Fa "void *data" 518Register 519.Fa data 520to be associated with this EditLine structure. 521It can be retrieved with the corresponding 522.Fn el_get 523call. 524.It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp" 525Set the current 526.Nm editline 527file pointer for 528.Dq input 529.Fa fd 530= 531.Dv 0 , 532.Dq output 533.Fa fd 534= 535.Dv 1 , 536or 537.Dq error 538.Fa fd 539= 540.Dv 2 541from 542.Fa fp . 543.El 544.It Fn el_get 545Get 546.Nm 547parameters. 548.Fa op 549determines which parameter to retrieve into 550.Fa result . 551Returns 0 if successful, \-1 otherwise. 552.Pp 553The following values for 554.Fa op 555are supported, along with actual type of 556.Fa result : 557.Bl -tag -width 4n 558.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" 559Set 560.Fa f 561to a pointer to the function that displays the prompt. 562If 563.Fa c 564is not 565.Dv NULL , 566set it to the start/stop literal prompt character. 567.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" 568Set 569.Fa f 570to a pointer to the function that displays the prompt. 571If 572.Fa c 573is not 574.Dv NULL , 575set it to the start/stop literal prompt character. 576.It Dv EL_EDITOR , Fa "const char **n" 577Set the name of the editor in 578.Fa n , 579which will be one of 580.Dq emacs 581or 582.Dq vi . 583.It Dv EL_GETTC , Fa "const char *name" , Fa "void *value" 584If 585.Fa name 586is a valid 587.Xr termcap 5 588capability set 589.Fa value 590to the current value of that capability. 591.It Dv EL_SIGNAL , Fa "int *s" 592Set 593.Fa s 594to non-zero if 595.Nm 596has installed private signal handlers (see 597.Fn el_get 598above). 599.It Dv EL_EDITMODE , Fa "int *c" 600Set 601.Fa c 602to non-zero if editing is enabled. 603.It Dv EL_GETCFN , Fa "el_rfunc_t *f" 604Set 605.Fa f 606to a pointer to the function that reads characters, or to 607.Dv EL_BUILTIN_GETCFN 608if the builtin function is in use. 609.It Dv EL_CLIENTDATA , Fa "void **data" 610Set 611.Fa data 612to the previously registered client data set by an 613.Fn el_set 614call. 615.It Dv EL_UNBUFFERED , Fa "int *c" 616Set 617.Fa c 618to non-zero if unbuffered mode is enabled. 619.It Dv EL_PREP_TERM , Fa "int" 620Sets or clears terminal editing mode. 621.It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp" 622Set 623.Fa fp 624to the current 625.Nm editline 626file pointer for 627.Dq input 628.Fa fd 629= 630.Dv 0 , 631.Dq output 632.Fa fd 633= 634.Dv 1 , 635or 636.Dq error 637.Fa fd 638= 639.Dv 2 . 640.El 641.It Fn el_source 642Initialize 643.Nm 644by reading the contents of 645.Fa file . 646.Fn el_parse 647is called for each line in 648.Fa file . 649If 650.Fa file 651is 652.Dv NULL , 653try 654.Pa $HOME/.editrc . 655Refer to 656.Xr editrc 5 657for details on the format of 658.Fa file . 659.Fn el_source 660returns 0 on success and \-1 on error. 661.It Fn el_resize 662Must be called if the terminal size changes. 663If 664.Dv EL_SIGNAL 665has been set with 666.Fn el_set , 667then this is done automatically. 668Otherwise, it's the responsibility of the application to call 669.Fn el_resize 670on the appropriate occasions. 671.It Fn el_line 672Return the editing information for the current line in a 673.Fa LineInfo 674structure, which is defined as follows: 675.Bd -literal 676typedef struct lineinfo { 677 const char *buffer; /* address of buffer */ 678 const char *cursor; /* address of cursor */ 679 const char *lastchar; /* address of last character */ 680} LineInfo; 681.Ed 682.Pp 683.Fa buffer 684is not NUL terminated. 685This function may be called after 686.Fn el_gets 687to obtain the 688.Fa LineInfo 689structure pertaining to line returned by that function, 690and from within user defined functions added with 691.Dv EL_ADDFN . 692.It Fn el_insertstr 693Insert 694.Fa str 695into the line at the cursor. 696Returns \-1 if 697.Fa str 698is empty or won't fit, and 0 otherwise. 699.It Fn el_deletestr 700Delete 701.Fa count 702characters before the cursor. 703.El 704.Sh HISTORY LIST FUNCTIONS 705The history functions use a common data structure, 706.Fa History , 707which is created by 708.Fn history_init 709and freed by 710.Fn history_end . 711.Pp 712The following functions are available: 713.Bl -tag -width 4n 714.It Fn history_init 715Initialize the history list, and return a data structure 716to be used by all other history list functions, or 717.Dv NULL 718on failure. 719.It Fn history_end 720Clean up and finish with 721.Fa h , 722assumed to have been created with 723.Fn history_init . 724.It Fn history 725Perform operation 726.Fa op 727on the history list, with optional arguments as needed by the 728operation. 729.Fa ev 730is changed accordingly to operation. 731The following values for 732.Fa op 733are supported, along with the required argument list: 734.Bl -tag -width 4n 735.It Dv H_SETSIZE , Fa "int size" 736Set size of history to 737.Fa size 738elements. 739.It Dv H_GETSIZE 740Get number of events currently in history. 741.It Dv H_END 742Cleans up and finishes with 743.Fa h , 744assumed to be created with 745.Fn history_init . 746.It Dv H_CLEAR 747Clear the history. 748.It Dv H_FUNC , Fa "void *ptr" , Fa "history_gfun_t first" , \ 749Fa "history_gfun_t next" , Fa "history_gfun_t last" , \ 750Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \ 751Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \ 752Fa "history_efun_t enter" , Fa "history_efun_t add" 753Define functions to perform various history operations. 754.Fa ptr 755is the argument given to a function when it's invoked. 756.It Dv H_FIRST 757Return the first element in the history. 758.It Dv H_LAST 759Return the last element in the history. 760.It Dv H_PREV 761Return the previous element in the history. 762It is newer than the current one. 763.It Dv H_NEXT 764Return the next element in the history. 765It is older than the current one. 766.It Dv H_CURR 767Return the current element in the history. 768.It Dv H_SET 769Set the cursor to point to the requested element. 770.It Dv H_ADD , Fa "const char *str" 771Append 772.Fa str 773to the current element of the history, or perform the 774.Dv H_ENTER 775operation with argument 776.Fa str 777if there is no current element. 778.It Dv H_APPEND , Fa "const char *str" 779Append 780.Fa str 781to the last new element of the history. 782.It Dv H_ENTER , Fa "const char *str" 783Add 784.Fa str 785as a new element to the history and, if necessary, 786removing the oldest entry to keep the list to the created size. 787If 788.Dv H_SETUNIQUE 789has been called with a non-zero argument, the element 790will not be entered into the history if its contents match 791the ones of the current history element. 792If the element is entered 793.Fn history 794returns 1; if it is ignored as a duplicate returns 0. 795Finally 796.Fn history 797returns \-1 if an error occurred. 798.It Dv H_PREV_STR , Fa "const char *str" 799Return the closest previous event that starts with 800.Fa str . 801.It Dv H_NEXT_STR , Fa "const char *str" 802Return the closest next event that starts with 803.Fa str . 804.It Dv H_PREV_EVENT , Fa "int e" 805Return the previous event numbered 806.Fa e . 807.It Dv H_NEXT_EVENT , Fa "int e" 808Return the next event numbered 809.Fa e . 810.It Dv H_LOAD , Fa "const char *file" 811Load the history list stored in 812.Fa file . 813.It Dv H_SAVE , Fa "const char *file" 814Save the history list to 815.Fa file . 816.It Dv H_SAVE_FP , Fa "FILE *fp" 817Save the history list to the opened 818.Ft FILE 819pointer 820.Fa fp . 821.It Dv H_SETUNIQUE , Fa "int unique" 822Set flag that adjacent identical event strings should not be entered 823into the history. 824.It Dv H_GETUNIQUE 825Retrieve the current setting if adjacent identical elements should 826be entered into the history. 827.It Dv H_DEL , Fa "int e" 828Delete the event numbered 829.Fa e . 830This function is only provided for 831.Xr readline 3 832compatibility. 833The caller is responsible for free'ing the string in the returned 834.Fa HistEvent . 835.El 836.Pp 837.Fn history 838returns \*[Gt]= 0 if the operation 839.Fa op 840succeeds. 841Otherwise, \-1 is returned and 842.Fa ev 843is updated to contain more details about the error. 844.El 845.Sh TOKENIZATION FUNCTIONS 846The tokenization functions use a common data structure, 847.Fa Tokenizer , 848which is created by 849.Fn tok_init 850and freed by 851.Fn tok_end . 852.Pp 853The following functions are available: 854.Bl -tag -width 4n 855.It Fn tok_init 856Initialize the tokenizer, and return a data structure 857to be used by all other tokenizer functions. 858.Fa IFS 859contains the Input Field Separators, which defaults to 860.Aq space , 861.Aq tab , 862and 863.Aq newline 864if 865.Dv NULL . 866.It Fn tok_end 867Clean up and finish with 868.Fa t , 869assumed to have been created with 870.Fn tok_init . 871.It Fn tok_reset 872Reset the tokenizer state. 873Use after a line has been successfully tokenized 874by 875.Fn tok_line 876or 877.Fn tok_str 878and before a new line is to be tokenized. 879.It Fn tok_line 880Tokenize 881.Fa li , 882If successful, modify: 883.Fa argv 884to contain the words, 885.Fa argc 886to contain the number of words, 887.Fa cursorc 888(if not 889.Dv NULL ) 890to contain the index of the word containing the cursor, 891and 892.Fa cursoro 893(if not 894.Dv NULL ) 895to contain the offset within 896.Fa argv[cursorc] 897of the cursor. 898.Pp 899Returns 9000 if successful, 901\-1 for an internal error, 9021 for an unmatched single quote, 9032 for an unmatched double quote, 904and 9053 for a backslash quoted 906.Aq newline . 907A positive exit code indicates that another line should be read 908and tokenization attempted again. 909. 910.It Fn tok_str 911A simpler form of 912.Fn tok_line ; 913.Fa str 914is a NUL terminated string to tokenize. 915.El 916. 917.\"XXX.Sh EXAMPLES 918.\"XXX: provide some examples 919.Sh SEE ALSO 920.Xr sh 1 , 921.Xr curses 3 , 922.Xr signal 3 , 923.Xr editrc 5 , 924.Xr termcap 5 , 925.Xr editline 7 926.Sh HISTORY 927The 928.Nm 929library first appeared in 930.Bx 4.4 . 931.Dv CC_REDISPLAY 932appeared in 933.Nx 1.3 . 934.Dv CC_REFRESH_BEEP , 935.Dv EL_EDITMODE 936and the readline emulation appeared in 937.Nx 1.4 . 938.Dv EL_RPROMPT 939appeared in 940.Nx 1.5 . 941.Sh AUTHORS 942.An -nosplit 943The 944.Nm 945library was written by 946.An Christos Zoulas . 947.An Luke Mewburn 948wrote this manual and implemented 949.Dv CC_REDISPLAY , 950.Dv CC_REFRESH_BEEP , 951.Dv EL_EDITMODE , 952and 953.Dv EL_RPROMPT . 954.An Jaromir Dolecek 955implemented the readline emulation. 956.An Johny Mattsson 957implemented wide-character support. 958.Sh BUGS 959At this time, it is the responsibility of the caller to 960check the result of the 961.Dv EL_EDITMODE 962operation of 963.Fn el_get 964(after an 965.Fn el_source 966or 967.Fn el_parse ) 968to determine if 969.Nm 970should be used for further input. 971I.e., 972.Dv EL_EDITMODE 973is purely an indication of the result of the most recent 974.Xr editrc 5 975.Ic edit 976command. 977