1EDITLINE(3)              BSD Library Functions Manual              EDITLINE(3)
2

NAME

4     editline, el_init, el_init_fd, el_end, el_reset, el_gets, el_wgets,
5     el_getc, el_wgetc, el_push, el_wpush, el_parse, el_wparse, el_set,
6     el_wset, el_get, el_wget, el_source, el_resize, el_cursor, el_line,
7     el_wline, el_insertstr, el_winsertstr, el_deletestr, el_wdeletestr,
8     history_init, history_winit, history_end, history_wend, history,
9     history_w, tok_init, tok_winit, tok_end, tok_wend, tok_reset, tok_wreset,
10     tok_line, tok_wline, tok_str, tok_wstr — line editor, history and tok‐
11     enization functions
12

LIBRARY

14     Command Line Editor Library (libedit, -ledit)
15

SYNOPSIS

17     #include <histedit.h>
18
19     EditLine *
20     el_init(const char *prog, FILE *fin, FILE *fout, FILE *ferr);
21
22     EditLine *
23     el_init_fd(const char *prog, FILE *fin, FILE *fout, FILE *ferr, int fdin,
24         int fdout, int fderr);
25
26     void
27     el_end(EditLine *e);
28
29     void
30     el_reset(EditLine *e);
31
32     const char *
33     el_gets(EditLine *e, int *count);
34
35     const wchar_t *
36     el_wgets(EditLine *e, int *count);
37
38     int
39     el_getc(EditLine *e, char *ch);
40
41     int
42     el_wgetc(EditLine *e, wchar_t *wc);
43
44     void
45     el_push(EditLine *e, const char *mbs);
46
47     void
48     el_wpush(EditLine *e, const wchar_t *wcs);
49
50     int
51     el_parse(EditLine *e, int argc, const char *argv[]);
52
53     int
54     el_wparse(EditLine *e, int argc, const wchar_t *argv[]);
55
56     int
57     el_set(EditLine *e, int op, ...);
58
59     int
60     el_wset(EditLine *e, int op, ...);
61
62     int
63     el_get(EditLine *e, int op, ...);
64
65     int
66     el_wget(EditLine *e, int op, ...);
67
68     int
69     el_source(EditLine *e, const char *file);
70
71     void
72     el_resize(EditLine *e);
73
74     int
75     el_cursor(EditLine *e, int count);
76
77     const LineInfo *
78     el_line(EditLine *e);
79
80     const LineInfoW *
81     el_wline(EditLine *e);
82
83     int
84     el_insertstr(EditLine *e, const char *str);
85
86     int
87     el_winsertstr(EditLine *e, const wchar_t *str);
88
89     void
90     el_deletestr(EditLine *e, int count);
91
92     void
93     el_wdeletestr(EditLine *e, int count);
94
95     History *
96     history_init(void);
97
98     HistoryW *
99     history_winit(void);
100
101     void
102     history_end(History *h);
103
104     void
105     history_wend(HistoryW *h);
106
107     int
108     history(History *h, HistEvent *ev, int op, ...);
109
110     int
111     history_w(HistoryW *h, HistEventW *ev, int op, ...);
112
113     Tokenizer *
114     tok_init(const char *IFS);
115
116     TokenizerW *
117     tok_winit(const wchar_t *IFS);
118
119     void
120     tok_end(Tokenizer *t);
121
122     void
123     tok_wend(TokenizerW *t);
124
125     void
126     tok_reset(Tokenizer *t);
127
128     void
129     tok_wreset(TokenizerW *t);
130
131     int
132     tok_line(Tokenizer *t, const LineInfo *li, int *argc,
133         const char **argv[], int *cursorc, int *cursoro);
134
135     int
136     tok_wline(TokenizerW *t, const LineInfoW *li, int *argc,
137         const wchar_t **argv[], int *cursorc, int *cursoro);
138
139     int
140     tok_str(Tokenizer *t, const char *str, int *argc, const char **argv[]);
141
142     int
143     tok_wstr(TokenizerW *t, const wchar_t *str, int *argc,
144         const wchar_t **argv[]);
145

DESCRIPTION

147     The editline library provides generic line editing, history and tokeniza‐
148     tion functions, similar to those found in sh(1).
149
150     These functions are available in the libedit library (which needs the
151     libtermcap library).  Programs should be linked with -ledit -ltermcap.
152
153     The editline library respects the LC_CTYPE locale set by the application
154     program and never uses setlocale(3) to change the locale.
155

LINE EDITING FUNCTIONS

157     The line editing functions use a common data structure, EditLine, which
158     is created by el_init() or el_init_fd() and freed by el_end().
159
160     The wide-character functions behave the same way as their narrow counter‐
161     parts.
162
163     The following functions are available:
164
165     el_init()
166           Initialize the line editor, and return a data structure to be used
167           by all other line editing functions, or NULL on failure.  prog is
168           the name of the invoking program, used when reading the editrc(5)
169           file to determine which settings to use.  fin, fout and ferr are
170           the input, output, and error streams (respectively) to use.  In
171           this documentation, references to “the tty” are actually to this
172           input/output stream combination.
173
174     el_init_fd()
175           Like el_init() but allows specifying file descriptors for the
176           stdio(3) corresponding streams, in case those were created with
177           funopen(3).
178
179     el_end()
180           Clean up and finish with e, assumed to have been created with
181           el_init() or el_init_fd().
182
183     el_reset()
184           Reset the tty and the parser.  This should be called after an error
185           which may have upset the tty's state.
186
187     el_gets()
188           Read a line from the tty.  count is modified to contain the number
189           of characters read.  Returns the line read if successful, or NULL
190           if no characters were read or if an error occurred.  If an error
191           occurred, count is set to -1 and errno contains the error code that
192           caused it.  The return value may not remain valid across calls to
193           el_gets() and must be copied if the data is to be retained.
194
195     el_wgetc()
196           Read a wide character from the tty, respecting the current locale,
197           or from the input queue described in editline(7) if that is not
198           empty, and store it in wc.  If an invalid or incomplete character
199           is found, it is discarded, errno is set to EILSEQ, and the next
200           character is read and stored in wc.  Returns 1 if a valid character
201           was read, 0 on end of file, or -1 on read(2) failure.  In the lat‐
202           ter case, errno is set to indicate the error.
203
204     el_getc()
205           Read a wide character as described for el_wgetc() and return 0 on
206           end of file or -1 on failure.  If the wide character can be repre‐
207           sented as a single-byte character, convert it with wctob(3), store
208           the result in ch, and return 1; otherwise, set errno to ERANGE and
209           return -1.  In the C or POSIX locale, this simply reads a byte, but
210           for any other locale, including UTF-8, this is rarely useful.
211
212     el_wpush()
213           Push the wide character string wcs back onto the input queue de‐
214           scribed in editline(7).  If the queue overflows, for example due to
215           a recursive macro, or if an error occurs, for example because wcs
216           is NULL or memory allocation fails, the function beeps at the user,
217           but does not report the problem to the caller.
218
219     el_push()
220           Use the current locale to convert the multibyte string mbs to a
221           wide character string, and pass the result to el_wpush().
222
223     el_parse()
224           Parses the argv array (which is argc elements in size) to execute
225           builtin editline commands.  If the command is prefixed with “prog”:
226           then el_parse() will only execute the command if “prog” matches the
227           prog argument supplied to el_init().  The return value is -1 if the
228           command is unknown, 0 if there was no error or “prog” didn't match,
229           or 1 if the command returned an error.  Refer to editrc(5) for more
230           information.
231
232     el_set()
233           Set editline parameters.  op determines which parameter to set, and
234           each operation has its own parameter list.  Returns 0 on success,
235           -1 on failure.
236
237           The following values for op are supported, along with the required
238           argument list:
239
240           EL_PROMPT, char *(*f)(EditLine *)
241                 Define prompt printing function as f, which is to return a
242                 string that contains the prompt.
243
244           EL_PROMPT_ESC, char *(*f)(EditLine *), char c
245                 Same as EL_PROMPT, but the c argument indicates the
246                 start/stop literal prompt character.
247
248                 If a start/stop literal character is found in the prompt, the
249                 character itself is not printed, but characters after it are
250                 printed directly to the terminal without affecting the state
251                 of the current line.  A subsequent second start/stop literal
252                 character ends this behavior.  This is typically used to em‐
253                 bed literal escape sequences that change the color/style of
254                 the terminal in the prompt.  Note that the literal escape
255                 character cannot be the last character in the prompt, as the
256                 escape sequence is attached to the next character in the
257                 prompt.  0 unsets it.
258
259           EL_REFRESH
260                 Re-display the current line on the next terminal line.
261
262           EL_RPROMPT, char *(*f)(EditLine *)
263                 Define right side prompt printing function as f, which is to
264                 return a string that contains the prompt.
265
266           EL_RPROMPT_ESC, char *(*f)(EditLine *), char c
267                 Define the right prompt printing function but with a literal
268                 escape character.
269
270           EL_TERMINAL, const char *type
271                 Define terminal type of the tty to be type, or to TERM if
272                 type is NULL.
273
274           EL_EDITOR, const char *mode
275                 Set editing mode to mode, which must be one of “emacs” or
276                 “vi”.
277
278           EL_SIGNAL, int flag
279                 If flag is non-zero, editline will install its own signal
280                 handler for the following signals when reading command input:
281                 SIGCONT, SIGHUP, SIGINT, SIGQUIT, SIGSTOP, SIGTERM, SIGTSTP,
282                 and SIGWINCH.  Otherwise, the current signal handlers will be
283                 used.
284
285           EL_BIND, const char *, ..., NULL
286                 Perform the bind builtin command.  Refer to editrc(5) for
287                 more information.
288
289           EL_ECHOTC, const char *, ..., NULL
290                 Perform the echotc builtin command.  Refer to editrc(5) for
291                 more information.
292
293           EL_SETTC, const char *, ..., NULL
294                 Perform the settc builtin command.  Refer to editrc(5) for
295                 more information.
296
297           EL_SETTY, const char *, ..., NULL
298                 Perform the setty builtin command.  Refer to editrc(5) for
299                 more information.
300
301           EL_TELLTC, const char *, ..., NULL
302                 Perform the telltc builtin command.  Refer to editrc(5) for
303                 more information.
304
305           EL_ADDFN, const char *name, const char *help, unsigned char
306                 (*func)(EditLine *e, int ch)
307                 Add a user defined function, func(), referred to as name
308                 which is invoked when a key which is bound to name is en‐
309                 tered.  help is a description of name.  At invocation time,
310                 ch is the key which caused the invocation.  The return value
311                 of func() should be one of:
312
313                 CC_NORM       Add a normal character.
314
315                 CC_NEWLINE    End of line was entered.
316
317                 CC_EOF        EOF was entered.
318
319                 CC_ARGHACK    Expecting further command input as arguments,
320                               do nothing visually.
321
322                 CC_REFRESH    Refresh display.
323
324                 CC_REFRESH_BEEP
325                               Refresh display, and beep.
326
327                 CC_CURSOR     Cursor moved, so update and perform CC_REFRESH.
328
329                 CC_REDISPLAY  Redisplay entire input line.  This is useful if
330                               a key binding outputs extra information.
331
332                 CC_ERROR      An error occurred.  Beep, and flush tty.
333
334                 CC_FATAL      Fatal error, reset tty to known state.
335
336           EL_HIST, History *(*func)(History *, int op, ...), const char *ptr
337                 Defines which history function to use, which is usually
338                 history().  ptr should be the value returned by
339                 history_init().
340
341           EL_EDITMODE, int flag
342                 If flag is non-zero, editing is enabled (the default).  Note
343                 that this is only an indication, and does not affect the op‐
344                 eration of editline.  At this time, it is the caller's re‐
345                 sponsibility to check this (using el_get()) to determine if
346                 editing should be enabled or not.
347
348           EL_UNBUFFERED, int flag
349                 If flag is zero, unbuffered mode is disabled (the default).
350                 In unbuffered mode, el_gets() will return immediately after
351                 processing a single character.
352
353           EL_SAFEREAD, int flag
354                 If the flag argument is non-zero, then editline attempts to
355                 recover from read errors, ignoring the first interrrupted er‐
356                 ror, and trying to reset the input file descriptor to reset
357                 non-blocking I/O.  This is disabled by default, and desirable
358                 only when editline is used in shell-like applications.
359
360           EL_GETCFN, el_rfunc_t f
361                 Whenever reading a character, use the function
362                       int f(EditLine *e, wchar_t *wc)
363                 which stores the character in wc and returns 1 on success, 0
364                 on end of file, or -1 on I/O or encoding errors.  Functions
365                 internally using it include el_wgets(), el_wgetc(),
366                 el_gets(), and el_getc().  Initially, a builtin function is
367                 installed, and replacing it is discouraged because writing
368                 such a function is very error prone.  The builtin function
369                 can be restored at any time by passing the special value
370                 EL_BUILTIN_GETCFN instead of a function pointer.
371
372           EL_CLIENTDATA, void *data
373                 Register data to be associated with this EditLine structure.
374                 It can be retrieved with the corresponding el_get() call.
375
376           EL_SETFP, int fd, FILE *fp
377                 Set the current editline file pointer for “input” fd = 0,
378                 “output” fd = 1, or “error” fd = 2 from fp.
379
380     el_get()
381           Get editline parameters.  op determines which parameter to retrieve
382           into result.  Returns 0 if successful, -1 otherwise.
383
384           The following values for op are supported, along with actual type
385           of result:
386
387           EL_PROMPT, char *(*f)(EditLine *), char *c
388                 Set f to a pointer to the function that displays the prompt.
389                 If c is not NULL, set it to the start/stop literal prompt
390                 character.
391
392           EL_RPROMPT, char *(*f)(EditLine *), char *c
393                 Set f to a pointer to the function that displays the prompt.
394                 If c is not NULL, set it to the start/stop literal prompt
395                 character.
396
397           EL_EDITOR, const char **n
398                 Set the name of the editor in n, which will be one of “emacs”
399                 or “vi”.
400
401           EL_GETTC, const char *name, void *value
402                 If name is a valid termcap(5) capability set value to the
403                 current value of that capability.
404
405           EL_SIGNAL, int *s
406                 Set s to non-zero if editline has installed private signal
407                 handlers (see el_get() above).
408
409           EL_EDITMODE, int *c
410                 Set c to non-zero if editing is enabled.
411
412           EL_GETCFN, el_rfunc_t *f
413                 Set f to a pointer to the function that reads characters, or
414                 to EL_BUILTIN_GETCFN if the builtin function is in use.
415
416           EL_CLIENTDATA, void **data
417                 Set data to the previously registered client data set by an
418                 el_set() call.
419
420           EL_UNBUFFERED, int *c
421                 Set c to non-zero if unbuffered mode is enabled.
422
423           EL_SAFEREAD, int *c
424                 Set c to non-zero if safe read is set.
425
426           EL_GETFP, int fd, FILE **fp
427                 Set fp to the current editline file pointer for “input” fd =
428                 0, “output” fd = 1, or “error” fd = 2.
429
430     el_source()
431           Initialize editline by reading the contents of file.  el_parse() is
432           called for each line in file.  If file is NULL, try $EDITRC and if
433           that is not set $HOME/.editrc.  Refer to editrc(5) for details on
434           the format of file.  el_source() returns 0 on success and -1 on er‐
435           ror.
436
437     el_resize()
438           Must be called if the terminal size changes.  If EL_SIGNAL has been
439           set with el_set(), then this is done automatically.  Otherwise,
440           it's the responsibility of the application to call el_resize() on
441           the appropriate occasions.
442
443     el_cursor()
444           Move the cursor to the right (if positive) or to the left (if nega‐
445           tive) count characters.  Returns the resulting offset of the cursor
446           from the beginning of the line.
447
448     el_line()
449           Return the editing information for the current line in a LineInfo
450           structure, which is defined as follows:
451
452           typedef struct lineinfo {
453               const char *buffer;    /* address of buffer */
454               const char *cursor;    /* address of cursor */
455               const char *lastchar;  /* address of last character */
456           } LineInfo;
457
458           buffer is not NUL terminated.  This function may be called after
459           el_gets() to obtain the LineInfo structure pertaining to line re‐
460           turned by that function, and from within user defined functions
461           added with EL_ADDFN.
462
463     el_insertstr()
464           Insert str into the line at the cursor.  Returns -1 if str is empty
465           or won't fit, and 0 otherwise.
466
467     el_deletestr()
468           Delete count characters before the cursor.
469

HISTORY LIST FUNCTIONS

471     The history functions use a common data structure, History, which is cre‐
472     ated by history_init() and freed by history_end().
473
474     The following functions are available:
475
476     history_init()
477           Initialize the history list, and return a data structure to be used
478           by all other history list functions, or NULL on failure.
479
480     history_end()
481           Clean up and finish with h, assumed to have been created with
482           history_init().
483
484     history()
485           Perform operation op on the history list, with optional arguments
486           as needed by the operation.  ev is changed accordingly to opera‐
487           tion.  The following values for op are supported, along with the
488           required argument list:
489
490           H_SETSIZE, int size
491                 Set size of history to size elements.
492
493           H_GETSIZE
494                 Get number of events currently in history.
495
496           H_END
497                 Cleans up and finishes with h, assumed to be created with
498                 history_init().
499
500           H_CLEAR
501                 Clear the history.
502
503           H_FUNC, void *ptr, history_gfun_t first, history_gfun_t next,
504                 history_gfun_t last, history_gfun_t prev, history_gfun_t
505                 curr, history_sfun_t set, history_vfun_t clear,
506                 history_efun_t enter, history_efun_t add
507                 Define functions to perform various history operations.  ptr
508                 is the argument given to a function when it's invoked.
509
510           H_FIRST
511                 Return the first element in the history.
512
513           H_LAST
514                 Return the last element in the history.
515
516           H_PREV
517                 Return the previous element in the history.  It is newer than
518                 the current one.
519
520           H_NEXT
521                 Return the next element in the history.  It is older than the
522                 current one.
523
524           H_CURR
525                 Return the current element in the history.
526
527           H_SET, int position
528                 Set the cursor to point to the requested element.
529
530           H_ADD, const char *str
531                 Append str to the current element of the history, or perform
532                 the H_ENTER operation with argument str if there is no cur‐
533                 rent element.
534
535           H_APPEND, const char *str
536                 Append str to the last new element of the history.
537
538           H_ENTER, const char *str
539                 Add str as a new element to the history and, if necessary,
540                 removing the oldest entry to keep the list to the created
541                 size.  If H_SETUNIQUE has been called with a non-zero argu‐
542                 ment, the element will not be entered into the history if its
543                 contents match the ones of the current history element.  If
544                 the element is entered history() returns 1; if it is ignored
545                 as a duplicate returns 0.  Finally history() returns -1 if an
546                 error occurred.
547
548           H_PREV_STR, const char *str
549                 Return the closest previous event that starts with str.
550
551           H_NEXT_STR, const char *str
552                 Return the closest next event that starts with str.
553
554           H_PREV_EVENT, int e
555                 Return the previous event numbered e.
556
557           H_NEXT_EVENT, int e
558                 Return the next event numbered e.
559
560           H_LOAD, const char *file
561                 Load the history list stored in file.
562
563           H_SAVE, const char *file
564                 Save the history list to file.
565
566           H_SAVE_FP, FILE *fp
567                 Save the history list to the opened FILE pointer fp.
568
569           H_NSAVE_FP, size_t n, FILE *fp
570                 Save the last n history entries to the opened FILE pointer
571                 fp.
572
573           H_SETUNIQUE, int unique
574                 Set flag that adjacent identical event strings should not be
575                 entered into the history.
576
577           H_GETUNIQUE
578                 Retrieve the current setting if adjacent identical elements
579                 should be entered into the history.
580
581           H_DEL, int e
582                 Delete the event numbered e.  This function is only provided
583                 for readline compatibility.  The caller is responsible for
584                 free'ing the string in the returned HistEvent.
585
586           history() returns >= 0 if the operation op succeeds.  Otherwise, -1
587           is returned and ev is updated to contain more details about the er‐
588           ror.
589

TOKENIZATION FUNCTIONS

591     The tokenization functions use a common data structure, Tokenizer, which
592     is created by tok_init() and freed by tok_end().
593
594     The following functions are available:
595
596     tok_init()
597           Initialize the tokenizer, and return a data structure to be used by
598           all other tokenizer functions.  IFS contains the Input Field Sepa‐
599           rators, which defaults to ⟨space⟩, ⟨tab⟩, and ⟨newline⟩ if NULL.
600
601     tok_end()
602           Clean up and finish with t, assumed to have been created with
603           tok_init().
604
605     tok_reset()
606           Reset the tokenizer state.  Use after a line has been successfully
607           tokenized by tok_line() or tok_str() and before a new line is to be
608           tokenized.
609
610     tok_line()
611           Tokenize li, If successful, modify: argv to contain the words, argc
612           to contain the number of words, cursorc (if not NULL) to contain
613           the index of the word containing the cursor, and cursoro (if not
614           NULL) to contain the offset within argv[cursorc] of the cursor.
615
616           Returns 0 if successful, -1 for an internal error, 1 for an un‐
617           matched single quote, 2 for an unmatched double quote, and 3 for a
618           backslash quoted ⟨newline⟩.  A positive exit code indicates that
619           another line should be read and tokenization attempted again.
620
621     tok_str()
622           A simpler form of tok_line(); str is a NUL terminated string to to‐
623           kenize.
624

SEE ALSO

626     sh(1), signal(3), termcap(3), editrc(5), termcap(5), editline(7)
627

HISTORY

629     The editline library first appeared in 4.4BSD.  CC_REDISPLAY appeared in
630     NetBSD 1.3.  CC_REFRESH_BEEP, EL_EDITMODE and the readline emulation ap‐
631     peared in NetBSD 1.4.  EL_RPROMPT appeared in NetBSD 1.5.
632

AUTHORS

634     The editline library was written by Christos Zoulas.  Luke Mewburn wrote
635     this manual and implemented CC_REDISPLAY, CC_REFRESH_BEEP, EL_EDITMODE,
636     and EL_RPROMPT.  Jaromir Dolecek implemented the readline emulation.
637     Johny Mattsson implemented wide-character support.
638

BUGS

640     At this time, it is the responsibility of the caller to check the result
641     of the EL_EDITMODE operation of el_get() (after an el_source() or
642     el_parse()) to determine if editline should be used for further input.
643     I.e., EL_EDITMODE is purely an indication of the result of the most re‐
644     cent editrc(5) edit command.
645
646BSD                             August 15, 2021                            BSD
Impressum