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