Print this page
12212 typos in some section 3tecla man pages
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3tecla/gl_get_line.3tecla.man.txt
+++ new/usr/src/man/man3tecla/gl_get_line.3tecla.man.txt
1 1 GL_GET_LINE(3TECLA) Interactive Command-line Input Library Functions
2 2
3 3
4 4
5 5 NAME
6 6 gl_get_line, new_GetLine, del_GetLine, gl_customize_completion,
7 7 gl_change_terminal, gl_configure_getline, gl_load_history,
8 8 gl_save_history, gl_group_history, gl_show_history, gl_watch_fd,
9 9 gl_inactivity_timeout, gl_terminal_size, gl_set_term_size,
10 10 gl_resize_history, gl_limit_history, gl_clear_history,
11 11 gl_toggle_history, gl_lookup_history, gl_state_of_history,
12 12 gl_range_of_history, gl_size_of_history, gl_echo_mode,
13 13 gl_replace_prompt, gl_prompt_style, gl_ignore_signal, gl_trap_signal,
14 14 gl_last_signal, gl_completion_action, gl_register_action,
15 15 gl_display_text, gl_return_status, gl_error_message, gl_catch_blocked,
16 16 gl_list_signals, gl_bind_keyseq, gl_erase_terminal,
17 17 gl_automatic_history, gl_append_history, gl_query_char, gl_read_char -
18 18 allow the user to compose an input line
19 19
20 20 SYNOPSIS
21 21 cc [ flag... ] file... -ltecla [ library... ]
22 22 #include <stdio.h>
23 23 #include <libtecla.h>
24 24
25 25 GetLine *new_GetLine(size_t linelen, size_t histlen);
26 26
27 27
28 28 GetLine *del_GetLine(GetLine *gl);
29 29
30 30
31 31 char *gl_get_line(GetLine *gl, const char *prompt,
32 32 const char *start_line, int start_pos);
33 33
34 34
35 35 int gl_query_char(GetLine *gl, const char *prompt, char defchar);
36 36
37 37
38 38 int gl_read_char(GetLine *gl);
39 39
40 40
41 41 int gl_customize_completion(GetLine *gl, void *data,
42 42 CplMatchFn *match_fn);
43 43
44 44
45 45 int gl_change_terminal(GetLine *gl, FILE *input_fp,
46 46 FILE *output_fp, const char *term);
47 47
48 48
49 49 int gl_configure_getline(GetLine *gl, const char *app_string,
50 50 const char *app_file, const char *user_file);
51 51
52 52
53 53 int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin,
54 54 const char *keyseq, const char *action);
55 55
56 56
57 57 int gl_save_history(GetLine *gl, const char *filename,
58 58 const char *comment, int max_lines);
59 59
60 60
61 61 int gl_load_history(GetLine *gl, const char *filename,
62 62 const char *comment);
63 63
64 64
65 65 int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
66 66 GlFdEventFn *callback, void *data);
67 67
68 68
69 69 int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *callback,
70 70 void *data, unsigned long sec, unsigned long nsec);
71 71
72 72
73 73 int gl_group_history(GetLine *gl, unsigned stream);
74 74
75 75
76 76 int gl_show_history(GetLine *gl, FILE *fp, const char *fmt,
77 77 int all_groups, int max_lines);
78 78
79 79
80 80 int gl_resize_history(GetLine *gl, size_t bufsize);
81 81
82 82
83 83 void gl_limit_history(GetLine *gl, int max_lines);
84 84
85 85
86 86 void gl_clear_history(GetLine *gl, int all_groups);
87 87
88 88
89 89 void gl_toggle_history(GetLine *gl, int enable);
90 90
91 91
92 92 GlTerminalSize gl_terminal_size(GetLine *gl, int def_ncolumn,
93 93 int def_nline);
94 94
95 95
96 96 int gl_set_term_size(GetLine *gl, int ncolumn, int nline);
97 97
98 98
99 99 int gl_lookup_history(GetLine *gl, unsigned long id,
100 100 GlHistoryLine *hline);
101 101
102 102
103 103 void gl_state_of_history(GetLine *gl, GlHistoryState *state);
104 104
105 105
106 106 void gl_range_of_history(GetLine *gl, GlHistoryRange *range);
107 107
108 108
109 109 void gl_size_of_history(GetLine *gl, GlHistorySize *size);
110 110
111 111
112 112 void gl_echo_mode(GetLine *gl, int enable);
113 113
114 114
115 115 void gl_replace_prompt(GetLine *gl, const char *prompt);
116 116
117 117
118 118 void gl_prompt_style(GetLine *gl, GlPromptStyle style);
119 119
120 120
121 121 int gl_ignore_signal(GetLine *gl, int signo);
122 122
123 123
124 124 int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
125 125 GlAfterSignal after, int errno_value);
126 126
127 127
128 128 int gl_last_signal(GetLine *gl);
129 129
130 130
131 131 int gl_completion_action(GetLine *gl, void *data,
132 132 CplMatchFn *match_fn, int list_only, const char *name,
133 133 const char *keyseq);
134 134
135 135
136 136 int gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
137 137 const char *name, const char *keyseq);
138 138
139 139
140 140 int gl_display_text(GetLine *gl, int indentation,
141 141 const char *prefix, const char *suffix, int fill_char,
142 142 int def_width, int start, const char *string);
143 143
144 144
145 145 GlReturnStatus gl_return_status(GetLine *gl);
146 146
147 147
148 148 const char *gl_error_message(GetLine *gl, char *buff, size_t n);
149 149
150 150
151 151 void gl_catch_blocked(GetLine *gl);
152 152
153 153
154 154 int gl_list_signals(GetLine *gl, sigset_t *set);
155 155
156 156
157 157 int gl_append_history(GetLine *gl, const char *line);
158 158
159 159
160 160 int gl_automatic_history(GetLine *gl, int enable);
161 161
162 162
163 163 int gl_erase_terminal(GetLine *gl);
164 164
165 165
166 166 DESCRIPTION
167 167 The gl_get_line() function is part of the libtecla(3LIB) library. If
168 168 the user is typing at a terminal, each call prompts them for a line of
169 169 input, then provides interactive editing facilities, similar to those
170 170 of the UNIX tcsh shell. In addition to simple command-line editing, it
171 171 supports recall of previously entered command lines, TAB completion of
172 172 file names, and in-line wild-card expansion of filenames. Documentation
173 173 of both the user-level command-line editing features and all user
174 174 configuration options can be found on the tecla(5) manual page.
175 175
176 176 An Example
177 177 The following shows a complete example of how to use the gl_get_line()
178 178 function to get input from the user:
179 179
180 180 #include <stdio.h>
181 181 #include <locale.h>
182 182 #include <libtecla.h>
183 183
184 184 int main(int argc, char *argv[])
185 185 {
186 186 char *line; /* The line that the user typed */
187 187 GetLine *gl; /* The gl_get_line() resource object */
188 188
189 189 setlocale(LC_CTYPE, ""); /* Adopt the user's choice */
190 190 /* of character set. */
191 191
192 192 gl = new_GetLine(1024, 2048);
193 193 if(!gl)
194 194 return 1;
195 195 while((line=gl_get_line(gl, "$ ", NULL, -1)) != NULL &&
196 196 strcmp(line, "exit\n") != 0)
197 197 printf("You typed: %s\n", line);
198 198
199 199 gl = del_GetLine(gl);
200 200 return 0;
201 201 }
202 202
203 203
204 204
205 205 In the example, first the resources needed by the gl_get_line()
206 206 function are created by calling new_GetLine(). This allocates the
207 207 memory used in subsequent calls to the gl_get_line() function,
208 208 including the history buffer for recording previously entered lines.
209 209 Then one or more lines are read from the user, until either an error
210 210 occurs, or the user types exit. Then finally the resources that were
211 211 allocated by new_GetLine(), are returned to the system by calling
212 212 del_GetLine(). Note the use of the NULL return value of del_GetLine()
213 213 to make gl NULL. This is a safety precaution. If the program
214 214 subsequently attempts to pass gl to gl_get_line(), said function will
215 215 complain, and return an error, instead of attempting to use the deleted
216 216 resource object.
217 217
218 218 The Functions Used In The Example
219 219 The new_GetLine() function creates the resources used by the
220 220 gl_get_line() function and returns an opaque pointer to the object that
221 221 contains them. The maximum length of an input line is specified by the
222 222 linelen argument, and the number of bytes to allocate for storing
223 223 history lines is set by the histlen argument. History lines are stored
224 224 back-to-back in a single buffer of this size. Note that this means that
225 225 the number of history lines that can be stored at any given time,
226 226 depends on the lengths of the individual lines. If you want to place an
227 227 upper limit on the number of lines that can be stored, see the
228 228 description of the gl_limit_history() function. If you do not want
229 229 history at all, specify histlen as zero, and no history buffer will be
230 230 allocated.
231 231
232 232
233 233 On error, a message is printed to stderr and NULL is returned.
234 234
235 235
236 236 The del_GetLine() function deletes the resources that were returned by
237 237 a previous call to new_GetLine(). It always returns NULL (for example,
238 238 a deleted object). It does nothing if the gl argument is NULL.
239 239
240 240
241 241 The gl_get_line() function can be called any number of times to read
242 242 input from the user. The gl argument must have been previously returned
243 243 by a call to new_GetLine(). The prompt argument should be a normal
244 244 null-terminated string, specifying the prompt to present the user with.
245 245 By default prompts are displayed literally, but if enabled with the
246 246 gl_prompt_style() function, prompts can contain directives to do
247 247 underlining, switch to and from bold fonts, or turn highlighting on and
248 248 off.
249 249
250 250
251 251 If you want to specify the initial contents of the line for the user to
252 252 edit, pass the desired string with the start_line argument. You can
253 253 then specify which character of this line the cursor is initially
254 254 positioned over by using the start_pos argument. This should be -1 if
255 255 you want the cursor to follow the last character of the start line. If
256 256 you do not want to preload the line in this manner, send start_line as
257 257 NULL, and set start_pos to -1.
258 258
259 259
260 260 The gl_get_line() function returns a pointer to the line entered by the
261 261 user, or NULL on error or at the end of the input. The returned pointer
262 262 is part of the specified gl resource object, and thus should not be
263 263 freed by the caller, or assumed to be unchanging from one call to the
264 264 next. When reading from a user at a terminal, there will always be a
265 265 newline character at the end of the returned line. When standard input
266 266 is being taken from a pipe or a file, there will similarly be a newline
267 267 unless the input line was too long to store in the internal buffer. In
268 268 the latter case you should call gl_get_line() again to read the rest of
269 269 the line. Note that this behavior makes gl_get_line() similar to
270 270 fgets(3C). When stdin is not connected to a terminal, gl_get_line()
271 271 simply calls fgets().
272 272
273 273 The Return Status Of gl_get_line()
274 274 The gl_get_line() function has two possible return values: a pointer to
275 275 the completed input line, or NULL. Additional information about what
276 276 caused gl_get_line() to return is available both by inspecting errno
277 277 and by calling the gl_return_status() function.
278 278
279 279
280 280 The following are the possible enumerated values returned by
281 281 gl_return_status():
282 282
283 283 GLR_NEWLINE
284 284 The last call to gl_get_line() successfully returned a
285 285 completed input line.
286 286
287 287
288 288 GLR_BLOCKED
289 289 The gl_get_line() function was in non-blocking server
290 290 mode, and returned early to avoid blocking the process
291 291 while waiting for terminal I/O. The gl_pending_io()
292 292 function can be used to see what type of I/O
293 293 gl_get_line() was waiting for. See the
294 294 gl_io_mode(3TECLA).
295 295
296 296
297 297 GLR_SIGNAL
298 298 A signal was caught by gl_get_line() that had an after-
299 299 signal disposition of GLS_ABORT. See gl_trap_signal().
|
↓ open down ↓ |
299 lines elided |
↑ open up ↑ |
300 300
301 301
302 302 GLR_TIMEOUT
303 303 The inactivity timer expired while gl_get_line() was
304 304 waiting for input, and the timeout callback function
305 305 returned GLTO_ABORT. See gl_inactivity_timeout() for
306 306 information about timeouts.
307 307
308 308
309 309 GLR_FDABORT
310 - An application I/O callback returned GLFD_ABORT. Ssee
310 + An application I/O callback returned GLFD_ABORT. See
311 311 gl_watch_fd().
312 312
313 313
314 314 GLR_EOF
315 315 End of file reached. This can happen when input is
316 316 coming from a file or a pipe, instead of the terminal.
317 317 It also occurs if the user invokes the list-or-eof or
318 318 del-char-or-list-or-eof actions at the start of a new
319 319 line.
320 320
321 321
322 322 GLR_ERROR
323 323 An unexpected error caused gl_get_line() to abort
324 324 (consult errno and/or gl_error_message() for details.
325 325
326 326
327 327
328 328 When gl_return_status() returns GLR_ERROR and the value of errno is not
329 329 sufficient to explain what happened, you can use the gl_error_message()
330 330 function to request a description of the last error that occurred.
331 331
332 332
333 333 The return value of gl_error_message() is a pointer to the message that
334 334 occurred. If the buff argument is NULL, this will be a pointer to a
335 335 buffer within gl whose value will probably change on the next call to
336 336 any function associated with gl_get_line(). Otherwise, if a non-null
337 337 buff argument is provided, the error message, including a '\0'
338 338 terminator, will be written within the first n elements of this buffer,
339 339 and the return value will be a pointer to the first element of this
340 340 buffer. If the message will not fit in the provided buffer, it will be
341 341 truncated to fit.
342 342
343 343 Optional Prompt Formatting
344 344 Whereas by default the prompt string that you specify is displayed
345 345 literally without any special interpretation of the characters within
346 346 it, the gl_prompt_style() function can be used to enable optional
347 347 formatting directives within the prompt.
348 348
349 349
350 350 The style argument, which specifies the formatting style, can take any
351 351 of the following values:
352 352
353 353 GL_FORMAT_PROMPT
354 354 In this style, the formatting directives described
355 355 below, when included in prompt strings, are
356 356 interpreted as follows:
357 357
358 358 %B
359 359 Display subsequent characters with a bold
360 360 font.
361 361
362 362
363 363 %b
364 364 Stop displaying characters with the bold
365 365 font.
366 366
367 367
368 368 %F
369 369 Make subsequent characters flash.
370 370
371 371
372 372 %f
373 373 Turn off flashing characters.
374 374
375 375
376 376 %U
377 377 Underline subsequent characters.
378 378
379 379
380 380 %u
381 381 Stop underlining characters.
382 382
383 383
384 384 %P
385 385 Switch to a pale (half brightness) font.
386 386
387 387
388 388 %p
389 389 Stop using the pale font.
390 390
391 391
392 392 %S
393 393 Highlight subsequent characters (also known
394 394 as standout mode).
395 395
396 396
397 397 %s
398 398 Stop highlighting characters.
399 399
400 400
401 401 %V
402 402 Turn on reverse video.
403 403
404 404
405 405 %v
406 406 Turn off reverse video.
407 407
408 408
409 409 %%
410 410 Display a single % character.
411 411
412 412 For example, in this mode, a prompt string like
413 413 "%UOK%u$" would display the prompt "OK$", but with
414 414 the OK part underlined.
415 415
416 416 Note that although a pair of characters that
417 417 starts with a % character, but does not match any
418 418 of the above directives is displayed literally, if
419 419 a new directive is subsequently introduced which
420 420 does match, the displayed prompt will change, so
421 421 it is better to always use %% to display a literal
422 422 %.
423 423
424 424 Also note that not all terminals support all of
425 425 these text attributes, and that some substitute a
426 426 different attribute for missing ones.
427 427
428 428
429 429 GL_LITERAL_PROMPT
430 430 In this style, the prompt string is printed
431 431 literally. This is the default style.
432 432
433 433
434 434 Alternate Configuration Sources
435 435 By default users have the option of configuring the behavior of
436 436 gl_get_line() with a configuration file called .teclarc in their home
437 437 directories. The fact that all applications share this same
438 438 configuration file is both an advantage and a disadvantage. In most
439 439 cases it is an advantage, since it encourages uniformity, and frees the
440 440 user from having to configure each application separately. In some
441 441 applications, however, this single means of configuration is a problem.
442 442 This is particularly true of embedded software, where there's no
443 443 filesystem to read a configuration file from, and also in applications
444 444 where a radically different choice of keybindings is needed to emulate
445 445 a legacy keyboard interface. To cater for such cases, the
446 446 gl_configure_getline() function allows the application to control where
447 447 configuration information is read from.
448 448
449 449
450 450 The gl_configure_getline() function allows the configuration commands
451 451 that would normally be read from a user's ~/.teclarc file, to be read
452 452 from any or none of, a string, an application specific configuration
453 453 file, and/or a user-specific configuration file. If this function is
454 454 called before the first call to gl_get_line(), the default behavior of
455 455 reading ~/.teclarc on the first call to gl_get_line() is disabled, so
456 456 all configurations must be achieved using the configuration sources
457 457 specified with this function.
458 458
459 459
460 460 If app_string != NULL, then it is interpreted as a string containing
461 461 one or more configuration commands, separated from each other in the
462 462 string by embedded newline characters. If app_file != NULL then it is
463 463 interpreted as the full pathname of an application-specific
464 464 configuration file. If user_file != NULL then it is interpreted as the
465 465 full path name of a user-specific configuration file, such as
466 466 ~/.teclarc. For example, in the call
467 467
468 468 gl_configure_getline(gl, "edit-mode vi \n nobeep",
469 469 "/usr/share/myapp/teclarc", "~/.teclarc");
|
↓ open down ↓ |
149 lines elided |
↑ open up ↑ |
470 470
471 471
472 472
473 473 The app_string argument causes the calling application to start in
474 474 vi(1) edit-mode, instead of the default emacs mode, and turns off the
475 475 use of the terminal bell by the library. It then attempts to read
476 476 system-wide configuration commands from an optional file called
477 477 /usr/share/myapp/teclarc, then finally reads user-specific
478 478 configuration commands from an optional .teclarc file in the user's
479 479 home directory. Note that the arguments are listed in ascending order
480 - of priority, with the contents of app_string being potentially over
481 - riden by commands in app_file, and commands in app_file potentially
482 - being overridden by commands in user_file.
480 + of priority, with the contents of app_string being potentially
481 + overridden by commands in app_file, and commands in app_file
482 + potentially being overridden by commands in user_file.
483 483
484 484
485 485 You can call this function as many times as needed, the results being
486 486 cumulative, but note that copies of any file names specified with the
487 487 app_file and user_file arguments are recorded internally for subsequent
488 488 use by the read-init-files key-binding function, so if you plan to call
489 489 this function multiple times, be sure that the last call specifies the
490 490 filenames that you want re-read when the user requests that the
491 491 configuration files be re-read.
492 492
493 493
494 494 Individual key sequences can also be bound and unbound using the
495 495 gl_bind_keyseq() function. The origin argument specifies the priority
496 496 of the binding, according to whom it is being established for, and must
497 497 be one of the following two values.
498 498
499 499 GL_USER_KEY
500 500 The user requested this key-binding.
501 501
502 502
503 503 GL_APP_KEY
504 504 This is a default binding set by the application.
505 505
506 506
507 507
508 508 When both user and application bindings for a given key sequence have
509 509 been specified, the user binding takes precedence. The application's
510 510 binding is subsequently reinstated if the user's binding is later
511 511 unbound with either another call to this function, or a call to
512 512 gl_configure_getline().
513 513
514 514
515 515 The keyseq argument specifies the key sequence to be bound or unbound,
516 516 and is expressed in the same way as in a ~/.teclarc configuration file.
517 517 The action argument must either be a string containing the name of the
518 518 action to bind the key sequence to, or it must be NULL or "" to unbind
519 519 the key sequence.
520 520
521 521 Customized Word Completion
522 522 If in your application you would like to have TAB completion complete
523 523 other things in addition to or instead of filenames, you can arrange
524 524 this by registering an alternate completion callback function with a
525 525 call to the gl_customize_completion() function.
526 526
527 527
528 528 The data argument provides a way for your application to pass
529 529 arbitrary, application-specific information to the callback function.
530 530 This is passed to the callback every time that it is called. It might
531 531 for example point to the symbol table from which possible completions
532 532 are to be sought. The match_fn argument specifies the callback function
533 533 to be called. The CplMatchFn function type is defined in <libtecla.h>,
534 534 as is a CPL_MATCH_FN() macro that you can use to declare and prototype
535 535 callback functions. The declaration and responsibilities of callback
536 536 functions are described in depth on the cpl_complete_word(3TECLA)
|
↓ open down ↓ |
44 lines elided |
↑ open up ↑ |
537 537 manual page.
538 538
539 539
540 540 The callback function is responsible for looking backwards in the input
541 541 line from the point at which the user pressed TAB, to find the start of
542 542 the word being completed. It then must lookup possible completions of
543 543 this word, and record them one by one in the WordCompletion object that
544 544 is passed to it as an argument, by calling the cpl_add_completion()
545 545 function. If the callback function wants to provide filename completion
546 546 in addition to its own specific completions, it has the option of
547 - itself calling the builtin filename completion callback. This also is
548 - documented on the cpl_complete_word(3TECLA) manual page.
547 + itself calling the builtin filename completion callback. This is also
548 + documented in the cpl_complete_word(3TECLA) manual page.
549 549
550 550
551 551 If you would like gl_get_line() to return the current input line when a
552 - successful completion is been made, you can arrange this when you call
552 + successful completion has been made, you can arrange this when you call
553 553 cpl_add_completion() by making the last character of the continuation
554 554 suffix a newline character. The input line will be updated to display
555 - the completion, together with any contiuation suffix up to the newline
555 + the completion, together with any continuation suffix up to the newline
556 556 character, and gl_get_line() will return this input line.
557 557
558 558
559 559 If your callback function needs to write something to the terminal, it
560 560 must call gl_normal_io() before doing so. This will start a new line
561 561 after the input line that is currently being edited, reinstate normal
562 562 terminal I/O, and notify gl_get_line() that the input line will need to
563 563 be redrawn when the callback returns.
564 564
565 565 Adding Completion Actions
566 566 In the previous section the ability to customize the behavior of the
567 567 only default completion action, complete-word, was described. In this
568 568 section the ability to install additional action functions, so that
569 569 different types of word completion can be bound to different key
570 570 sequences, is described. This is achieved by using the
571 571 gl_completion_action() function.
572 572
573 573
574 574 The data and match_fn arguments are as described on the
575 575 cpl_complete_word(3TECLA) manual page, and specify the callback
576 576 function that should be invoked to identify possible completions. The
577 577 list_only argument determines whether the action that is being defined
578 578 should attempt to complete the word as far as possible in the input
579 579 line before displaying any possible ambiguous completions, or whether
580 580 it should simply display the list of possible completions without
581 581 touching the input line. The former option is selected by specifying a
|
↓ open down ↓ |
16 lines elided |
↑ open up ↑ |
582 582 value of 0, and the latter by specifying a value of 1. The name
583 583 argument specifies the name by which configuration files and future
584 584 invocations of this function should refer to the action. This must
585 585 either be the name of an existing completion action to be changed, or
586 586 be a new unused name for a new action. Finally, the keyseq argument
587 587 specifies the default key sequence to bind the action to. If this is
588 588 NULL, no new key sequence will be bound to the action.
589 589
590 590
591 591 Beware that in order for the user to be able to change the key sequence
592 - that is bound to actions that are installed in this manner, you
593 - shouldcall gl_completion_action() to install a given action for the
594 - first time between calling new_GetLine() and the first call to
595 - gl_get_line(). Otherwise, when the user's configuration file is read
596 - on the first call to gl_get_line(), the name of the your additional
597 - action will not be known, and any reference to it in the configuration
598 - file will generate an error.
592 + that is bound to actions that are installed in this manner, you should
593 + call gl_completion_action() to install a given action for the first
594 + time between calling new_GetLine() and the first call to gl_get_line().
595 + Otherwise, when the user's configuration file is read on the first call
596 + to gl_get_line(), the name of the your additional action will not be
597 + known, and any reference to it in the configuration file will generate
598 + an error.
599 599
600 600
601 601 As discussed for gl_customize_completion(), if your callback function
602 602 needs to write anything to the terminal, it must call gl_normal_io()
603 603 before doing so.
604 604
605 605 Defining Custom Actions
606 606 Although the built-in key-binding actions are sufficient for the needs
607 607 of most applications, occasionally a specialized application may need
608 608 to define one or more custom actions, bound to application-specific key
609 609 sequences. For example, a sales application would benefit from having a
610 610 key sequence that displayed the part name that corresponded to a part
611 611 number preceding the cursor. Such a feature is clearly beyond the scope
612 612 of the built-in action functions. So for such special cases, the
613 613 gl_register_action() function is provided.
614 614
615 615
616 616 The gl_register_action() function lets the application register an
617 617 external function, fn, that will thereafter be called whenever either
618 618 the specified key sequence, keyseq, is entered by the user, or the user
619 619 enters any other key sequence that the user subsequently binds to the
620 620 specified action name, name, in their configuration file. The data
621 621 argument can be a pointer to anything that the application wants to
622 622 have passed to the action function, fn, whenever that function is
623 623 invoked.
624 624
625 625
626 626 The action function, fn, should be declared using the GL_ACTION_FN()
627 627 macro, which is defined in <libtecla.h>.
628 628
629 629 #define GL_ACTION_FN(fn) GlAfterAction (fn)(GetLine *gl, \
630 630 void *data, int count, size_t curpos, \
631 631 const char *line)
632 632
633 633
634 634
635 635 The gl and data arguments are those that were previously passed to
636 636 gl_register_action() when the action function was registered. The count
637 637 argument is a numeric argument which the user has the option of
638 638 entering using the digit-argument action, before invoking the action.
639 639 If the user does not enter a number, then the count argument is set to
640 640 1. Nominally this argument is interpreted as a repeat count, meaning
641 641 that the action should be repeated that many times. In practice
642 642 however, for some actions a repeat count makes little sense. In such
643 643 cases, actions can either simply ignore the count argument, or use its
644 644 value for a different purpose.
645 645
646 646
647 647 A copy of the current input line is passed in the read-only line
648 648 argument. The current cursor position within this string is given by
649 649 the index contained in the curpos argument. Note that direct
650 650 manipulation of the input line and the cursor position is not permitted
651 651 because the rules dictated by various modes (such as vi mode versus
652 652 emacs mode, no-echo mode, and insert mode versus overstrike mode) make
653 653 it too complex for an application writer to write a conforming editing
654 654 action, as well as constrain future changes to the internals of
655 655 gl_get_line(). A potential solution to this dilemma would be to allow
656 656 the action function to edit the line using the existing editing
657 657 actions. This is currently under consideration.
658 658
659 659
660 660 If the action function wishes to write text to the terminal without
661 661 this getting mixed up with the displayed text of the input line, or
662 662 read from the terminal without having to handle raw terminal I/O, then
663 663 before doing either of these operations, it must temporarily suspend
664 664 line editing by calling the gl_normal_io() function. This function
665 665 flushes any pending output to the terminal, moves the cursor to the
666 666 start of the line that follows the last terminal line of the input
667 667 line, then restores the terminal to a state that is suitable for use
668 668 with the C stdio facilities. The latter includes such things as
669 669 restoring the normal mapping of \n to \r\n, and, when in server mode,
670 670 restoring the normal blocking form of terminal I/O. Having called this
671 671 function, the action function can read from and write to the terminal
672 672 without the fear of creating a mess. It is not necessary for the action
673 673 function to restore the original editing environment before it returns.
674 674 This is done automatically by gl_get_line() after the action function
675 675 returns. The following is a simple example of an action function which
676 676 writes the sentence "Hello world" on a new terminal line after the line
677 677 being edited. When this function returns, the input line is redrawn on
678 678 the line that follows the "Hello world" line, and line editing resumes.
679 679
680 680 static GL_ACTION_FN(say_hello_fn)
681 681 {
682 682 if(gl_normal_io(gl)) /* Temporarily suspend editing */
683 683 return GLA_ABORT;
684 684 printf("Hello world\n");
685 685 return GLA_CONTINUE;
686 686 }
687 687
688 688
689 689
690 690 Action functions must return one of the following values, to tell
691 691 gl_get_line() how to proceed.
692 692
693 693 GLA_ABORT
694 694 Cause gl_get_line() to return NULL.
695 695
696 696
697 697 GLA_RETURN
698 698 Cause gl_get_line() to return the completed input line
699 699
700 700
701 701 GLA_CONTINUE
702 702 Resume command-line editing.
703 703
704 704
705 705
706 706 Note that the name argument of gl_register_action() specifies the name
707 707 by which a user can refer to the action in their configuration file.
708 708 This allows them to re-bind the action to an alternate key-sequence. In
709 709 order for this to work, it is necessary to call gl_register_action()
710 710 between calling new_GetLine() and the first call to gl_get_line().
711 711
712 712 History Files
713 713 To save the contents of the history buffer before quitting your
714 714 application and subsequently restore them when you next start the
715 715 application, the gl_save_history() and gl_load_history() functions are
716 716 provided.
717 717
718 718
719 719 The filename argument specifies the name to give the history file when
720 720 saving, or the name of an existing history file, when loading. This may
721 721 contain home directory and environment variable expressions, such as
722 722 ~/.myapp_history or $HOME/.myapp_history.
723 723
724 724
725 725 Along with each history line, additional information about it, such as
726 726 its nesting level and when it was entered by the user, is recorded as a
727 727 comment preceding the line in the history file. Writing this as a
728 728 comment allows the history file to double as a command file, just in
729 729 case you wish to replay a whole session using it. Since comment
730 730 prefixes differ in different languages, the comment argument is
731 731 provided for specifying the comment prefix. For example, if your
732 732 application were a UNIX shell, such as the Bourne shell, you would
|
↓ open down ↓ |
124 lines elided |
↑ open up ↑ |
733 733 specify "#" here. Whatever you choose for the comment character, you
734 734 must specify the same prefix to gl_load_history() that you used when
735 735 you called gl_save_history() to write the history file.
736 736
737 737
738 738 The max_lines argument must be either -1 to specify that all lines in
739 739 the history list be saved, or a positive number specifying a ceiling on
740 740 how many of the most recent lines should be saved.
741 741
742 742
743 - Both fuctions return non-zero on error, after writing an error message
743 + Both functions return non-zero on error, after writing an error message
744 744 to stderr. Note that gl_load_history() does not consider the non-
745 745 existence of a file to be an error.
746 746
747 747 Multiple History Lists
748 748 If your application uses a single GetLine object for entering many
749 749 different types of input lines, you might want gl_get_line() to
750 750 distinguish the different types of lines in the history list, and only
751 751 recall lines that match the current type of line. To support this
752 752 requirement, gl_get_line() marks lines being recorded in the history
753 753 list with an integer identifier chosen by the application. Initially
754 754 this identifier is set to 0 by new_GetLine(), but it can be changed
755 755 subsequently by calling gl_group_history().
756 756
757 757
758 758 The integer identifier ID can be any number chosen by the application,
759 759 but note that gl_save_history() and gl_load_history() preserve the
760 760 association between identifiers and historical input lines between
761 761 program invocations, so you should choose fixed identifiers for the
762 762 different types of input line used by your application.
763 763
764 764
765 765 Whenever gl_get_line() appends a new input line to the history list,
766 766 the current history identifier is recorded with it, and when it is
767 767 asked to recall a historical input line, it only recalls lines that are
768 768 marked with the current identifier.
769 769
770 770 Displaying History
771 771 The history list can be displayed by calling gl_show_history(). This
772 772 function displays the current contents of the history list to the stdio
773 773 output stream fp. If the max_lines argument is greater than or equal to
774 774 zero, then no more than this number of the most recent lines will be
775 775 displayed. If the all_groups argument is non-zero, lines from all
776 776 history groups are displayed. Otherwise only those of the currently
777 777 selected history group are displayed. The format string argument, fmt,
778 778 determines how the line is displayed. This can contain arbitrary
779 779 characters which are written verbatim, interleaved with any of the
780 780 following format directives:
781 781
782 782 %D
783 783 The date on which the line was originally entered, formatted like
784 784 2001-11-20.
785 785
786 786
787 787 %T
788 788 The time of day when the line was entered, formatted like
789 789 23:59:59.
790 790
791 791
792 792 %N
793 793 The sequential entry number of the line in the history buffer.
794 794
795 795
796 796 %G
797 797 The number of the history group which the line belongs to.
798 798
799 799
800 800 %%
801 801 A literal % character.
802 802
803 803
804 804 %H
805 805 The history line itself.
806 806
807 807
808 808
809 809 Thus a format string like "%D %T %H0" would output something like:
810 810
811 811 2001-11-20 10:23:34 Hello world
812 812
813 813
814 814
815 815 Note the inclusion of an explicit newline character in the format
816 816 string.
817 817
818 818 Looking Up History
819 819 The gl_lookup_history() function allows the calling application to look
820 820 up lines in the history list.
821 821
822 822
823 823 The id argument indicates which line to look up, where the first line
824 824 that was entered in the history list after new_GetLine() was called is
825 825 denoted by 0, and subsequently entered lines are denoted with
826 826 successively higher numbers. Note that the range of lines currently
827 827 preserved in the history list can be queried by calling the
828 828 gl_range_of_history() function. If the requested line is in the history
829 829 list, the details of the line are recorded in the variable pointed to
830 830 by the hline argument, and 1 is returned. Otherwise 0 is returned, and
831 831 the variable pointed to by hline is left unchanged.
832 832
833 833
834 834 Beware that the string returned in hline->line is part of the history
835 835 buffer, so it must not be modified by the caller, and will be recycled
836 836 on the next call to any function that takes gl as its argument.
837 837 Therefore you should make a private copy of this string if you need to
838 838 keep it.
839 839
840 840 Manual History Archival
841 841 By default, whenever a line is entered by the user, it is automatically
842 842 appended to the history list, just before gl_get_line() returns the
843 843 line to the caller. This is convenient for the majority of
844 844 applications, but there are also applications that need finer-grained
845 845 control over what gets added to the history list. In such cases, the
846 846 automatic addition of entered lines to the history list can be turned
847 847 off by calling the gl_automatic_history() function.
848 848
849 849
850 850 If this function is called with its enable argument set to 0,
851 851 gl_get_line() will not automatically archive subsequently entered
852 852 lines. Automatic archiving can be reenabled at a later time by calling
853 853 this function again, with its enable argument set to 1. While automatic
854 854 history archiving is disabled, the calling application can use the
855 855 gl_append_history() to append lines to the history list as needed.
856 856
857 857
858 858 The line argument specifies the line to be added to the history list.
859 859 This must be a normal '\0 ' terminated string. If this string contains
860 860 any newline characters, the line that gets archived in the history list
861 861 will be terminated by the first of these. Otherwise it will be
862 862 terminated by the '\0 ' terminator. If the line is longer than the
863 863 maximum input line length that was specified when new_GetLine() was
864 864 called, it will be truncated to the actual gl_get_line() line length
865 865 when the line is recalled.
866 866
867 867
868 868 If successful, gl_append_history() returns 0. Otherwise it returns non-
869 869 zero and sets errno to one of the following values.
870 870
871 871 EINVAL
872 872 One of the arguments passed to gl_append_history() was NULL.
873 873
874 874
875 875 ENOMEM
876 876 The specified line was longer than the allocated size of the
877 877 history buffer (as specified when new_GetLine() was called),
878 878 so it could not be archived.
879 879
880 880
881 881
882 882 A textual description of the error can optionally be obtained by
883 883 calling gl_error_message(). Note that after such an error, the history
884 884 list remains in a valid state to receive new history lines, so there is
885 885 little harm in simply ignoring the return status of
886 886 gl_append_history().
887 887
888 888 Miscellaneous History Configuration
889 889 If you wish to change the size of the history buffer that was
890 890 originally specified in the call to new_GetLine(), you can do so with
891 891 the gl_resize_history() function.
892 892
893 893
894 894 The histlen argument specifies the new size in bytes, and if you
895 895 specify this as 0, the buffer will be deleted.
896 896
897 897
898 898 As mentioned in the discussion of new_GetLine(), the number of lines
899 899 that can be stored in the history buffer, depends on the lengths of the
900 900 individual lines. For example, a 1000 byte buffer could equally store
901 901 10 lines of average length 100 bytes, or 20 lines of average length 50
902 902 bytes. Although the buffer is never expanded when new lines are added,
903 903 a list of pointers into the buffer does get expanded when needed to
904 904 accommodate the number of lines currently stored in the buffer. To
905 905 place an upper limit on the number of lines in the buffer, and thus a
906 906 ceiling on the amount of memory used in this list, you can call the
907 907 gl_limit_history() function.
908 908
909 909
910 910 The max_lines should either be a positive number >= 0, specifying an
911 911 upper limit on the number of lines in the buffer, or be -1 to cancel
912 912 any previously specified limit. When a limit is in effect, only the
913 913 max_lines most recently appended lines are kept in the buffer. Older
914 914 lines are discarded.
915 915
916 916
917 917 To discard lines from the history buffer, use the gl_clear_history()
918 918 function.
919 919
920 920
921 921 The all_groups argument tells the function whether to delete just the
922 922 lines associated with the current history group (see
923 923 gl_group_history()) or all historical lines in the buffer.
924 924
925 925
926 926 The gl_toggle_history() function allows you to toggle history on and
927 927 off without losing the current contents of the history list.
928 928
929 929
930 930 Setting the enable argument to 0 turns off the history mechanism, and
931 931 setting it to 1 turns it back on. When history is turned off, no new
932 932 lines will be added to the history list, and history lookup key-
933 933 bindings will act as though there is nothing in the history buffer.
934 934
935 935 Querying History Information
936 936 The configured state of the history list can be queried with the
937 937 gl_history_state() function. On return, the status information is
938 938 recorded in the variable pointed to by the state argument.
939 939
940 940
941 941 The gl_range_of_history() function returns the number and range of
942 942 lines in the history list. The return values are recorded in the
943 943 variable pointed to by the range argument. If the nlines member of this
944 944 structure is greater than zero, then the oldest and newest members
945 945 report the range of lines in the list, and newest=oldest+nlines-1.
946 946 Otherwise they are both zero.
947 947
948 948
949 949 The gl_size_of_history() function returns the total size of the history
950 950 buffer and the amount of the buffer that is currently occupied.
951 951
952 952
953 953 On return, the size information is recorded in the variable pointed to
954 954 by the size argument.
955 955
956 956 Changing Terminals
957 957 The new_GetLine() constructor function assumes that input is to be read
958 958 from stdin and output written to stdout. The following function allows
959 959 you to switch to different input and output streams.
960 960
961 961
962 962 The gl argument is the object that was returned by new_GetLine(). The
963 963 input_fp argument specifies the stream to read from, and output_fp
964 964 specifies the stream to be written to. Only if both of these refer to a
965 965 terminal, will interactive terminal input be enabled. Otherwise
966 966 gl_get_line() will simply call fgets() to read command input. If both
967 967 streams refer to a terminal, then they must refer to the same terminal,
968 968 and the type of this terminal must be specified with the term argument.
969 969 The value of the term argument is looked up in the terminal information
970 970 database (terminfo or termcap), in order to determine which special
971 971 control sequences are needed to control various aspects of the
972 972 terminal. new_GetLine() for example, passes the return value of
973 973 getenv("TERM") in this argument. Note that if one or both of input_fp
974 974 and output_fp do not refer to a terminal, then it is legal to pass NULL
975 975 instead of a terminal type.
976 976
977 977
978 978 Note that if you want to pass file descriptors to gl_change_terminal(),
979 979 you can do this by creating stdio stream wrappers using the POSIX
980 980 fdopen(3C) function.
981 981
982 982 External Event Handling
983 983 By default, gl_get_line() does not return until either a complete input
984 984 line has been entered by the user, or an error occurs. In programs that
985 985 need to watch for I/O from other sources than the terminal, there are
986 986 two options.
987 987
988 988 o Use the functions described in the gl_io_mode(3TECLA) manual
989 989 page to switch gl_get_line() into non-blocking server mode.
990 990 In this mode, gl_get_line() becomes a non-blocking,
991 991 incremental line-editing function that can safely be called
992 992 from an external event loop. Although this is a very
993 993 versatile method, it involves taking on some
994 994 responsibilities that are normally performed behind the
995 995 scenes by gl_get_line().
996 996
997 997 o While gl_get_line() is waiting for keyboard input from the
998 998 user, you can ask it to also watch for activity on arbitrary
999 999 file descriptors, such as network sockets or pipes, and have
1000 1000 it call functions of your choosing when activity is seen.
1001 1001 This works on any system that has the select system call,
1002 1002 which is most, if not all flavors of UNIX.
1003 1003
1004 1004
1005 1005 Registering a file descriptor to be watched by gl_get_line() involves
1006 1006 calling the gl_watch_fd() function. If this returns non-zero, then it
1007 1007 means that either your arguments are invalid, or that this facility is
1008 1008 not supported on the host system.
1009 1009
1010 1010
1011 1011 The fd argument is the file descriptor to be watched. The event
1012 1012 argument specifies what type of activity is of interest, chosen from
1013 1013 the following enumerated values:
1014 1014
1015 1015 GLFD_READ
1016 1016 Watch for the arrival of data to be read.
1017 1017
1018 1018
1019 1019 GLFD_WRITE
1020 1020 Watch for the ability to write to the file descriptor
1021 1021 without blocking.
1022 1022
1023 1023
1024 1024 GLFD_URGENT
1025 1025 Watch for the arrival of urgent out-of-band data on the
1026 1026 file descriptor.
1027 1027
1028 1028
1029 1029
1030 1030 The callback argument is the function to call when the selected
1031 1031 activity is seen. It should be defined with the following macro, which
1032 1032 is defined in libtecla.h.
1033 1033
1034 1034 #define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, void *data, int fd, GlFdEvent event)
1035 1035
1036 1036
1037 1037
1038 1038 The data argument of the gl_watch_fd() function is passed to the
1039 1039 callback function for its own use, and can point to anything you like,
1040 1040 including NULL. The file descriptor and the event argument are also
1041 1041 passed to the callback function, and this potentially allows the same
1042 1042 callback function to be registered to more than one type of event
1043 1043 and/or more than one file descriptor. The return value of the callback
1044 1044 function should be one of the following values.
1045 1045
1046 1046 GLFD_ABORT
1047 1047 Tell gl_get_line() to abort. When this happens,
1048 1048 gl_get_line() returns NULL, and a following call to
1049 1049 gl_return_status() will return GLR_FDABORT. Note that
1050 1050 if the application needs errno always to have a
1051 1051 meaningful value when gl_get_line() returns NULL, the
1052 1052 callback function should set errno appropriately.
1053 1053
1054 1054
1055 1055 GLFD_REFRESH
1056 1056 Redraw the input line then continue waiting for
1057 1057 input. Return this if your callback wrote to the
1058 1058 terminal.
1059 1059
1060 1060
1061 1061 GLFD_CONTINUE
1062 1062 Continue to wait for input, without redrawing the
1063 1063 line.
1064 1064
1065 1065
1066 1066
1067 1067 Note that before calling the callback, gl_get_line() blocks most
1068 1068 signals and leaves its own signal handlers installed, so if you need to
1069 1069 catch a particular signal you will need to both temporarily install
1070 1070 your own signal handler, and unblock the signal. Be sure to re-block
1071 1071 the signal (if it was originally blocked) and reinstate the original
1072 1072 signal handler, if any, before returning.
1073 1073
1074 1074
1075 1075 Your callback should not try to read from the terminal, which is left
1076 1076 in raw mode as far as input is concerned. You can write to the terminal
1077 1077 as usual, since features like conversion of newline to carriage-
1078 1078 return/linefeed are re-enabled while the callback is running. If your
1079 1079 callback function does write to the terminal, be sure to output a
1080 1080 newline first, and when your callback returns, tell gl_get_line() that
1081 1081 the input line needs to be redrawn, by returning the GLFD_REFRESH
1082 1082 status code.
1083 1083
1084 1084
1085 1085 To remove a callback function that you previously registered for a
1086 1086 given file descriptor and event, simply call gl_watch_fd() with the
1087 1087 same fd and event arguments, but with a callback argument of 0. The
1088 1088 data argument is ignored in this case.
1089 1089
1090 1090 Setting An Inactivity Timeout
1091 1091 The gl_inactivity_timeout() function can be used to set or cancel an
1092 1092 inactivity timeout. Inactivity in this case refers both to keyboard
1093 1093 input, and to I/O on any file descriptors registered by prior and
1094 1094 subsequent calls to gl_watch_fd().
1095 1095
1096 1096
1097 1097 The timeout is specified in the form of an integral number of seconds
1098 1098 and an integral number of nanoseconds, specified by the sec and nsec
1099 1099 arguments, respectively. Subsequently, whenever no activity is seen for
1100 1100 this time period, the function specified by the callback argument is
1101 1101 called. The data argument of gl_inactivity_timeout() is passed to this
1102 1102 callback function whenever it is invoked, and can thus be used to pass
1103 1103 arbitrary application-specific information to the callback. The
1104 1104 following macro is provided in <libtecla.h> for applications to use to
1105 1105 declare and prototype timeout callback functions.
1106 1106
1107 1107 #define GL_TIMEOUT_FN(fn) GlAfterTimeout (fn)(GetLine *gl, void *data)
1108 1108
1109 1109
1110 1110
1111 1111 On returning, the application's callback is expected to return one of
1112 1112 the following enumerators to tell gl_get_line() how to proceed after
1113 1113 the timeout has been handled by the callback.
1114 1114
1115 1115 GLTO_ABORT
1116 1116 Tell gl_get_line() to abort. When this happens,
1117 1117 gl_get_line() will return NULL, and a following call
1118 1118 to gl_return_status() will return GLR_TIMEOUT. Note
1119 1119 that if the application needs errno always to have a
1120 1120 meaningful value when gl_get_line() returns NULL, the
1121 1121 callback function should set errno appropriately.
1122 1122
1123 1123
1124 1124 GLTO_REFRESH
1125 1125 Redraw the input line, then continue waiting for
1126 1126 input. You should return this value if your callback
1127 1127 wrote to the terminal.
1128 1128
1129 1129
1130 1130 GLTO_CONTINUE
1131 1131 In normal blocking-I/O mode, continue to wait for
1132 1132 input, without redrawing the user's input line. In
1133 1133 non-blocking server I/O mode (see gl_io_mode(3TECLA)),
1134 1134 gl_get_line() acts as though I/O blocked. This means
1135 1135 that gl_get_line() will immediately return NULL, and a
1136 1136 following call to gl_return_status() will return
1137 1137 GLR_BLOCKED.
1138 1138
1139 1139
1140 1140
1141 1141 Note that before calling the callback, gl_get_line() blocks most
1142 1142 signals and leaves its own signal handlers installed, so if you need to
1143 1143 catch a particular signal you will need to both temporarily install
1144 1144 your own signal handler and unblock the signal. Be sure to re-block the
1145 1145 signal (if it was originally blocked) and reinstate the original signal
1146 1146 handler, if any, before returning.
1147 1147
1148 1148
1149 1149 Your callback should not try to read from the terminal, which is left
1150 1150 in raw mode as far as input is concerned. You can however write to the
1151 1151 terminal as usual, since features like conversion of newline to
1152 1152 carriage-return/linefeed are re-enabled while the callback is running.
1153 1153 If your callback function does write to the terminal, be sure to output
1154 1154 a newline first, and when your callback returns, tell gl_get_line()
1155 1155 that the input line needs to be redrawn, by returning the GLTO_REFRESH
1156 1156 status code.
1157 1157
1158 1158
1159 1159 Finally, note that although the timeout arguments include a nanosecond
1160 1160 component, few computer clocks presently have resolutions that are
1161 1161 finer than a few milliseconds, so asking for less than a few
1162 1162 milliseconds is equivalent to requesting zero seconds on many systems.
1163 1163 If this would be a problem, you should base your timeout selection on
1164 1164 the actual resolution of the host clock (for example, by calling
1165 1165 sysconf(_SC_CLK_TCK)).
1166 1166
1167 1167
1168 1168 To turn off timeouts, simply call gl_inactivity_timeout() with a
1169 1169 callback argument of 0. The data argument is ignored in this case.
1170 1170
1171 1171 Signal Handling Defaults
1172 1172 By default, the gl_get_line() function intercepts a number of signals.
1173 1173 This is particularly important for signals that would by default
1174 1174 terminate the process, since the terminal needs to be restored to a
1175 1175 usable state before this happens. This section describes the signals
1176 1176 that are trapped by default and how gl_get_line() responds to them.
1177 1177 Changing these defaults is the topic of the following section.
1178 1178
1179 1179
1180 1180 When the following subset of signals are caught, gl_get_line() first
1181 1181 restores the terminal settings and signal handling to how they were
1182 1182 before gl_get_line() was called, resends the signal to allow the
1183 1183 calling application's signal handlers to handle it, then, if the
1184 1184 process still exists, returns NULL and sets errno as specified below.
1185 1185
1186 1186 SIGINT
1187 1187 This signal is generated both by the keyboard interrupt key
1188 1188 (usually ^C), and the keyboard break key. The errno value is
1189 1189 EINTR.
1190 1190
1191 1191
1192 1192 SIGHUP
1193 1193 This signal is generated when the controlling terminal
1194 1194 exits. The errno value is ENOTTY.
1195 1195
1196 1196
1197 1197 SIGPIPE
1198 1198 This signal is generated when a program attempts to write to
1199 1199 a pipe whose remote end is not being read by any process.
1200 1200 This can happen for example if you have called
1201 1201 gl_change_terminal() to redirect output to a pipe hidden
1202 1202 under a pseudo terminal. The errno value is EPIPE.
1203 1203
1204 1204
1205 1205 SIGQUIT
1206 1206 This signal is generated by the keyboard quit key (usually
1207 1207 ^\). The errno value is EINTR.
1208 1208
1209 1209
1210 1210 SIGABRT
1211 1211 This signal is generated by the standard C, abort function.
1212 1212 By default it both terminates the process and generates a
1213 1213 core dump. The errno value is EINTR.
1214 1214
1215 1215
1216 1216 SIGTERM
1217 1217 This is the default signal that the UNIX kill command sends
1218 1218 to processes. The errno value is EINTR.
1219 1219
1220 1220
1221 1221
1222 1222 Note that in the case of all of the above signals, POSIX mandates that
1223 1223 by default the process is terminated, with the addition of a core dump
1224 1224 in the case of the SIGQUIT signal. In other words, if the calling
1225 1225 application does not override the default handler by supplying its own
1226 1226 signal handler, receipt of the corresponding signal will terminate the
1227 1227 application before gl_get_line() returns.
1228 1228
1229 1229
1230 1230 If gl_get_line() aborts with errno set to EINTR, you can find out what
1231 1231 signal caused it to abort, by calling the gl_last_signal() function.
1232 1232 This returns the numeric code (for example, SIGINT) of the last signal
1233 1233 that was received during the most recent call to gl_get_line(), or -1
1234 1234 if no signals were received.
1235 1235
1236 1236
1237 1237 On systems that support it, when a SIGWINCH (window change) signal is
1238 1238 received, gl_get_line() queries the terminal to find out its new size,
1239 1239 redraws the current input line to accommodate the new size, then
1240 1240 returns to waiting for keyboard input from the user. Unlike other
1241 1241 signals, this signal is not resent to the application.
1242 1242
1243 1243
1244 1244 Finally, the following signals cause gl_get_line() to first restore the
1245 1245 terminal and signal environment to that which prevailed before
1246 1246 gl_get_line() was called, then resend the signal to the application. If
1247 1247 the process still exists after the signal has been delivered, then
1248 1248 gl_get_line() then re-establishes its own signal handlers, switches the
1249 1249 terminal back to raw mode, redisplays the input line, and goes back to
1250 1250 awaiting terminal input from the user.
1251 1251
1252 1252 SIGCONT
1253 1253 This signal is generated when a suspended process is
1254 1254 resumed.
1255 1255
1256 1256
1257 1257 SIGPOLL
1258 1258 On SVR4 systems, this signal notifies the process of an
1259 1259 asynchronous I/O event. Note that under 4.3+BSD, SIGIO
1260 1260 and SIGPOLL are the same. On other systems, SIGIO is
1261 1261 ignored by default, so gl_get_line() does not trap it by
1262 1262 default.
1263 1263
1264 1264
1265 1265 SIGPWR
1266 1266 This signal is generated when a power failure occurs
1267 1267 (presumably when the system is on a UPS).
1268 1268
1269 1269
1270 1270 SIGALRM
1271 1271 This signal is generated when a timer expires.
1272 1272
1273 1273
1274 1274 SIGUSR1
1275 1275 An application specific signal.
1276 1276
1277 1277
1278 1278 SIGUSR2
1279 1279 Another application specific signal.
1280 1280
1281 1281
1282 1282 SIGVTALRM
1283 1283 This signal is generated when a virtual timer expires. See
1284 1284 setitimer(2).
1285 1285
1286 1286
1287 1287 SIGXCPU
1288 1288 This signal is generated when a process exceeds its soft
1289 1289 CPU time limit.
1290 1290
1291 1291
1292 1292 SIGXFSZ
1293 1293 This signal is generated when a process exceeds its soft
1294 1294 file-size limit.
1295 1295
1296 1296
1297 1297 SIGTSTP
1298 1298 This signal is generated by the terminal suspend key,
1299 1299 which is usually ^Z, or the delayed terminal suspend key,
1300 1300 which is usually ^Y.
1301 1301
1302 1302
1303 1303 SIGTTIN
1304 1304 This signal is generated if the program attempts to read
1305 1305 from the terminal while the program is running in the
1306 1306 background.
1307 1307
1308 1308
1309 1309 SIGTTOU
1310 1310 This signal is generated if the program attempts to write
1311 1311 to the terminal while the program is running in the
1312 1312 background.
1313 1313
1314 1314
1315 1315
1316 1316 Obviously not all of the above signals are supported on all systems, so
1317 1317 code to support them is conditionally compiled into the tecla library.
1318 1318
1319 1319
1320 1320 Note that if SIGKILL or SIGPOLL, which by definition cannot be caught,
1321 1321 or any of the hardware generated exception signals, such as SIGSEGV,
1322 1322 SIGBUS, and SIGFPE, are received and unhandled while gl_get_line() has
1323 1323 the terminal in raw mode, the program will be terminated without the
1324 1324 terminal having been restored to a usable state. In practice, job-
1325 1325 control shells usually reset the terminal settings when a process
1326 1326 relinquishes the controlling terminal, so this is only a problem with
1327 1327 older shells.
1328 1328
1329 1329 Customized Signal Handling
1330 1330 The previous section listed the signals that gl_get_line() traps by
1331 1331 default, and described how it responds to them. This section describes
1332 1332 how to both add and remove signals from the list of trapped signals,
1333 1333 and how to specify how gl_get_line() should respond to a given signal.
1334 1334
1335 1335
1336 1336 If you do not need gl_get_line() to do anything in response to a signal
1337 1337 that it normally traps, you can tell to gl_get_line() to ignore that
1338 1338 signal by calling gl_ignore_signal().
1339 1339
1340 1340
1341 1341 The signo argument is the number of the signal (for example, SIGINT)
1342 1342 that you want to have ignored. If the specified signal is not currently
1343 1343 one of those being trapped, this function does nothing.
1344 1344
1345 1345
1346 1346 The gl_trap_signal() function allows you to either add a new signal to
1347 1347 the list that gl_get_line() traps or modify how it responds to a signal
1348 1348 that it already traps.
1349 1349
1350 1350
1351 1351 The signo argument is the number of the signal that you want to have
1352 1352 trapped. The flags argument is a set of flags that determine the
1353 1353 environment in which the application's signal handler is invoked. The
1354 1354 after argument tells gl_get_line() what to do after the application's
1355 1355 signal handler returns. The errno_value tells gl_get_line() what to set
1356 1356 errno to if told to abort.
1357 1357
1358 1358
1359 1359 The flags argument is a bitwise OR of zero or more of the following
1360 1360 enumerators:
1361 1361
1362 1362 GLS_RESTORE_SIG
1363 1363 Restore the caller's signal environment while
1364 1364 handling the signal.
1365 1365
1366 1366
1367 1367 GLS_RESTORE_TTY
1368 1368 Restore the caller's terminal settings while
1369 1369 handling the signal.
1370 1370
1371 1371
1372 1372 GLS_RESTORE_LINE
1373 1373 Move the cursor to the start of the line following
1374 1374 the input line before invoking the application's
1375 1375 signal handler.
1376 1376
1377 1377
1378 1378 GLS_REDRAW_LINE
1379 1379 Redraw the input line when the application's signal
1380 1380 handler returns.
1381 1381
1382 1382
1383 1383 GLS_UNBLOCK_SIG
1384 1384 Normally, if the calling program has a signal
1385 1385 blocked (see sigprocmask(2)), gl_get_line() does
1386 1386 not trap that signal. This flag tells gl_get_line()
1387 1387 to trap the signal and unblock it for the duration
1388 1388 of the call to gl_get_line().
1389 1389
1390 1390
1391 1391 GLS_DONT_FORWARD
1392 1392 If this flag is included, the signal will not be
1393 1393 forwarded to the signal handler of the calling
1394 1394 program.
1395 1395
1396 1396
1397 1397
1398 1398 Two commonly useful flag combinations are also enumerated as follows:
1399 1399
1400 1400 GLS_RESTORE_ENV
1401 1401 GLS_RESTORE_SIG | GLS_RESTORE_TTY |GLS_REDRAW_LINE
1402 1402
1403 1403
1404 1404 GLS_SUSPEND_INPUT
1405 1405 GLS_RESTORE_ENV | GLS_RESTORE_LINE
1406 1406
1407 1407
1408 1408
1409 1409 If your signal handler, or the default system signal handler for this
1410 1410 signal, if you have not overridden it, never either writes to the
1411 1411 terminal, nor suspends or terminates the calling program, then you can
1412 1412 safely set the flags argument to 0.
1413 1413
1414 1414 o The cursor does not get left in the middle of the input
1415 1415 line.
1416 1416
1417 1417 o So that the user can type in input and have it echoed.
1418 1418
1419 1419 o So that you do not need to end each output line with \r\n,
1420 1420 instead of just \n.
1421 1421
1422 1422
1423 1423 The GL_RESTORE_ENV combination is the same as GL_SUSPEND_INPUT, except
1424 1424 that it does not move the cursor. If your signal handler does not read
1425 1425 or write anything to the terminal, the user will not see any visible
1426 1426 indication that a signal was caught. This can be useful if you have a
1427 1427 signal handler that only occasionally writes to the terminal, where
1428 1428 using GL_SUSPEND_LINE would cause the input line to be unnecessarily
|
↓ open down ↓ |
675 lines elided |
↑ open up ↑ |
1429 1429 duplicated when nothing had been written to the terminal. Such a signal
1430 1430 handler, when it does write to the terminal, should be sure to start a
1431 1431 new line at the start of its first write, by writing a new line before
1432 1432 returning. If the signal arrives while the user is entering a line that
1433 1433 only occupies a signal terminal line, or if the cursor is on the last
1434 1434 terminal line of a longer input line, this will have the same effect as
1435 1435 GL_SUSPEND_INPUT. Otherwise it will start writing on a line that
1436 1436 already contains part of the displayed input line. This does not do any
1437 1437 harm, but it looks a bit ugly, which is why the GL_SUSPEND_INPUT
1438 1438 combination is better if you know that you are always going to be
1439 - writting to the terminal.
1439 + writing to the terminal.
1440 1440
1441 1441
1442 1442 The after argument, which determines what gl_get_line() does after the
1443 1443 application's signal handler returns (if it returns), can take any one
1444 1444 of the following values:
1445 1445
1446 1446 GLS_RETURN
1447 1447 Return the completed input line, just as though the
1448 1448 user had pressed the return key.
1449 1449
1450 1450
1451 1451 GLS_ABORT
1452 1452 Cause gl_get_line() to abort. When this happens,
1453 1453 gl_get_line() returns NULL, and a following call to
1454 1454 gl_return_status() will return GLR_SIGNAL. Note that if
1455 1455 the application needs errno always to have a meaningful
1456 1456 value when gl_get_line() returns NULL, the callback
1457 1457 function should set errno appropriately.
1458 1458
1459 1459
1460 1460 GLS_CONTINUE
1461 1461 Resume command line editing.
1462 1462
1463 1463
1464 1464
1465 1465 The errno_value argument is intended to be combined with the GLS_ABORT
1466 1466 option, telling gl_get_line() what to set the standard errno variable
1467 1467 to before returning NULL to the calling program. It can also, however,
1468 1468 be used with the GL_RETURN option, in case you want to have a way to
1469 1469 distinguish between an input line that was entered using the return
1470 1470 key, and one that was entered by the receipt of a signal.
1471 1471
1472 1472 Reliable Signal Handling
1473 1473 Signal handling is surprisingly hard to do reliably without race
1474 1474 conditions. In gl_get_line() a lot of care has been taken to allow
1475 1475 applications to perform reliable signal handling around gl_get_line().
1476 1476 This section explains how to make use of this.
1477 1477
1478 1478
1479 1479 As an example of the problems that can arise if the application is not
1480 1480 written correctly, imagine that one's application has a SIGINT signal
1481 1481 handler that sets a global flag. Now suppose that the application tests
1482 1482 this flag just before invoking gl_get_line(). If a SIGINT signal
1483 1483 happens to be received in the small window of time between the
1484 1484 statement that tests the value of this flag, and the statement that
1485 1485 calls gl_get_line(), then gl_get_line() will not see the signal, and
1486 1486 will not be interrupted. As a result, the application will not be able
1487 1487 to respond to the signal until the user gets around to finishing
1488 1488 entering the input line and gl_get_line() returns. Depending on the
1489 1489 application, this might or might not be a disaster, but at the very
1490 1490 least it would puzzle the user.
1491 1491
1492 1492
1493 1493 The way to avoid such problems is to do the following.
1494 1494
1495 1495 1. If needed, use the gl_trap_signal() function to configure
1496 1496 gl_get_line() to abort when important signals are caught.
1497 1497
1498 1498 2. Configure gl_get_line() such that if any of the signals that
1499 1499 it catches are blocked when gl_get_line() is called, they
1500 1500 will be unblocked automatically during times when
1501 1501 gl_get_line() is waiting for I/O. This can be done either on
1502 1502 a per signal basis, by calling the gl_trap_signal()
1503 1503 function, and specifying the GLS_UNBLOCK attribute of the
1504 1504 signal, or globally by calling the gl_catch_blocked()
1505 1505 function. This function simply adds the GLS_UNBLOCK
1506 1506 attribute to all of the signals that it is currently
1507 1507 configured to trap.
1508 1508
1509 1509 3. Just before calling gl_get_line(), block delivery of all of
1510 1510 the signals that gl_get_line() is configured to trap. This
1511 1511 can be done using the POSIX sigprocmask function in
1512 1512 conjunction with the gl_list_signals() function. This
1513 1513 function returns the set of signals that it is currently
1514 1514 configured to catch in the set argument, which is in the
1515 1515 form required by sigprocmask(2).
1516 1516
1517 1517 4. In the example, one would now test the global flag that the
1518 1518 signal handler sets, knowing that there is now no danger of
1519 1519 this flag being set again until gl_get_line() unblocks its
1520 1520 signals while performing I/O.
1521 1521
1522 1522 5. Eventually gl_get_line() returns, either because a signal
1523 1523 was caught, an error occurred, or the user finished entering
1524 1524 their input line.
1525 1525
1526 1526 6. Now one would check the global signal flag again, and if it
1527 1527 is set, respond to it, and zero the flag.
1528 1528
1529 1529 7. Use sigprocmask() to unblock the signals that were blocked
1530 1530 in step 3.
1531 1531
1532 1532
1533 1533 The same technique can be used around certain POSIX signal-aware
1534 1534 functions, such as sigsetjmp(3C) and sigsuspend(2), and in particular,
1535 1535 the former of these two functions can be used in conjunction with
1536 1536 siglongjmp(3C) to implement race-condition free signal handling around
1537 1537 other long-running system calls. The gl_get_line() function manages to
1538 1538 reliably trap signals around calls to functions like read(2) and
1539 1539 select(3C) without race conditions.
1540 1540
1541 1541
1542 1542 The gl_get_line() function first uses the POSIX sigprocmask() function
1543 1543 to block the delivery of all of the signals that it is currently
1544 1544 configured to catch. This is redundant if the application has already
1545 1545 blocked them, but it does no harm. It undoes this step just before
1546 1546 returning.
1547 1547
1548 1548
1549 1549 Whenever gl_get_line() needs to call read or select to wait for input
1550 1550 from the user, it first calls the POSIX sigsetjmp() function, being
1551 1551 sure to specify a non-zero value for its savemask argument.
1552 1552
1553 1553
1554 1554 If sigsetjmp() returns zero, gl_get_line() then does the following.
1555 1555
1556 1556 1. It uses the POSIX sigaction(2) function to register a
1557 1557 temporary signal handler to all of the signals that it is
1558 1558 configured to catch. This signal handler does two things.
1559 1559
1560 1560 a. It records the number of the signal that was received in
1561 1561 a file-scope variable.
1562 1562
1563 1563 b. It then calls the POSIX siglongjmp() function using the
1564 1564 buffer that was passed to sigsetjmp() for its first
1565 1565 argument and a non-zero value for its second argument.
1566 1566 When this signal handler is registered, the sa_mask member of the
1567 1567 struct sigaction act argument of the call to sigaction() is
1568 1568 configured to contain all of the signals that gl_get_line() is
1569 1569 catching. This ensures that only one signal will be caught at once
1570 1570 by our signal handler, which in turn ensures that multiple
1571 1571 instances of our signal handler do not tread on each other's toes.
1572 1572
1573 1573 2. Now that the signal handler has been set up, gl_get_line()
1574 1574 unblocks all of the signals that it is configured to catch.
1575 1575
1576 1576 3. It then calls the read() or select() function to wait for
1577 1577 keyboard input.
1578 1578
1579 1579 4. If this function returns (that is, no signal is received),
1580 1580 gl_get_line() blocks delivery of the signals of interest
1581 1581 again.
1582 1582
1583 1583 5. It then reinstates the signal handlers that were displaced
1584 1584 by the one that was just installed.
1585 1585
1586 1586
1587 1587 Alternatively, if sigsetjmp() returns non-zero, this means that one of
1588 1588 the signals being trapped was caught while the above steps were
1589 1589 executing. When this happens, gl_get_line() does the following.
1590 1590
1591 1591
1592 1592 First, note that when a call to siglongjmp() causes sigsetjmp() to
1593 1593 return, provided that the savemask argument of sigsetjmp() was non-
1594 1594 zero, the signal process mask is restored to how it was when
1595 1595 sigsetjmp() was called. This is the important difference between
1596 1596 sigsetjmp() and the older problematic setjmp(3C), and is the essential
1597 1597 ingredient that makes it possible to avoid signal handling race
1598 1598 conditions. Because of this we are guaranteed that all of the signals
1599 1599 that we blocked before calling sigsetjmp() are blocked again as soon as
1600 1600 any signal is caught. The following statements, which are then
1601 1601 executed, are thus guaranteed to be executed without any further
1602 1602 signals being caught.
1603 1603
1604 1604 1. If so instructed by the gl_get_line() configuration
1605 1605 attributes of the signal that was caught, gl_get_line()
1606 1606 restores the terminal attributes to the state that they had
1607 1607 when gl_get_line() was called. This is particularly
1608 1608 important for signals that suspend or terminate the process,
1609 1609 since otherwise the terminal would be left in an unusable
1610 1610 state.
1611 1611
1612 1612 2. It then reinstates the application's signal handlers.
1613 1613
1614 1614 3. Then it uses the C standard-library raise(3C) function to
1615 1615 re-send the application the signal that was caught.
1616 1616
1617 1617 4. Next it unblocks delivery of the signal that we just sent.
1618 1618 This results in the signal that was just sent by raise()
1619 1619 being caught by the application's original signal handler,
1620 1620 which can now handle it as it sees fit.
1621 1621
1622 1622 5. If the signal handler returns (that is, it does not
1623 1623 terminate the process), gl_get_line() blocks delivery of the
1624 1624 above signal again.
1625 1625
1626 1626 6. It then undoes any actions performed in the first of the
1627 1627 above steps and redisplays the line, if the signal
1628 1628 configuration calls for this.
1629 1629
1630 1630 7. gl_get_line() then either resumes trying to read a
1631 1631 character, or aborts, depending on the configuration of the
1632 1632 signal that was caught.
1633 1633
1634 1634
1635 1635 What the above steps do in essence is to take asynchronously delivered
1636 1636 signals and handle them synchronously, one at a time, at a point in the
1637 1637 code where gl_get_line() has complete control over its environment.
1638 1638
1639 1639 The Terminal Size
1640 1640 On most systems the combination of the TIOCGWINSZ ioctl and the
1641 1641 SIGWINCH signal is used to maintain an accurate idea of the terminal
1642 1642 size. The terminal size is newly queried every time that gl_get_line()
1643 1643 is called and whenever a SIGWINCH signal is received.
1644 1644
1645 1645
1646 1646 On the few systems where this mechanism is not available, at startup
1647 1647 new_GetLine() first looks for the LINES and COLUMNS environment
1648 1648 variables. If these are not found, or they contain unusable values,
1649 1649 then if a terminal information database like terminfo or termcap is
1650 1650 available, the default size of the terminal is looked up in this
1651 1651 database. If this too fails to provide the terminal size, a default
1652 1652 size of 80 columns by 24 lines is used.
1653 1653
1654 1654
1655 1655 Even on systems that do support ioctl(TIOCGWINSZ), if the terminal is
1656 1656 on the other end of a serial line, the terminal driver generally has no
1657 1657 way of detecting when a resize occurs or of querying what the current
1658 1658 size is. In such cases no SIGWINCH is sent to the process, and the
1659 1659 dimensions returned by ioctl(TIOCGWINSZ) are not correct. The only way
1660 1660 to handle such instances is to provide a way for the user to enter a
1661 1661 command that tells the remote system what the new size is. This command
1662 1662 would then call the gl_set_term_size() function to tell gl_get_line()
1663 1663 about the change in size.
1664 1664
1665 1665
1666 1666 The ncolumn and nline arguments are used to specify the new dimensions
1667 1667 of the terminal, and must not be less than 1. On systems that do
1668 1668 support ioctl(TIOCGWINSZ), this function first calls ioctl(TIOCSWINSZ)
1669 1669 to tell the terminal driver about the change in size. In non-blocking
1670 1670 server-I/O mode, if a line is currently being input, the input line is
1671 1671 then redrawn to accommodate the changed size. Finally the new values
1672 1672 are recorded in gl for future use by gl_get_line().
1673 1673
1674 1674
1675 1675 The gl_terminal_size() function allows you to query the current size of
1676 1676 the terminal, and install an alternate fallback size for cases where
1677 1677 the size is not available. Beware that the terminal size will not be
1678 1678 available if reading from a pipe or a file, so the default values can
1679 1679 be important even on systems that do support ways of finding out the
1680 1680 terminal size.
1681 1681
1682 1682
1683 1683 This function first updates gl_get_line()'s fallback terminal
1684 1684 dimensions, then records its findings in the return value.
1685 1685
1686 1686
1687 1687 The def_ncolumn and def_nline arguments specify the default number of
1688 1688 terminal columns and lines to use if the terminal size cannot be
1689 1689 determined by ioctl(TIOCGWINSZ) or environment variables.
1690 1690
1691 1691 Hiding What You Type
1692 1692 When entering sensitive information, such as passwords, it is best not
1693 1693 to have the text that you are entering echoed on the terminal.
1694 1694 Furthermore, such text should not be recorded in the history list,
1695 1695 since somebody finding your terminal unattended could then recall it,
1696 1696 or somebody snooping through your directories could see it in your
1697 1697 history file. With this in mind, the gl_echo_mode() function allows you
1698 1698 to toggle on and off the display and archival of any text that is
1699 1699 subsequently entered in calls to gl_get_line().
1700 1700
1701 1701
1702 1702 The enable argument specifies whether entered text should be visible or
1703 1703 not. If it is 0, then subsequently entered lines will not be visible on
1704 1704 the terminal, and will not be recorded in the history list. If it is 1,
1705 1705 then subsequent input lines will be displayed as they are entered, and
1706 1706 provided that history has not been turned off with a call to
1707 1707 gl_toggle_history(), then they will also be archived in the history
1708 1708 list. Finally, if the enable argument is -1, then the echoing mode is
1709 1709 left unchanged, which allows you to non-destructively query the current
1710 1710 setting through the return value. In all cases, the return value of the
1711 1711 function is 0 if echoing was disabled before the function was called,
1712 1712 and 1 if it was enabled.
1713 1713
1714 1714
1715 1715 When echoing is turned off, note that although tab completion will
1716 1716 invisibly complete your prefix as far as possible, ambiguous
1717 1717 completions will not be displayed.
1718 1718
1719 1719 Single Character Queries
1720 1720 Using gl_get_line() to query the user for a single character reply, is
1721 1721 inconvenient for the user, since they must hit the enter or return key
1722 1722 before the character that they typed is returned to the program. Thus
1723 1723 the gl_query_char() function has been provided for single character
1724 1724 queries like this.
1725 1725
1726 1726
1727 1727 This function displays the specified prompt at the start of a new line,
1728 1728 and waits for the user to type a character. When the user types a
1729 1729 character, gl_query_char() displays it to the right of the prompt,
1730 1730 starts a newline, then returns the character to the calling program.
1731 1731 The return value of the function is the character that was typed. If
1732 1732 the read had to be aborted for some reason, EOF is returned instead. In
1733 1733 the latter case, the application can call the previously documented
1734 1734 gl_return_status(), to find out what went wrong. This could, for
1735 1735 example, have been the reception of a signal, or the optional
1736 1736 inactivity timer going off.
1737 1737
1738 1738
1739 1739 If the user simply hits enter, the value of the defchar argument is
1740 1740 substituted. This means that when the user hits either newline or
1741 1741 return, the character specified in defchar, is displayed after the
1742 1742 prompt, as though the user had typed it, as well as being returned to
1743 1743 the calling application. If such a replacement is not important, simply
1744 1744 pass '\n' as the value of defchar.
1745 1745
1746 1746
1747 1747 If the entered character is an unprintable character, it is displayed
1748 1748 symbolically. For example, control-A is displayed as ^A, and characters
1749 1749 beyond 127 are displayed in octal, preceded by a backslash.
1750 1750
1751 1751
1752 1752 As with gl_get_line(), echoing of the entered character can be disabled
1753 1753 using the gl_echo_mode() function.
1754 1754
1755 1755
1756 1756 If the calling process is suspended while waiting for the user to type
1757 1757 their response, the cursor is moved to the line following the prompt
1758 1758 line, then when the process resumes, the prompt is redisplayed, and
1759 1759 gl_query_char() resumes waiting for the user to type a character.
1760 1760
1761 1761
1762 1762 Note that in non-blocking server mode, if an incomplete input line is
1763 1763 in the process of being read when gl_query_char() is called, the
1764 1764 partial input line is discarded, and erased from the terminal, before
1765 1765 the new prompt is displayed. The next call to gl_get_line() will thus
1766 1766 start editing a new line.
1767 1767
1768 1768 Reading Raw Characters
1769 1769 Whereas the gl_query_char() function visibly prompts the user for a
1770 1770 character, and displays what they typed, the gl_read_char() function
1771 1771 reads a signal character from the user, without writing anything to the
1772 1772 terminal, or perturbing any incompletely entered input line. This means
1773 1773 that it can be called not only from between calls to gl_get_line(), but
1774 1774 also from callback functions that the application has registered to be
1775 1775 called by gl_get_line().
1776 1776
1777 1777
1778 1778 On success, the return value of gl_read_char() is the character that
1779 1779 was read. On failure, EOF is returned, and the gl_return_status()
1780 1780 function can be called to find out what went wrong. Possibilities
1781 1781 include the optional inactivity timer going off, the receipt of a
1782 1782 signal that is configured to abort gl_get_line(), or terminal I/O
1783 1783 blocking, when in non-blocking server-I/O mode.
1784 1784
1785 1785
1786 1786 Beware that certain keyboard keys, such as function keys, and cursor
1787 1787 keys, usually generate at least three characters each, so a single call
1788 1788 to gl_read_char() will not be enough to identify such keystrokes.
1789 1789
1790 1790 Clearing The Terminal
1791 1791 The calling program can clear the terminal by calling
1792 1792 gl_erase_terminal(). In non-blocking server-I/O mode, this function
1793 1793 also arranges for the current input line to be redrawn from scratch
1794 1794 when gl_get_line() is next called.
1795 1795
1796 1796 Displaying Text Dynamically
1797 1797 Between calls to gl_get_line(), the gl_display_text() function provides
1798 1798 a convenient way to display paragraphs of text, left-justified and
1799 1799 split over one or more terminal lines according to the constraints of
1800 1800 the current width of the terminal. Examples of the use of this function
1801 1801 may be found in the demo programs, where it is used to display
1802 1802 introductions. In those examples the advanced use of optional
1803 1803 prefixes, suffixes and filled lines to draw a box around the text is
1804 1804 also illustrated.
1805 1805
1806 1806
1807 1807 If gl is not currently connected to a terminal, for example if the
1808 1808 output of a program that uses gl_get_line() is being piped to another
1809 1809 program or redirected to a file, then the value of the def_width
1810 1810 parameter is used as the terminal width.
1811 1811
1812 1812
1813 1813 The indentation argument specifies the number of characters to use to
1814 1814 indent each line of output. The fill_char argument specifies the
1815 1815 character that will be used to perform this indentation.
1816 1816
1817 1817
1818 1818 The prefix argument can be either NULL or a string to place at the
1819 1819 beginning of each new line (after any indentation). Similarly, the
1820 1820 suffix argument can be either NULL or a string to place at the end of
1821 1821 each line. The suffix is placed flush against the right edge of the
1822 1822 terminal, and any space between its first character and the last word
1823 1823 on that line is filled with the character specified by the fill_char
1824 1824 argument. Normally the fill-character is a space.
1825 1825
1826 1826
1827 1827 The start argument tells gl_display_text() how many characters have
1828 1828 already been written to the current terminal line, and thus tells it
1829 1829 the starting column index of the cursor. Since the return value of
1830 1830 gl_display_text() is the ending column index of the cursor, by passing
1831 1831 the return value of one call to the start argument of the next call, a
1832 1832 paragraph that is broken between more than one string can be composed
1833 1833 by calling gl_display_text() for each successive portion of the
1834 1834 paragraph. Note that literal newline characters are necessary at the
1835 1835 end of each paragraph to force a new line to be started.
1836 1836
1837 1837
1838 1838 On error, gl_display_text() returns -1.
1839 1839
1840 1840 Callback Function Facilities
1841 1841 Unless otherwise stated, callback functions such as tab completion
1842 1842 callbacks and event callbacks should not call any functions in this
1843 1843 module. The following functions, however, are designed specifically to
1844 1844 be used by callback functions.
1845 1845
1846 1846
1847 1847 Calling the gl_replace_prompt() function from a callback tells
1848 1848 gl_get_line() to display a different prompt when the callback returns.
1849 1849 Except in non-blocking server mode, it has no effect if used between
1850 1850 calls to gl_get_line(). In non-blocking server mode, when used between
1851 1851 two calls to gl_get_line() that are operating on the same input line,
1852 1852 the current input line will be re-drawn with the new prompt on the
1853 1853 following call to gl_get_line().
1854 1854
1855 1855 International Character Sets
1856 1856 Since libtecla(3LIB) version 1.4.0, gl_get_line() has been 8-bit clean.
1857 1857 This means that all 8-bit characters that are printable in the user's
1858 1858 current locale are now displayed verbatim and included in the returned
1859 1859 input line. Assuming that the calling program correctly contains a call
1860 1860 like the following,
1861 1861
1862 1862 setlocale(LC_CTYPE, "")
1863 1863
1864 1864
1865 1865
1866 1866 then the current locale is determined by the first of the environment
1867 1867 variables LC_CTYPE, LC_ALL, and LANG that is found to contain a valid
1868 1868 locale name. If none of these variables are defined, or the program
1869 1869 neglects to call setlocale(3C), then the default C locale is used,
1870 1870 which is US 7-bit ASCII. On most UNIX-like platforms, you can get a
1871 1871 list of valid locales by typing the command:
1872 1872
1873 1873 locale -a
1874 1874
1875 1875
1876 1876
1877 1877
1878 1878 at the shell prompt. Further documentation on how the user can make use
1879 1879 of this to enter international characters can be found in the tecla(5)
1880 1880 man page.
1881 1881
1882 1882 Thread Safety
1883 1883 Unfortunately neither terminfo nor termcap were designed to be
1884 1884 reentrant, so you cannot safely use the functions of the getline module
1885 1885 in multiple threads (you can use the separate file-expansion and word-
1886 1886 completion modules in multiple threads, see the corresponding man pages
1887 1887 for details). However due to the use of POSIX reentrant functions for
1888 1888 looking up home directories, it is safe to use this module from a
1889 1889 single thread of a multi-threaded program, provided that your other
1890 1890 threads do not use any termcap or terminfo functions.
1891 1891
1892 1892 ATTRIBUTES
1893 1893 See attributes(5) for descriptions of the following attributes:
1894 1894
1895 1895
1896 1896
1897 1897
1898 1898 +--------------------+-----------------+
1899 1899 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
1900 1900 +--------------------+-----------------+
1901 1901 |Interface Stability | Committed |
|
↓ open down ↓ |
452 lines elided |
↑ open up ↑ |
1902 1902 +--------------------+-----------------+
1903 1903 |MT-Level | MT-Safe |
1904 1904 +--------------------+-----------------+
1905 1905
1906 1906 SEE ALSO
1907 1907 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_io_mode(3TECLA),
1908 1908 libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5), tecla(5)
1909 1909
1910 1910
1911 1911
1912 - April 9, 2016 GL_GET_LINE(3TECLA)
1912 + January 18, 2020 GL_GET_LINE(3TECLA)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX