42 GL_NORMAL_MODE
43 Select the normal blocking-I/O mode. In this mode
44 gl_get_line() does not return until either an error
45 occurs of the user finishes entering a new line.
46
47
48 GL_SERVER_MODE
49 Select non-blocking server I/O mode. In this mode,
50 since non-blocking terminal I/O is used, the entry of
51 each new input line typically requires many calls to
52 gl_get_line() from an external I/O-driven event loop.
53
54
55
56 Newly created GetLine objects start in normal I/O mode, so to switch to
57 non-blocking server mode requires an initial call to gl_io_mode().
58
59 Server I/O Mode
60 In non-blocking server I/O mode, the application is required to have an
61 event loop that calls gl_get_line() whenever the terminal file
62 descriptor can perform the type I/O that gl_get_line() is waiting for.
63 To determine which type of I/O gl_get_line() is waiting for, the
64 application calls the gl_pending_io() function. The return value is
65 one of the following two enumerated values.
66
67 GLP_READ
68 gl_get_line() is waiting to write a character to the
69 terminal.
70
71
72 GLP_WRITE
73 gl_get_line() is waiting to read a character from the
74 keyboad.
75
76
77
78 If the application is using either the select(3C) or poll(2) function
79 to watch for I/O on a group of file descriptors, then it should call
80 the gl_pending_io() function before each call to these functions to
81 determine which direction of I/O it should tell them to watch for, and
82 configure their arguments accordingly. In the case of the select()
83 function, this means using the FD_SET() macro to add the terminal file
84 descriptor either to the set of file descriptors to be watched for
85 readability or the set to be watched for writability.
86
87
88 As in normal I/O mode, the return value of gl_get_line() is either a
89 pointer to a completed input line or NULL. However, whereas in normal
90 I/O mode a NULL return value always means that an error occurred, in
91 non-blocking server mode, NULL is also returned when gl_get_line()
92 cannot read or write to the terminal without blocking. Thus in non-
93 blocking server mode, in order to determine when a NULL return value
94 signifies that an error occurred or not, it is necessary to call the
323 8. Now call select() or poll().
324
325 9. When select returns, again block the signals that were
326 unblocked in step 7.
327
328 If a signal is arrived any time during the above steps, our
329 signal handler will be triggered and cause control to return
330 to the sigsetjmp() statement, where this time, sigsetjmp()
331 will return non-zero, indicating that a signal was caught.
332 When this happens we simply skip the above block of
333 statements, and continue with the following statements,
334 which are executed regardless of whether or not a signal is
335 caught. Note that when sigsetjmp() returns, regardless of
336 why it returned, the process signal mask is returned to how
337 it was when sigsetjmp() was called. Thus the following
338 statements are always executed with all of our signals
339 blocked.
340
341 10. Reinstate the signal handlers that were displaced in step 5.
342
343 11. Check wether a signal was caught, by checking the file-scope
344 variable that the signal handler records signal numbers in.
345
346 12. If a signal was caught, send this signal to the application
347 again and unblock only this signal so that it invokes the
348 signal handler which was just reinstated in step 10.
349
350 13. Unblock all of the signals that were blocked in step 7.
351
352 Signals Caught By gl_get_line()
353 Since the application is expected to handle signals in non-blocking
354 server mode, gl_get_line() does not attempt to duplicate this when it
355 is being called. If one of the signals that it is configured to catch
356 is sent to the application while gl_get_line() is being called,
357 gl_get_line() reinstates the caller's signal handlers, then immediately
358 before returning, re-sends the signal to the process to let the
359 application's signal handler handle it. If the process is not
360 terminated by this signal, gl_get_line() returns NULL, and a following
361 call to gl_return_status() returns the enumerated value GLR_SIGNAL.
362
363 Aborting Line Input
364 Often, rather than letting it terminate the process, applications
365 respond to the SIGINT user-interrupt signal by aborting the current
366 input line. This can be accomplished in non-blocking server-I/O mode by
367 not calling gl_handle_signal() when this signal is caught, but by
368 calling instead the gl_abandon_line() function. This function arranges
369 that when gl_get_line() is next called, it first flushes any pending
370 output to the terminal, discardes the current input line, outputs a new
371 prompt on the next line, and finally starts accepting input of a new
372 input line from the user.
373
374 Signal Safe Functions
375 Provided that certain rules are followed, the gl_normal_io(),
376 gl_raw_io(), gl_handle_signal(), and gl_abandon_line() functions can be
377 written to be safely callable from signal handlers. Other functions in
378 this library should not be called from signal handlers. For this to be
379 true, all signal handlers that call these functions must be registered
380 in such a way that only one instance of any one of them can be running
381 at one time. The way to do this is to use the POSIX sigaction()
382 function to register all signal handlers, and when doing this, use the
383 sa_mask member of the corresponding sigaction structure to indicate
384 that all of the signals whose handlers invoke the above functions
385 should be blocked when the current signal is being handled. This
386 prevents two signal handlers from operating on a GetLine object at the
387 same time.
388
389
390 To prevent signal handlers from accessing a GetLine object while
418 ATTRIBUTES
419 See attributes(5) for descriptions of the following attributes:
420
421
422
423
424 +--------------------+-----------------+
425 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
426 +--------------------+-----------------+
427 |Interface Stability | Evolving |
428 +--------------------+-----------------+
429 |MT-Level | MT-Safe |
430 +--------------------+-----------------+
431
432 SEE ALSO
433 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
434 libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5), tecla(5)
435
436
437
438 June 1, 2004 GL_IO_MODE(3TECLA)
|
42 GL_NORMAL_MODE
43 Select the normal blocking-I/O mode. In this mode
44 gl_get_line() does not return until either an error
45 occurs of the user finishes entering a new line.
46
47
48 GL_SERVER_MODE
49 Select non-blocking server I/O mode. In this mode,
50 since non-blocking terminal I/O is used, the entry of
51 each new input line typically requires many calls to
52 gl_get_line() from an external I/O-driven event loop.
53
54
55
56 Newly created GetLine objects start in normal I/O mode, so to switch to
57 non-blocking server mode requires an initial call to gl_io_mode().
58
59 Server I/O Mode
60 In non-blocking server I/O mode, the application is required to have an
61 event loop that calls gl_get_line() whenever the terminal file
62 descriptor can perform the type of I/O that gl_get_line() is waiting
63 for. To determine which type of I/O gl_get_line() is waiting for, the
64 application calls the gl_pending_io() function. The return value is
65 one of the following two enumerated values.
66
67 GLP_READ
68 gl_get_line() is waiting to write a character to the
69 terminal.
70
71
72 GLP_WRITE
73 gl_get_line() is waiting to read a character from the
74 keyboard.
75
76
77
78 If the application is using either the select(3C) or poll(2) function
79 to watch for I/O on a group of file descriptors, then it should call
80 the gl_pending_io() function before each call to these functions to
81 determine which direction of I/O it should tell them to watch for, and
82 configure their arguments accordingly. In the case of the select()
83 function, this means using the FD_SET() macro to add the terminal file
84 descriptor either to the set of file descriptors to be watched for
85 readability or the set to be watched for writability.
86
87
88 As in normal I/O mode, the return value of gl_get_line() is either a
89 pointer to a completed input line or NULL. However, whereas in normal
90 I/O mode a NULL return value always means that an error occurred, in
91 non-blocking server mode, NULL is also returned when gl_get_line()
92 cannot read or write to the terminal without blocking. Thus in non-
93 blocking server mode, in order to determine when a NULL return value
94 signifies that an error occurred or not, it is necessary to call the
323 8. Now call select() or poll().
324
325 9. When select returns, again block the signals that were
326 unblocked in step 7.
327
328 If a signal is arrived any time during the above steps, our
329 signal handler will be triggered and cause control to return
330 to the sigsetjmp() statement, where this time, sigsetjmp()
331 will return non-zero, indicating that a signal was caught.
332 When this happens we simply skip the above block of
333 statements, and continue with the following statements,
334 which are executed regardless of whether or not a signal is
335 caught. Note that when sigsetjmp() returns, regardless of
336 why it returned, the process signal mask is returned to how
337 it was when sigsetjmp() was called. Thus the following
338 statements are always executed with all of our signals
339 blocked.
340
341 10. Reinstate the signal handlers that were displaced in step 5.
342
343 11. Check whether a signal was caught, by checking the file-
344 scope variable that the signal handler records signal
345 numbers in.
346
347 12. If a signal was caught, send this signal to the application
348 again and unblock only this signal so that it invokes the
349 signal handler which was just reinstated in step 10.
350
351 13. Unblock all of the signals that were blocked in step 7.
352
353 Signals Caught By gl_get_line()
354 Since the application is expected to handle signals in non-blocking
355 server mode, gl_get_line() does not attempt to duplicate this when it
356 is being called. If one of the signals that it is configured to catch
357 is sent to the application while gl_get_line() is being called,
358 gl_get_line() reinstates the caller's signal handlers, then immediately
359 before returning, re-sends the signal to the process to let the
360 application's signal handler handle it. If the process is not
361 terminated by this signal, gl_get_line() returns NULL, and a following
362 call to gl_return_status() returns the enumerated value GLR_SIGNAL.
363
364 Aborting Line Input
365 Often, rather than letting it terminate the process, applications
366 respond to the SIGINT user-interrupt signal by aborting the current
367 input line. This can be accomplished in non-blocking server-I/O mode by
368 not calling gl_handle_signal() when this signal is caught, but by
369 calling instead the gl_abandon_line() function. This function arranges
370 that when gl_get_line() is next called, it first flushes any pending
371 output to the terminal, discards the current input line, outputs a new
372 prompt on the next line, and finally starts accepting input of a new
373 input line from the user.
374
375 Signal Safe Functions
376 Provided that certain rules are followed, the gl_normal_io(),
377 gl_raw_io(), gl_handle_signal(), and gl_abandon_line() functions can be
378 written to be safely callable from signal handlers. Other functions in
379 this library should not be called from signal handlers. For this to be
380 true, all signal handlers that call these functions must be registered
381 in such a way that only one instance of any one of them can be running
382 at one time. The way to do this is to use the POSIX sigaction()
383 function to register all signal handlers, and when doing this, use the
384 sa_mask member of the corresponding sigaction structure to indicate
385 that all of the signals whose handlers invoke the above functions
386 should be blocked when the current signal is being handled. This
387 prevents two signal handlers from operating on a GetLine object at the
388 same time.
389
390
391 To prevent signal handlers from accessing a GetLine object while
419 ATTRIBUTES
420 See attributes(5) for descriptions of the following attributes:
421
422
423
424
425 +--------------------+-----------------+
426 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
427 +--------------------+-----------------+
428 |Interface Stability | Evolving |
429 +--------------------+-----------------+
430 |MT-Level | MT-Safe |
431 +--------------------+-----------------+
432
433 SEE ALSO
434 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
435 libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5), tecla(5)
436
437
438
439 January 18, 2020 GL_IO_MODE(3TECLA)
|