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
214           described in editline(7).  If the queue overflows, for example due
215           to a recursive macro, or if an error occurs, for example because
216           wcs is NULL or memory allocation fails, the function beeps at the
217           user, 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
253                 embed 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
309                 entered.  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
344                 operation of editline.  At this time, it is the caller's
345                 responsibility 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_GETCFN, el_rfunc_t f
354                 Whenever reading a character, use the function
355                       int f(EditLine *e, wchar_t *wc)
356                 which stores the character in wc and returns 1 on success, 0
357                 on end of file, or -1 on I/O or encoding errors.  Functions
358                 internally using it include el_wgets(), el_wgetc(),
359                 el_gets(), and el_getc().  Initially, a builtin function is
360                 installed, and replacing it is discouraged because writing
361                 such a function is very error prone.  The builtin function
362                 can be restored at any time by passing the special value
363                 EL_BUILTIN_GETCFN instead of a function pointer.
364
365           EL_CLIENTDATA, void *data
366                 Register data to be associated with this EditLine structure.
367                 It can be retrieved with the corresponding el_get() call.
368
369           EL_SETFP, int fd, FILE *fp
370                 Set the current editline file pointer for “input” fd = 0,
371                 “output” fd = 1, or “error” fd = 2 from fp.
372
373     el_get()
374           Get editline parameters.  op determines which parameter to retrieve
375           into result.  Returns 0 if successful, -1 otherwise.
376
377           The following values for op are supported, along with actual type
378           of result:
379
380           EL_PROMPT, char *(*f)(EditLine *), char *c
381                 Set f to a pointer to the function that displays the prompt.
382                 If c is not NULL, set it to the start/stop literal prompt
383                 character.
384
385           EL_RPROMPT, char *(*f)(EditLine *), char *c
386                 Set f to a pointer to the function that displays the prompt.
387                 If c is not NULL, set it to the start/stop literal prompt
388                 character.
389
390           EL_EDITOR, const char **n
391                 Set the name of the editor in n, which will be one of “emacs”
392                 or “vi”.
393
394           EL_GETTC, const char *name, void *value
395                 If name is a valid termcap(5) capability set value to the
396                 current value of that capability.
397
398           EL_SIGNAL, int *s
399                 Set s to non-zero if editline has installed private signal
400                 handlers (see el_get() above).
401
402           EL_EDITMODE, int *c
403                 Set c to non-zero if editing is enabled.
404
405           EL_GETCFN, el_rfunc_t *f
406                 Set f to a pointer to the function that reads characters, or
407                 to EL_BUILTIN_GETCFN if the builtin function is in use.
408
409           EL_CLIENTDATA, void **data
410                 Set data to the previously registered client data set by an
411                 el_set() call.
412
413           EL_UNBUFFERED, int *c
414                 Set c to non-zero if unbuffered mode is enabled.
415
416           EL_GETFP, int fd, FILE **fp
417                 Set fp to the current editline file pointer for “input” fd =
418                 0, “output” fd = 1, or “error” fd = 2.
419
420     el_source()
421           Initialize editline by reading the contents of file.  el_parse() is
422           called for each line in file.  If file is NULL, try $EDITRC and if
423           that is not set $HOME/.editrc.  Refer to editrc(5) for details on
424           the format of file.  el_source() returns 0 on success and -1 on
425           error.
426
427     el_resize()
428           Must be called if the terminal size changes.  If EL_SIGNAL has been
429           set with el_set(), then this is done automatically.  Otherwise,
430           it's the responsibility of the application to call el_resize() on
431           the appropriate occasions.
432
433     el_cursor()
434           Move the cursor to the right (if positive) or to the left (if nega‐
435           tive) count characters.  Returns the resulting offset of the cursor
436           from the beginning of the line.
437
438     el_line()
439           Return the editing information for the current line in a LineInfo
440           structure, which is defined as follows:
441
442           typedef struct lineinfo {
443               const char *buffer;    /* address of buffer */
444               const char *cursor;    /* address of cursor */
445               const char *lastchar;  /* address of last character */
446           } LineInfo;
447
448           buffer is not NUL terminated.  This function may be called after
449           el_gets() to obtain the LineInfo structure pertaining to line
450           returned by that function, and from within user defined functions
451           added with EL_ADDFN.
452
453     el_insertstr()
454           Insert str into the line at the cursor.  Returns -1 if str is empty
455           or won't fit, and 0 otherwise.
456
457     el_deletestr()
458           Delete count characters before the cursor.
459

HISTORY LIST FUNCTIONS

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

TOKENIZATION FUNCTIONS

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

SEE ALSO

616     sh(1), signal(3), termcap(3), editrc(5), termcap(5), editline(7)
617

HISTORY

619     The editline library first appeared in 4.4BSD.  CC_REDISPLAY appeared in
620     NetBSD 1.3.  CC_REFRESH_BEEP, EL_EDITMODE and the readline emulation
621     appeared in NetBSD 1.4.  EL_RPROMPT appeared in NetBSD 1.5.
622

AUTHORS

624     The editline library was written by Christos Zoulas.  Luke Mewburn wrote
625     this manual and implemented CC_REDISPLAY, CC_REFRESH_BEEP, EL_EDITMODE,
626     and EL_RPROMPT.  Jaromir Dolecek implemented the readline emulation.
627     Johny Mattsson implemented wide-character support.
628

BUGS

630     At this time, it is the responsibility of the caller to check the result
631     of the EL_EDITMODE operation of el_get() (after an el_source() or
632     el_parse()) to determine if editline should be used for further input.
633     I.e., EL_EDITMODE is purely an indication of the result of the most
634     recent editrc(5) edit command.
635
636BSD                            November 9, 2018                            BSD
Impressum