1.\" $NetBSD: editline.3,v 1.77 2012/09/11 20:29:58 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 September 11, 2012 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 176The wide-character functions behave the same way as their narrow 177counterparts. 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, 225in which case 226.Dv errno 227can be inspected for the cause. 228.It Fn el_push 229Pushes 230.Fa str 231back onto the input stream. 232This is used by the macro expansion mechanism. 233Refer to the description of 234.Ic bind 235.Fl s 236in 237.Xr editrc 5 238for more information. 239.It Fn el_parse 240Parses the 241.Fa argv 242array (which is 243.Fa argc 244elements in size) 245to execute builtin 246.Nm 247commands. 248If the command is prefixed with 249.Dq prog : 250then 251.Fn el_parse 252will only execute the command if 253.Dq prog 254matches the 255.Fa prog 256argument supplied to 257.Fn el_init . 258The return value is 259\-1 if the command is unknown, 2600 if there was no error or 261.Dq prog 262didn't match, or 2631 if the command returned an error. 264Refer to 265.Xr editrc 5 266for more information. 267.It Fn el_set 268Set 269.Nm 270parameters. 271.Fa op 272determines which parameter to set, and each operation has its 273own parameter list. 274.Pp 275The following values for 276.Fa op 277are supported, along with the required argument list: 278.Bl -tag -width 4n 279.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 280Define prompt printing function as 281.Fa f , 282which is to return a string that contains the prompt. 283.It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" 284Same as 285.Dv EL_PROMPT , 286but the 287.Fa c 288argument indicates the start/stop literal prompt character. 289.Pp 290If a start/stop literal character is found in the prompt, the 291character itself 292is not printed, but characters after it are printed directly to the 293terminal without affecting the state of the current line. 294A subsequent second start/stop literal character ends this behavior. 295This is typically used to embed literal escape sequences that change the 296color/style of the terminal in the prompt. 297.Dv 0 298unsets it. 299.It Dv EL_REFRESH 300Re-display the current line on the next terminal line. 301.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 302Define right side prompt printing function as 303.Fa f , 304which is to return a string that contains the prompt. 305.It Dv EL_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" 306Define the right prompt printing function but with a literal escape character. 307.It Dv EL_TERMINAL , Fa "const char *type" 308Define terminal type of the tty to be 309.Fa type , 310or to 311.Ev TERM 312if 313.Fa type 314is 315.Dv NULL . 316.It Dv EL_EDITOR , Fa "const char *mode" 317Set editing mode to 318.Fa mode , 319which must be one of 320.Dq emacs 321or 322.Dq vi . 323.It Dv EL_SIGNAL , Fa "int flag" 324If 325.Fa flag 326is non-zero, 327.Nm 328will install its own signal handler for the following signals when 329reading command input: 330.Dv SIGCONT , 331.Dv SIGHUP , 332.Dv SIGINT , 333.Dv SIGQUIT , 334.Dv SIGSTOP , 335.Dv SIGTERM , 336.Dv SIGTSTP , 337and 338.Dv SIGWINCH . 339Otherwise, the current signal handlers will be used. 340.It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL 341Perform the 342.Ic bind 343builtin command. 344Refer to 345.Xr editrc 5 346for more information. 347.It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL 348Perform the 349.Ic echotc 350builtin command. 351Refer to 352.Xr editrc 5 353for more information. 354.It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL 355Perform the 356.Ic settc 357builtin command. 358Refer to 359.Xr editrc 5 360for more information. 361.It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL 362Perform the 363.Ic setty 364builtin command. 365Refer to 366.Xr editrc 5 367for more information. 368.It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL 369Perform the 370.Ic telltc 371builtin command. 372Refer to 373.Xr editrc 5 374for more information. 375.It Dv EL_ADDFN , Fa "const char *name" , Fa "const char *help" , \ 376Fa "unsigned char (*func)(EditLine *e, int ch)" 377Add a user defined function, 378.Fn func , 379referred to as 380.Fa name 381which is invoked when a key which is bound to 382.Fa name 383is entered. 384.Fa help 385is a description of 386.Fa name . 387At invocation time, 388.Fa ch 389is the key which caused the invocation. 390The return value of 391.Fn func 392should be one of: 393.Bl -tag -width "CC_REDISPLAY" 394.It Dv CC_NORM 395Add a normal character. 396.It Dv CC_NEWLINE 397End of line was entered. 398.It Dv CC_EOF 399EOF was entered. 400.It Dv CC_ARGHACK 401Expecting further command input as arguments, do nothing visually. 402.It Dv CC_REFRESH 403Refresh display. 404.It Dv CC_REFRESH_BEEP 405Refresh display, and beep. 406.It Dv CC_CURSOR 407Cursor moved, so update and perform 408.Dv CC_REFRESH . 409.It Dv CC_REDISPLAY 410Redisplay entire input line. 411This is useful if a key binding outputs extra information. 412.It Dv CC_ERROR 413An error occurred. 414Beep, and flush tty. 415.It Dv CC_FATAL 416Fatal error, reset tty to known state. 417.El 418.It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \ 419Fa "const char *ptr" 420Defines which history function to use, which is usually 421.Fn history . 422.Fa ptr 423should be the value returned by 424.Fn history_init . 425.It Dv EL_EDITMODE , Fa "int flag" 426If 427.Fa flag 428is non-zero, 429editing is enabled (the default). 430Note that this is only an indication, and does not 431affect the operation of 432.Nm . 433At this time, it is the caller's responsibility to 434check this 435(using 436.Fn el_get ) 437to determine if editing should be enabled or not. 438.It Dv EL_UNBUFFERED , Fa "int flag" 439If 440.Fa flag 441is zero, 442unbuffered mode is disabled (the default). 443In unbuffered mode, 444.Fn el_gets 445will return immediately after processing a single character. 446.It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)" 447Define the character reading function as 448.Fa f , 449which is to return the number of characters read and store them in 450.Fa c . 451This function is called internally by 452.Fn el_gets 453and 454.Fn el_getc . 455The builtin function can be set or restored with the special function 456name 457.Dq Dv EL_BUILTIN_GETCFN . 458.It Dv EL_CLIENTDATA , Fa "void *data" 459Register 460.Fa data 461to be associated with this EditLine structure. 462It can be retrieved with the corresponding 463.Fn el_get 464call. 465.It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp" 466Set the current 467.Nm editline 468file pointer for 469.Dq input 470.Fa fd 471= 472.Dv 0 , 473.Dq output 474.Fa fd 475= 476.Dv 1 , 477or 478.Dq error 479.Fa fd 480= 481.Dv 2 482from 483.Fa fp . 484.El 485.It Fn el_get 486Get 487.Nm 488parameters. 489.Fa op 490determines which parameter to retrieve into 491.Fa result . 492Returns 0 if successful, \-1 otherwise. 493.Pp 494The following values for 495.Fa op 496are supported, along with actual type of 497.Fa result : 498.Bl -tag -width 4n 499.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" 500Return a pointer to the function that displays the prompt in 501.Fa f . 502If 503.Fa c 504is not 505.Dv NULL , 506return the start/stop literal prompt character in it. 507.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" 508Return a pointer to the function that displays the prompt in 509.Fa f . 510If 511.Fa c 512is not 513.Dv NULL , 514return the start/stop literal prompt character in it. 515.It Dv EL_EDITOR , Fa "const char **" 516Return the name of the editor, which will be one of 517.Dq emacs 518or 519.Dq vi . 520.It Dv EL_GETTC , Fa "const char *name" , Fa "void *value" 521Return non-zero if 522.Fa name 523is a valid 524.Xr termcap 5 525capability 526and set 527.Fa value 528to the current value of that capability. 529.It Dv EL_SIGNAL , Fa "int *" 530Return non-zero if 531.Nm 532has installed private signal handlers (see 533.Fn el_get 534above). 535.It Dv EL_EDITMODE , Fa "int *" 536Return non-zero if editing is enabled. 537.It Dv EL_GETCFN , Fa "int (**f)(EditLine *, char *)" 538Return a pointer to the function that read characters, which is equal to 539.Dq Dv EL_BUILTIN_GETCFN 540in the case of the default builtin function. 541.It Dv EL_CLIENTDATA , Fa "void **data" 542Retrieve 543.Fa data 544previously registered with the corresponding 545.Fn el_set 546call. 547.It Dv EL_UNBUFFERED , Fa "int" 548Return non-zero if unbuffered mode is enabled. 549.It Dv EL_PREP_TERM , Fa "int" 550Sets or clears terminal editing mode. 551.It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp" 552Return in 553.Fa fp 554the current 555.Nm editline 556file pointer for 557.Dq input 558.Fa fd 559= 560.Dv 0 , 561.Dq output 562.Fa fd 563= 564.Dv 1 , 565or 566.Dq error 567.Fa fd 568= 569.Dv 2 . 570.El 571.It Fn el_source 572Initialise 573.Nm 574by reading the contents of 575.Fa file . 576.Fn el_parse 577is called for each line in 578.Fa file . 579If 580.Fa file 581is 582.Dv NULL , 583try 584.Pa $PWD/.editrc 585then 586.Pa $HOME/.editrc . 587Refer to 588.Xr editrc 5 589for details on the format of 590.Fa file . 591.It Fn el_resize 592Must be called if the terminal size changes. 593If 594.Dv EL_SIGNAL 595has been set with 596.Fn el_set , 597then this is done automatically. 598Otherwise, it's the responsibility of the application to call 599.Fn el_resize 600on the appropriate occasions. 601.It Fn el_line 602Return the editing information for the current line in a 603.Fa LineInfo 604structure, which is defined as follows: 605.Bd -literal 606typedef struct lineinfo { 607 const char *buffer; /* address of buffer */ 608 const char *cursor; /* address of cursor */ 609 const char *lastchar; /* address of last character */ 610} LineInfo; 611.Ed 612.Pp 613.Fa buffer 614is not NUL terminated. 615This function may be called after 616.Fn el_gets 617to obtain the 618.Fa LineInfo 619structure pertaining to line returned by that function, 620and from within user defined functions added with 621.Dv EL_ADDFN . 622.It Fn el_insertstr 623Insert 624.Fa str 625into the line at the cursor. 626Returns \-1 if 627.Fa str 628is empty or won't fit, and 0 otherwise. 629.It Fn el_deletestr 630Delete 631.Fa count 632characters before the cursor. 633.El 634.Sh HISTORY LIST FUNCTIONS 635The history functions use a common data structure, 636.Fa History , 637which is created by 638.Fn history_init 639and freed by 640.Fn history_end . 641.Pp 642The following functions are available: 643.Bl -tag -width 4n 644.It Fn history_init 645Initialise the history list, and return a data structure 646to be used by all other history list functions. 647.It Fn history_end 648Clean up and finish with 649.Fa h , 650assumed to have been created with 651.Fn history_init . 652.It Fn history 653Perform operation 654.Fa op 655on the history list, with optional arguments as needed by the 656operation. 657.Fa ev 658is changed accordingly to operation. 659The following values for 660.Fa op 661are supported, along with the required argument list: 662.Bl -tag -width 4n 663.It Dv H_SETSIZE , Fa "int size" 664Set size of history to 665.Fa size 666elements. 667.It Dv H_GETSIZE 668Get number of events currently in history. 669.It Dv H_END 670Cleans up and finishes with 671.Fa h , 672assumed to be created with 673.Fn history_init . 674.It Dv H_CLEAR 675Clear the history. 676.It Dv H_FUNC , Fa "void *ptr" , Fa "history_gfun_t first" , \ 677Fa "history_gfun_t next" , Fa "history_gfun_t last" , \ 678Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \ 679Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \ 680Fa "history_efun_t enter" , Fa "history_efun_t add" 681Define functions to perform various history operations. 682.Fa ptr 683is the argument given to a function when it's invoked. 684.It Dv H_FIRST 685Return the first element in the history. 686.It Dv H_LAST 687Return the last element in the history. 688.It Dv H_PREV 689Return the previous element in the history. 690.It Dv H_NEXT 691Return the next element in the history. 692.It Dv H_CURR 693Return the current element in the history. 694.It Dv H_SET 695Set the cursor to point to the requested element. 696.It Dv H_ADD , Fa "const char *str" 697Append 698.Fa str 699to the current element of the history, or perform the 700.Dv H_ENTER 701operation with argument 702.Fa str 703if there is no current element. 704.It Dv H_APPEND , Fa "const char *str" 705Append 706.Fa str 707to the last new element of the history. 708.It Dv H_ENTER , Fa "const char *str" 709Add 710.Fa str 711as a new element to the history, and, if necessary, 712removing the oldest entry to keep the list to the created size. 713If 714.Dv H_SETUNIQUE 715was has been called with a non-zero arguments, the element 716will not be entered into the history if its contents match 717the ones of the current history element. 718If the element is entered 719.Fn history 720returns 1, if it is ignored as a duplicate returns 0. 721Finally 722.Fn history 723returns \-1 if an error occurred. 724.It Dv H_PREV_STR , Fa "const char *str" 725Return the closest previous event that starts with 726.Fa str . 727.It Dv H_NEXT_STR , Fa "const char *str" 728Return the closest next event that starts with 729.Fa str . 730.It Dv H_PREV_EVENT , Fa "int e" 731Return the previous event numbered 732.Fa e . 733.It Dv H_NEXT_EVENT , Fa "int e" 734Return the next event numbered 735.Fa e . 736.It Dv H_LOAD , Fa "const char *file" 737Load the history list stored in 738.Fa file . 739.It Dv H_SAVE , Fa "const char *file" 740Save the history list to 741.Fa file . 742.It Dv H_SETUNIQUE , Fa "int unique" 743Set flag that adjacent identical event strings should not be entered 744into the history. 745.It Dv H_GETUNIQUE 746Retrieve the current setting if adjacent identical elements should 747be entered into the history. 748.It Dv H_DEL , Fa "int e" 749Delete the event numbered 750.Fa e . 751This function is only provided for 752.Xr readline 3 753compatibility. 754The caller is responsible for free'ing the string in the returned 755.Fa HistEvent . 756.El 757.Pp 758.Fn history 759returns \*[Gt]= 0 if the operation 760.Fa op 761succeeds. 762Otherwise, \-1 is returned and 763.Fa ev 764is updated to contain more details about the error. 765.El 766.Sh TOKENIZATION FUNCTIONS 767The tokenization functions use a common data structure, 768.Fa Tokenizer , 769which is created by 770.Fn tok_init 771and freed by 772.Fn tok_end . 773.Pp 774The following functions are available: 775.Bl -tag -width 4n 776.It Fn tok_init 777Initialise the tokenizer, and return a data structure 778to be used by all other tokenizer functions. 779.Fa IFS 780contains the Input Field Separators, which defaults to 781.Aq space , 782.Aq tab , 783and 784.Aq newline 785if 786.Dv NULL . 787.It Fn tok_end 788Clean up and finish with 789.Fa t , 790assumed to have been created with 791.Fn tok_init . 792.It Fn tok_reset 793Reset the tokenizer state. 794Use after a line has been successfully tokenized 795by 796.Fn tok_line 797or 798.Fn tok_str 799and before a new line is to be tokenized. 800.It Fn tok_line 801Tokenize 802.Fa li , 803If successful, modify: 804.Fa argv 805to contain the words, 806.Fa argc 807to contain the number of words, 808.Fa cursorc 809(if not 810.Dv NULL ) 811to contain the index of the word containing the cursor, 812and 813.Fa cursoro 814(if not 815.Dv NULL ) 816to contain the offset within 817.Fa argv[cursorc] 818of the cursor. 819.Pp 820Returns 8210 if successful, 822\-1 for an internal error, 8231 for an unmatched single quote, 8242 for an unmatched double quote, 825and 8263 for a backslash quoted 827.Aq newline . 828A positive exit code indicates that another line should be read 829and tokenization attempted again. 830. 831.It Fn tok_str 832A simpler form of 833.Fn tok_line ; 834.Fa str 835is a NUL terminated string to tokenize. 836.El 837. 838.\"XXX.Sh EXAMPLES 839.\"XXX: provide some examples 840.Sh SEE ALSO 841.Xr sh 1 , 842.Xr signal 3 , 843.Xr termcap 3 , 844.Xr editrc 5 , 845.Xr termcap 5 846.Sh HISTORY 847The 848.Nm 849library first appeared in 850.Bx 4.4 . 851.Dv CC_REDISPLAY 852appeared in 853.Nx 1.3 . 854.Dv CC_REFRESH_BEEP , 855.Dv EL_EDITMODE 856and the readline emulation appeared in 857.Nx 1.4 . 858.Dv EL_RPROMPT 859appeared in 860.Nx 1.5 . 861.Sh AUTHORS 862The 863.Nm 864library was written by Christos Zoulas. 865Luke Mewburn wrote this manual and implemented 866.Dv CC_REDISPLAY , 867.Dv CC_REFRESH_BEEP , 868.Dv EL_EDITMODE , 869and 870.Dv EL_RPROMPT . 871Jaromir Dolecek implemented the readline emulation. 872Johny Mattsson implemented wide-character support. 873.Sh BUGS 874At this time, it is the responsibility of the caller to 875check the result of the 876.Dv EL_EDITMODE 877operation of 878.Fn el_get 879(after an 880.Fn el_source 881or 882.Fn el_parse ) 883to determine if 884.Nm 885should be used for further input. 886I.e., 887.Dv EL_EDITMODE 888is purely an indication of the result of the most recent 889.Xr editrc 5 890.Ic edit 891command. 892