Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/el_wgetc.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 .TH EDITLINE 3 "August 15, 2021" ""
2 .SH NAME
3 \fBeditline\fP,
4 \fBel_init\fP,
5 \fBel_init_fd\fP,
6 \fBel_end\fP,
7 \fBel_reset\fP,
8 \fBel_gets\fP,
9 \fBel_wgets\fP,
10 \fBel_getc\fP,
11 \fBel_wgetc\fP,
12 \fBel_push\fP,
13 \fBel_wpush\fP,
14 \fBel_parse\fP,
15 \fBel_wparse\fP,
16 \fBel_set\fP,
17 \fBel_wset\fP,
18 \fBel_get\fP,
19 \fBel_wget\fP,
20 \fBel_source\fP,
21 \fBel_resize\fP,
22 \fBel_cursor\fP,
23 \fBel_line\fP,
24 \fBel_wline\fP,
25 \fBel_insertstr\fP,
26 \fBel_winsertstr\fP,
27 \fBel_deletestr\fP,
28 \fBel_wdeletestr\fP,
29 \fBhistory_init\fP,
30 \fBhistory_winit\fP,
31 \fBhistory_end\fP,
32 \fBhistory_wend\fP,
33 \fBhistory\fP,
34 \fBhistory_w\fP,
35 \fBtok_init\fP,
36 \fBtok_winit\fP,
37 \fBtok_end\fP,
38 \fBtok_wend\fP,
39 \fBtok_reset\fP,
40 \fBtok_wreset\fP,
41 \fBtok_line\fP,
42 \fBtok_wline\fP,
43 \fBtok_str\fP,
44 \fBtok_wstr\fP
45 \- line editor, history and tokenization functions
46 .SH LIBRARY
47 Command Line Editor Library (libedit, -ledit)
48 .SH SYNOPSIS
49 .PP
50 \fB#include <histedit.h>\fP
51 .PP
52 \fIEditLine *\fP
53 .br
54 \fBel_init\fP(\fIconst char *prog\fP, \fIFILE *fin\fP, \fIFILE *fout\fP, \fIFILE *ferr\fP);
55 .PP
56 \fIEditLine *\fP
57 .br
58 \fBel_init_fd\fP(\fIconst char *prog\fP, \fIFILE *fin\fP, \fIFILE *fout\fP, \fIFILE *ferr\fP, \fIint fdin\fP, \fIint fdout\fP, \fIint fderr\fP);
59 .PP
60 \fIvoid\fP
61 .br
62 \fBel_end\fP(\fIEditLine *e\fP);
63 .PP
64 \fIvoid\fP
65 .br
66 \fBel_reset\fP(\fIEditLine *e\fP);
67 .PP
68 \fIconst char *\fP
69 .br
70 \fBel_gets\fP(\fIEditLine *e\fP, \fIint *count\fP);
71 .PP
72 \fIconst wchar_t *\fP
73 .br
74 \fBel_wgets\fP(\fIEditLine *e\fP, \fIint *count\fP);
75 .PP
76 \fIint\fP
77 .br
78 \fBel_getc\fP(\fIEditLine *e\fP, \fIchar *ch\fP);
79 .PP
80 \fIint\fP
81 .br
82 \fBel_wgetc\fP(\fIEditLine *e\fP, \fIwchar_t *wc\fP);
83 .PP
84 \fIvoid\fP
85 .br
86 \fBel_push\fP(\fIEditLine *e\fP, \fIconst char *mbs\fP);
87 .PP
88 \fIvoid\fP
89 .br
90 \fBel_wpush\fP(\fIEditLine *e\fP, \fIconst wchar_t *wcs\fP);
91 .PP
92 \fIint\fP
93 .br
94 \fBel_parse\fP(\fIEditLine *e\fP, \fIint argc\fP, \fIconst char *argv[]\fP);
95 .PP
96 \fIint\fP
97 .br
98 \fBel_wparse\fP(\fIEditLine *e\fP, \fIint argc\fP, \fIconst wchar_t *argv[]\fP);
99 .PP
100 \fIint\fP
101 .br
102 \fBel_set\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
103 .PP
104 \fIint\fP
105 .br
106 \fBel_wset\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
107 .PP
108 \fIint\fP
109 .br
110 \fBel_get\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
111 .PP
112 \fIint\fP
113 .br
114 \fBel_wget\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
115 .PP
116 \fIint\fP
117 .br
118 \fBel_source\fP(\fIEditLine *e\fP, \fIconst char *file\fP);
119 .PP
120 \fIvoid\fP
121 .br
122 \fBel_resize\fP(\fIEditLine *e\fP);
123 .PP
124 \fIint\fP
125 .br
126 \fBel_cursor\fP(\fIEditLine *e\fP, \fIint count\fP);
127 .PP
128 \fIconst LineInfo *\fP
129 .br
130 \fBel_line\fP(\fIEditLine *e\fP);
131 .PP
132 \fIconst LineInfoW *\fP
133 .br
134 \fBel_wline\fP(\fIEditLine *e\fP);
135 .PP
136 \fIint\fP
137 .br
138 \fBel_insertstr\fP(\fIEditLine *e\fP, \fIconst char *str\fP);
139 .PP
140 \fIint\fP
141 .br
142 \fBel_winsertstr\fP(\fIEditLine *e\fP, \fIconst wchar_t *str\fP);
143 .PP
144 \fIvoid\fP
145 .br
146 \fBel_deletestr\fP(\fIEditLine *e\fP, \fIint count\fP);
147 .PP
148 \fIvoid\fP
149 .br
150 \fBel_wdeletestr\fP(\fIEditLine *e\fP, \fIint count\fP);
151 .PP
152 \fIHistory *\fP
153 .br
154 \fBhistory_init\fP(void );
155 .PP
156 \fIHistoryW *\fP
157 .br
158 \fBhistory_winit\fP(void );
159 .PP
160 \fIvoid\fP
161 .br
162 \fBhistory_end\fP(\fIHistory *h\fP);
163 .PP
164 \fIvoid\fP
165 .br
166 \fBhistory_wend\fP(\fIHistoryW *h\fP);
167 .PP
168 \fIint\fP
169 .br
170 \fBhistory\fP(\fIHistory *h\fP, \fIHistEvent *ev\fP, \fIint op\fP, \fI...\fP);
171 .PP
172 \fIint\fP
173 .br
174 \fBhistory_w\fP(\fIHistoryW *h\fP, \fIHistEventW *ev\fP, \fIint op\fP, \fI...\fP);
175 .PP
176 \fITokenizer *\fP
177 .br
178 \fBtok_init\fP(\fIconst char *IFS\fP);
179 .PP
180 \fITokenizerW *\fP
181 .br
182 \fBtok_winit\fP(\fIconst wchar_t *IFS\fP);
183 .PP
184 \fIvoid\fP
185 .br
186 \fBtok_end\fP(\fITokenizer *t\fP);
187 .PP
188 \fIvoid\fP
189 .br
190 \fBtok_wend\fP(\fITokenizerW *t\fP);
191 .PP
192 \fIvoid\fP
193 .br
194 \fBtok_reset\fP(\fITokenizer *t\fP);
195 .PP
196 \fIvoid\fP
197 .br
198 \fBtok_wreset\fP(\fITokenizerW *t\fP);
199 .PP
200 \fIint\fP
201 .br
202 \fBtok_line\fP(\fITokenizer *t\fP, \fIconst LineInfo *li\fP, \fIint *argc\fP, \fIconst char **argv[]\fP, \fIint *cursorc\fP, \fIint *cursoro\fP);
203 .PP
204 \fIint\fP
205 .br
206 \fBtok_wline\fP(\fITokenizerW *t\fP, \fIconst LineInfoW *li\fP, \fIint *argc\fP, \fIconst wchar_t **argv[]\fP, \fIint *cursorc\fP, \fIint *cursoro\fP);
207 .PP
208 \fIint\fP
209 .br
210 \fBtok_str\fP(\fITokenizer *t\fP, \fIconst char *str\fP, \fIint *argc\fP, \fIconst char **argv[]\fP);
211 .PP
212 \fIint\fP
213 .br
214 \fBtok_wstr\fP(\fITokenizerW *t\fP, \fIconst wchar_t *str\fP, \fIint *argc\fP, \fIconst wchar_t **argv[]\fP);
215 .SH DESCRIPTION
216 The
217 \fBeditline\fP
218 library provides generic line editing, history and tokenization functions,
219 similar to those found in
220 \fBsh\fP(1).
221
222 These functions are available in the
223 \fBlibedit\fP
224 library (which needs the
225 \fBlibtermcap\fP
226 library).
227 Programs should be linked with
228 \fB\-ledit\fP ltermcap .
229
230 The
231 \fBeditline\fP
232 library respects the
233 .IR LC_CTYPE
234 locale set by the application program and never uses
235 \fBsetlocale\fP(3)
236 to change the locale.
237 .SH LINE EDITING FUNCTIONS
238 The line editing functions use a common data structure,
239 \fIEditLine\fP,
240 which is created by
241 \fBel_init\fP()
242 or
243 \fBel_init_fd\fP()
244 and freed by
245 \fBel_end\fP().
246
247 The wide-character functions behave the same way as their narrow
248 counterparts.
249
250 The following functions are available:
251 .TP
252 \fBel_init\fP()
253 Initialize the line editor, and return a data structure
254 to be used by all other line editing functions, or
255 NULL
256 on failure.
257 \fIprog \fP
258 is the name of the invoking program, used when reading the
259 \fBeditrc\fP(5)
260 file to determine which settings to use.
261 \fIfin\fP,
262 \fIfout \fP
263 and
264 \fIferr \fP
265 are the input, output, and error streams (respectively) to use.
266 In this documentation, references to
267 ``the tty''
268 are actually to this input/output stream combination.
269 .TP
270 \fBel_init_fd\fP()
271 Like
272 \fBel_init\fP()
273 but allows specifying file descriptors for the
274 \fBstdio\fP(3)
275 corresponding streams, in case those were created with
276 \fBfunopen\fP(3).
277 .TP
278 \fBel_end\fP()
279 Clean up and finish with
280 \fIe\fP,
281 assumed to have been created with
282 \fBel_init\fP()
283 or
284 \fBel_init_fd\fP().
285 .TP
286 \fBel_reset\fP()
287 Reset the tty and the parser.
288 This should be called after an error which may have upset the tty's
289 state.
290 .TP
291 \fBel_gets\fP()
292 Read a line from the tty.
293 \fIcount \fP
294 is modified to contain the number of characters read.
295 Returns the line read if successful, or
296 NULL
297 if no characters were read or if an error occurred.
298 If an error occurred,
299 \fIcount \fP
300 is set to \-1 and
301 errno
302 contains the error code that caused it.
303 The return value may not remain valid across calls to
304 \fBel_gets\fP()
305 and must be copied if the data is to be retained.
306 .TP
307 \fBel_wgetc\fP()
308 Read a wide character from the tty, respecting the current locale,
309 or from the input queue described in
310 \fBeditline\fP(7)
311 if that is not empty, and store it in
312 \fIwc\fP.
313 If an invalid or incomplete character is found, it is discarded,
314 \fIerrno\fP
315 is set to
316 Er EILSEQ ,
317 and the next character is read and stored in
318 \fIwc\fP.
319 Returns 1 if a valid character was read, 0 on end of file, or \-1 on
320 \fBread\fP(2)
321 failure.
322 In the latter case,
323 \fIerrno\fP
324 is set to indicate the error.
325 .TP
326 \fBel_getc\fP()
327 Read a wide character as described for
328 \fBel_wgetc\fP()
329 and return 0 on end of file or \-1 on failure.
330 If the wide character can be represented as a single-byte character,
331 convert it with
332 \fBwctob\fP(3),
333 store the result in
334 \fIch\fP,
335 and return 1; otherwise, set
336 \fIerrno\fP
337 to
338 Er ERANGE
339 and return \-1.
340 In the C or POSIX locale, this simply reads a byte, but for any other
341 locale, including UTF-8, this is rarely useful.
342 .TP
343 \fBel_wpush\fP()
344 Push the wide character string
345 \fIwcs \fP
346 back onto the input queue described in
347 \fBeditline\fP(7).
348 If the queue overflows, for example due to a recursive macro,
349 or if an error occurs, for example because
350 \fIwcs \fP
351 is
352 NULL
353 or memory allocation fails, the function beeps at the user,
354 but does not report the problem to the caller.
355 .TP
356 \fBel_push\fP()
357 Use the current locale to convert the multibyte string
358 \fImbs \fP
359 to a wide character string, and pass the result to
360 \fBel_wpush\fP().
361 .TP
362 \fBel_parse\fP()
363 Parses the
364 \fIargv \fP
365 array (which is
366 \fIargc \fP
367 elements in size)
368 to execute builtin
369 \fBeditline\fP
370 commands.
371 If the command is prefixed with
372 ``prog :''
373 then
374 \fBel_parse\fP()
375 will only execute the command if
376 ``prog''
377 matches the
378 \fIprog \fP
379 argument supplied to
380 \fBel_init\fP().
381 The return value is
382 \-1 if the command is unknown,
383 0 if there was no error or
384 ``prog''
385 didn't match, or
386 1 if the command returned an error.
387 Refer to
388 \fBeditrc\fP(5)
389 for more information.
390 .TP
391 \fBel_set\fP()
392 Set
393 \fBeditline\fP
394 parameters.
395 \fIop \fP
396 determines which parameter to set, and each operation has its
397 own parameter list.
398 Returns 0 on success, \-1 on failure.
399
400 The following values for
401 \fIop \fP
402 are supported, along with the required argument list:
403 .RS
404 .TP
405 EL_PROMPT , \fIchar *(*f)(EditLine *)\fP
406 Define prompt printing function as
407 \fIf\fP,
408 which is to return a string that contains the prompt.
409 .TP
410 EL_PROMPT_ESC , \fIchar *(*f)(EditLine *), Fa char c\fP
411 Same as
412 EL_PROMPT ,
413 but the
414 \fIc \fP
415 argument indicates the start/stop literal prompt character.
416
417 If a start/stop literal character is found in the prompt, the
418 character itself
419 is not printed, but characters after it are printed directly to the
420 terminal without affecting the state of the current line.
421 A subsequent second start/stop literal character ends this behavior.
422 This is typically used to embed literal escape sequences that change the
423 color/style of the terminal in the prompt.
424 Note that the literal escape character cannot be the last character in the
425 prompt, as the escape sequence is attached to the next character in the prompt.
426 0
427 unsets it.
428 .TP
429 EL_REFRESH
430 Re-display the current line on the next terminal line.
431 .TP
432 EL_RPROMPT , \fIchar *(*f)(EditLine *)\fP
433 Define right side prompt printing function as
434 \fIf\fP,
435 which is to return a string that contains the prompt.
436 .TP
437 EL_RPROMPT_ESC , \fIchar *(*f)(EditLine *), Fa char c\fP
438 Define the right prompt printing function but with a literal escape character.
439 .TP
440 EL_TERMINAL , \fIconst char *type\fP
441 Define terminal type of the tty to be
442 \fItype\fP,
443 or to
444 .IR TERM
445 if
446 \fItype \fP
447 is
448 NULL .
449 .TP
450 EL_EDITOR , \fIconst char *mode\fP
451 Set editing mode to
452 \fImode\fP,
453 which must be one of
454 ``emacs''
455 or
456 ``vi''.
457 .TP
458 EL_SIGNAL , \fIint flag\fP
459 If
460 \fIflag \fP
461 is non-zero,
462 \fBeditline\fP
463 will install its own signal handler for the following signals when
464 reading command input:
465 SIGCONT ,
466 SIGHUP ,
467 SIGINT ,
468 SIGQUIT ,
469 SIGSTOP ,
470 SIGTERM ,
471 SIGTSTP ,
472 and
473 SIGWINCH .
474 Otherwise, the current signal handlers will be used.
475 .TP
476 EL_BIND , \fIconst char *, Fa ..., Dv NULL \fP
477 Perform the
478 \fBbind\fP
479 builtin command.
480 Refer to
481 \fBeditrc\fP(5)
482 for more information.
483 .TP
484 EL_ECHOTC , \fIconst char *, Fa ..., Dv NULL \fP
485 Perform the
486 \fBechotc\fP
487 builtin command.
488 Refer to
489 \fBeditrc\fP(5)
490 for more information.
491 .TP
492 EL_SETTC , \fIconst char *, Fa ..., Dv NULL \fP
493 Perform the
494 \fBsettc\fP
495 builtin command.
496 Refer to
497 \fBeditrc\fP(5)
498 for more information.
499 .TP
500 EL_SETTY , \fIconst char *, Fa ..., Dv NULL \fP
501 Perform the
502 \fBsetty\fP
503 builtin command.
504 Refer to
505 \fBeditrc\fP(5)
506 for more information.
507 .TP
508 EL_TELLTC , \fIconst char *, Fa ..., Dv NULL \fP
509 Perform the
510 \fBtelltc\fP
511 builtin command.
512 Refer to
513 \fBeditrc\fP(5)
514 for more information.
515 .TP
516 EL_ADDFN , \fIconst char *name, Fa const char *help, \ \fP
517 Fa "unsigned char (*func)(EditLine *e, int ch)"
518 Add a user defined function,
519 \fBfunc\fP(),
520 referred to as
521 \fIname \fP
522 which is invoked when a key which is bound to
523 \fIname \fP
524 is entered.
525 \fIhelp \fP
526 is a description of
527 \fIname\fP.
528 At invocation time,
529 \fIch \fP
530 is the key which caused the invocation.
531 The return value of
532 \fBfunc\fP()
533 should be one of:
534 .RS
535 .TP
536 CC_NORM
537 Add a normal character.
538 .TP
539 CC_NEWLINE
540 End of line was entered.
541 .TP
542 CC_EOF
543 EOF was entered.
544 .TP
545 CC_ARGHACK
546 Expecting further command input as arguments, do nothing visually.
547 .TP
548 CC_REFRESH
549 Refresh display.
550 .TP
551 CC_REFRESH_BEEP
552 Refresh display, and beep.
553 .TP
554 CC_CURSOR
555 Cursor moved, so update and perform
556 CC_REFRESH .
557 .TP
558 CC_REDISPLAY
559 Redisplay entire input line.
560 This is useful if a key binding outputs extra information.
561 .TP
562 CC_ERROR
563 An error occurred.
564 Beep, and flush tty.
565 .TP
566 CC_FATAL
567 Fatal error, reset tty to known state.
568 .RE
569 .TP
570 EL_HIST , \fIHistory *(*func)(History *, int op, ...), \ \fP
571 Fa "const char *ptr"
572 Defines which history function to use, which is usually
573 \fBhistory\fP().
574 \fIptr \fP
575 should be the value returned by
576 \fBhistory_init\fP().
577 .TP
578 EL_EDITMODE , \fIint flag\fP
579 If
580 \fIflag \fP
581 is non-zero,
582 editing is enabled (the default).
583 Note that this is only an indication, and does not
584 affect the operation of
585 \fB.\fP
586 At this time, it is the caller's responsibility to
587 check this
588 (using
589 \fBel_get\fP() )
590 to determine if editing should be enabled or not.
591 .TP
592 EL_UNBUFFERED , \fIint flag\fP
593 If
594 \fIflag \fP
595 is zero,
596 unbuffered mode is disabled (the default).
597 In unbuffered mode,
598 \fBel_gets\fP()
599 will return immediately after processing a single character.
600 .TP
601 EL_SAFEREAD , \fIint flag\fP
602 If the
603 \fIflag \fP
604 argument is non-zero, then
605 \fBeditline\fP
606 attempts to recover from read errors, ignoring the first interrupted
607 error, and trying to reset the input file descriptor to reset non-blocking I/O.
608 This is disabled by default, and desirable only when
609 \fBeditline\fP
610 is used in shell-like applications.
611 .TP
612 EL_GETCFN , \fIel_rfunc_t f\fP
613 Whenever reading a character, use the function
614 -ragged -offset indent -compact
615 .PP
616 \fIint\fP
617 .br
618 Fo f
619 \fIEditLine *e\fP
620 \fIwchar_t *wc\fP
621 Fc
622 which stores the character in
623 \fIwc \fP
624 and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding
625 errors.
626 Functions internally using it include
627 \fBel_wgets\fP(),
628 \fBel_wgetc\fP(),
629 \fBel_gets\fP(),
630 and
631 \fBel_getc\fP().
632 Initially, a builtin function is installed, and replacing it
633 is discouraged because writing such a function is very error prone.
634 The builtin function can be restored at any time by passing the
635 special value
636 EL_BUILTIN_GETCFN
637 instead of a function pointer.
638 .TP
639 EL_CLIENTDATA , \fIvoid *data\fP
640 Register
641 \fIdata \fP
642 to be associated with this EditLine structure.
643 It can be retrieved with the corresponding
644 \fBel_get\fP();
645 call.
646 .TP
647 EL_SETFP , \fIint fd, Fa FILE *fp\fP
648 Set the current
649 \fBeditline\fP
650 file pointer for
651 ``input''
652 \fIfd \fP
653 =
654 0 ,
655 ``output''
656 \fIfd \fP
657 =
658 1 ,
659 or
660 ``error''
661 \fIfd \fP
662 =
663 2
664 from
665 \fIfp\fP.
666 .RE
667 .TP
668 \fBel_get\fP()
669 Get
670 \fBeditline\fP
671 parameters.
672 \fIop \fP
673 determines which parameter to retrieve into
674 \fIresult\fP.
675 Returns 0 if successful, \-1 otherwise.
676
677 The following values for
678 \fIop \fP
679 are supported, along with actual type of
680 \fIresult : \fP
681 .RS
682 .TP
683 EL_PROMPT , \fIchar *(*f)(EditLine *), Fa char *c\fP
684 Set
685 \fIf \fP
686 to a pointer to the function that displays the prompt.
687 If
688 \fIc \fP
689 is not
690 NULL ,
691 set it to the start/stop literal prompt character.
692 .TP
693 EL_RPROMPT , \fIchar *(*f)(EditLine *), Fa char *c\fP
694 Set
695 \fIf \fP
696 to a pointer to the function that displays the prompt.
697 If
698 \fIc \fP
699 is not
700 NULL ,
701 set it to the start/stop literal prompt character.
702 .TP
703 EL_EDITOR , \fIconst char **n\fP
704 Set the name of the editor in
705 \fIn\fP,
706 which will be one of
707 ``emacs''
708 or
709 ``vi''.
710 .TP
711 EL_GETTC , \fIconst char *name, Fa void *value\fP
712 If
713 \fIname \fP
714 is a valid
715 \fBtermcap\fP(5)
716 capability set
717 \fIvalue \fP
718 to the current value of that capability.
719 .TP
720 EL_SIGNAL , \fIint *s\fP
721 Set
722 \fIs \fP
723 to non-zero if
724 \fBeditline\fP
725 has installed private signal handlers (see
726 \fBel_get\fP()
727 above).
728 .TP
729 EL_EDITMODE , \fIint *c\fP
730 Set
731 \fIc \fP
732 to non-zero if editing is enabled.
733 .TP
734 EL_GETCFN , \fIel_rfunc_t *f\fP
735 Set
736 \fIf \fP
737 to a pointer to the function that reads characters, or to
738 EL_BUILTIN_GETCFN
739 if the builtin function is in use.
740 .TP
741 EL_CLIENTDATA , \fIvoid **data\fP
742 Set
743 \fIdata \fP
744 to the previously registered client data set by an
745 \fBel_set\fP()
746 call.
747 .TP
748 EL_UNBUFFERED , \fIint *c\fP
749 Set
750 \fIc \fP
751 to non-zero if unbuffered mode is enabled.
752 .TP
753 EL_SAFEREAD , \fIint *c\fP
754 Set
755 \fIc \fP
756 to non-zero if safe read is set.
757 .TP
758 EL_GETFP , \fIint fd", Fa FILE **fp\fP
759 Set
760 \fIfp \fP
761 to the current
762 \fBeditline\fP
763 file pointer for
764 ``input''
765 \fIfd \fP
766 =
767 0 ,
768 ``output''
769 \fIfd \fP
770 =
771 1 ,
772 or
773 ``error''
774 \fIfd \fP
775 =
776 2 .
777 .RE
778 .TP
779 \fBel_source\fP()
780 Initialize
781 \fBeditline\fP
782 by reading the contents of
783 \fIfile\fP.
784 \fBel_parse\fP()
785 is called for each line in
786 \fIfile\fP.
787 If
788 \fIfile \fP
789 is
790 NULL ,
791 try
792 \fI$EDITRC\fP
793 and if that is not set
794 \fI$HOME/.editrc\fP.
795 Refer to
796 \fBeditrc\fP(5)
797 for details on the format of
798 \fIfile\fP.
799 \fBel_source\fP()
800 returns 0 on success and \-1 on error.
801 .TP
802 \fBel_resize\fP()
803 Must be called if the terminal size changes.
804 If
805 EL_SIGNAL
806 has been set with
807 \fBel_set\fP(),
808 then this is done automatically.
809 Otherwise, it's the responsibility of the application to call
810 \fBel_resize\fP()
811 on the appropriate occasions.
812 .TP
813 \fBel_cursor\fP()
814 Move the cursor to the right (if positive) or to the left (if negative)
815 \fIcount \fP
816 characters.
817 Returns the resulting offset of the cursor from the beginning of the line.
818 .TP
819 \fBel_line\fP()
820 Return the editing information for the current line in a
821 \fILineInfo \fP
822 structure, which is defined as follows:
823
824 typedef struct lineinfo {
825 .br
826 const char *buffer; /* address of buffer */
827 .br
828 const char *cursor; /* address of cursor */
829 .br
830 const char *lastchar; /* address of last character */
831 .br
832 } LineInfo;
833 .br
834
835 \fIbuffer \fP
836 is not NUL terminated.
837 This function may be called after
838 \fBel_gets\fP()
839 to obtain the
840 \fILineInfo \fP
841 structure pertaining to line returned by that function,
842 and from within user defined functions added with
843 EL_ADDFN .
844 .TP
845 \fBel_insertstr\fP()
846 Insert
847 \fIstr \fP
848 into the line at the cursor.
849 Returns \-1 if
850 \fIstr \fP
851 is empty or won't fit, and 0 otherwise.
852 .TP
853 \fBel_deletestr\fP()
854 Delete
855 \fIcount \fP
856 characters before the cursor.
857 .SH HISTORY LIST FUNCTIONS
858 The history functions use a common data structure,
859 \fIHistory\fP,
860 which is created by
861 \fBhistory_init\fP()
862 and freed by
863 \fBhistory_end\fP().
864
865 The following functions are available:
866 .TP
867 \fBhistory_init\fP()
868 Initialize the history list, and return a data structure
869 to be used by all other history list functions, or
870 NULL
871 on failure.
872 .TP
873 \fBhistory_end\fP()
874 Clean up and finish with
875 \fIh\fP,
876 assumed to have been created with
877 \fBhistory_init\fP().
878 .TP
879 \fBhistory\fP()
880 Perform operation
881 \fIop \fP
882 on the history list, with optional arguments as needed by the
883 operation.
884 \fIev \fP
885 is changed accordingly to operation.
886 The following values for
887 \fIop \fP
888 are supported, along with the required argument list:
889 .RS
890 .TP
891 H_SETSIZE , \fIint size\fP
892 Set size of history to
893 \fIsize \fP
894 elements.
895 .TP
896 H_GETSIZE
897 Get number of events currently in history.
898 .TP
899 H_END
900 Cleans up and finishes with
901 \fIh\fP,
902 assumed to be created with
903 \fBhistory_init\fP().
904 .TP
905 H_CLEAR
906 Clear the history.
907 .TP
908 H_FUNC , \fIvoid *ptr, Fa history_gfun_t first, \ \fP
909 Fa "history_gfun_t next" , Fa "history_gfun_t last" , \
910 Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \
911 Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \
912 Fa "history_efun_t enter" , Fa "history_efun_t add"
913 Define functions to perform various history operations.
914 \fIptr \fP
915 is the argument given to a function when it's invoked.
916 .TP
917 H_FIRST
918 Return the first element in the history.
919 .TP
920 H_LAST
921 Return the last element in the history.
922 .TP
923 H_PREV
924 Return the previous element in the history.
925 It is newer than the current one.
926 .TP
927 H_NEXT
928 Return the next element in the history.
929 It is older than the current one.
930 .TP
931 H_CURR
932 Return the current element in the history.
933 .TP
934 H_SET , \fIint position\fP
935 Set the cursor to point to the requested element.
936 .TP
937 H_ADD , \fIconst char *str\fP
938 Append
939 \fIstr \fP
940 to the current element of the history, or perform the
941 H_ENTER
942 operation with argument
943 \fIstr \fP
944 if there is no current element.
945 .TP
946 H_APPEND , \fIconst char *str\fP
947 Append
948 \fIstr \fP
949 to the last new element of the history.
950 .TP
951 H_ENTER , \fIconst char *str\fP
952 Add
953 \fIstr \fP
954 as a new element to the history and, if necessary,
955 removing the oldest entry to keep the list to the created size.
956 If
957 H_SETUNIQUE
958 has been called with a non-zero argument, the element
959 will not be entered into the history if its contents match
960 the ones of the current history element.
961 If the element is entered
962 \fBhistory\fP()
963 returns 1; if it is ignored as a duplicate returns 0.
964 Finally
965 \fBhistory\fP()
966 returns \-1 if an error occurred.
967 .TP
968 H_PREV_STR , \fIconst char *str\fP
969 Return the closest previous event that starts with
970 \fIstr\fP.
971 .TP
972 H_NEXT_STR , \fIconst char *str\fP
973 Return the closest next event that starts with
974 \fIstr\fP.
975 .TP
976 H_PREV_EVENT , \fIint e\fP
977 Return the previous event numbered
978 \fIe\fP.
979 .TP
980 H_NEXT_EVENT , \fIint e\fP
981 Return the next event numbered
982 \fIe\fP.
983 .TP
984 H_LOAD , \fIconst char *file\fP
985 Load the history list stored in
986 \fIfile\fP.
987 .TP
988 H_SAVE , \fIconst char *file\fP
989 Save the history list to
990 \fIfile\fP.
991 .TP
992 H_SAVE_FP , \fIFILE *fp\fP
993 Save the history list to the opened
994 .PP
995 \fIFILE\fP
996 .br
997 pointer
998 \fIfp\fP.
999 .TP
1000 H_NSAVE_FP , \fIsize_t n, Fa FILE *fp\fP
1001 Save the last
1002 .PP
1003 \fIn\fP
1004 .br
1005 history entries to the opened
1006 .PP
1007 \fIFILE\fP
1008 .br
1009 pointer
1010 \fIfp\fP.
1011 .TP
1012 H_SETUNIQUE , \fIint unique\fP
1013 Set flag that adjacent identical event strings should not be entered
1014 into the history.
1015 .TP
1016 H_GETUNIQUE
1017 Retrieve the current setting if adjacent identical elements should
1018 be entered into the history.
1019 .TP
1020 H_DEL , \fIint e\fP
1021 Delete the event numbered
1022 \fIe\fP.
1023 This function is only provided for
1024 \fBreadline\fP
1025 compatibility.
1026 The caller is responsible for free'ing the string in the returned
1027 \fIHistEvent\fP.
1028 .RE
1029
1030 \fBhistory\fP();
1031 returns >= 0 if the operation
1032 \fIop \fP
1033 succeeds.
1034 Otherwise, \-1 is returned and
1035 \fIev \fP
1036 is updated to contain more details about the error.
1037 .SH TOKENIZATION FUNCTIONS
1038 The tokenization functions use a common data structure,
1039 \fITokenizer\fP,
1040 which is created by
1041 \fBtok_init\fP()
1042 and freed by
1043 \fBtok_end\fP().
1044
1045 The following functions are available:
1046 .TP
1047 \fBtok_init\fP()
1048 Initialize the tokenizer, and return a data structure
1049 to be used by all other tokenizer functions.
1050 \fIIFS \fP
1051 contains the Input Field Separators, which defaults to
1052 <space ,>
1053 <tab ,>
1054 and
1055 <newline>
1056 if
1057 NULL .
1058 .TP
1059 \fBtok_end\fP()
1060 Clean up and finish with
1061 \fIt\fP,
1062 assumed to have been created with
1063 \fBtok_init\fP().
1064 .TP
1065 \fBtok_reset\fP()
1066 Reset the tokenizer state.
1067 Use after a line has been successfully tokenized
1068 by
1069 \fBtok_line\fP()
1070 or
1071 \fBtok_str\fP()
1072 and before a new line is to be tokenized.
1073 .TP
1074 \fBtok_line\fP()
1075 Tokenize
1076 \fIli\fP,
1077 If successful, modify:
1078 \fIargv \fP
1079 to contain the words,
1080 \fIargc \fP
1081 to contain the number of words,
1082 \fIcursorc \fP
1083 (if not
1084 NULL )
1085 to contain the index of the word containing the cursor,
1086 and
1087 \fIcursoro \fP
1088 (if not
1089 NULL )
1090 to contain the offset within
1091 \fIargv[cursorc] \fP
1092 of the cursor.
1093
1094 Returns
1095 0 if successful,
1096 \-1 for an internal error,
1097 1 for an unmatched single quote,
1098 2 for an unmatched double quote,
1099 and
1100 3 for a backslash quoted
1101 <newline .>
1102 A positive exit code indicates that another line should be read
1103 and tokenization attempted again.
1104 .TP
1105 \fBtok_str\fP()
1106 A simpler form of
1107 \fBtok_line\fP(; )
1108 \fIstr \fP
1109 is a NUL terminated string to tokenize.
1110 .SH SEE ALSO
1111 \fBsh\fP(1),
1112 \fBsignal\fP(3),
1113 \fBtermcap\fP(3),
1114 \fBeditrc\fP(5),
1115 \fBtermcap\fP(5),
1116 \fBeditline\fP(7)
1117 .SH HISTORY
1118 The
1119 \fBeditline\fP
1120 library first appeared in
1121 Bx 4.4 .
1122 CC_REDISPLAY
1123 appeared in
1124 Nx 1.3 .
1125 CC_REFRESH_BEEP ,
1126 EL_EDITMODE
1127 and the readline emulation appeared in
1128 Nx 1.4 .
1129 EL_RPROMPT
1130 appeared in
1131 Nx 1.5 .
1132 .SH AUTHORS
1133
1134 -nosplit
1135 The
1136 \fBeditline\fP
1137 library was written by
1138
1139 Christos Zoulas .
1140
1141 Luke Mewburn
1142 wrote this manual and implemented
1143 CC_REDISPLAY ,
1144 CC_REFRESH_BEEP ,
1145 EL_EDITMODE ,
1146 and
1147 EL_RPROMPT .
1148
1149 Jaromir Dolecek
1150 implemented the readline emulation.
1151
1152 Johny Mattsson
1153 implemented wide-character support.
1154 .SH BUGS
1155 At this time, it is the responsibility of the caller to
1156 check the result of the
1157 EL_EDITMODE
1158 operation of
1159 \fBel_get\fP()
1160 (after an
1161 \fBel_source\fP()
1162 or
1163 \fBel_parse\fP() )
1164 to determine if
1165 \fBeditline\fP
1166 should be used for further input.
1167 I.e.,
1168 EL_EDITMODE
1169 is purely an indication of the result of the most recent
1170 \fBeditrc\fP(5)
1171 \fBedit\fP
1172 command.