8 .\" to whom the Software is furnished to do so, provided that the above
9 .\" copyright notice(s) and this permission notice appear in all copies of
10 .\" the Software and that both the above copyright notice(s) and this
11 .\" permission notice appear in supporting documentation.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
15 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
16 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
17 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
18 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
19 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
20 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
21 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22 .\"
23 .\" Except as contained in this notice, the name of a copyright holder
24 .\" shall not be used in advertising or otherwise to promote the sale, use
25 .\" or other dealings in this Software without prior written authorization
26 .\" of the copyright holder.
27 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
28 .TH GL_IO_MODE 3TECLA "Jun 1, 2004"
29 .SH NAME
30 gl_io_mode, gl_raw_io, gl_normal_io, gl_tty_signals, gl_abandon_line,
31 gl_handle_signal, gl_pending_io \- use \fBgl_get_line()\fR from an external
32 event loop
33 .SH SYNOPSIS
34 .LP
35 .nf
36 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
37 #include <libtecla.h>
38
39 \fBint\fR \fBgl_io_mode\fR(\fBGetLine *\fR\fIgl\fR, \fBGlIOMode\fR \fImode\fR);
40 .fi
41
42 .LP
43 .nf
44 \fBint\fR \fBgl_raw_io\fR(\fBGetLine *\fR\fIgl\fR);
45 .fi
46
47 .LP
48 .nf
49 \fBint\fR \fBgl_normal_io\fR(\fBGetLine *\fR\fIgl\fR);
50 .fi
51
52 .LP
53 .nf
54 \fBint\fR \fBgl_tty_signals\fR(\fBvoid (*\fR\fIterm_handler\fR)(int), \fBvoid (*\fR\fIsusp_handler\fR)(int),
55 \fBvoid (*\fR\fIcont_handler\fR)(int), \fBvoid (*\fR\fIsize_handler\fR)(int));
56 .fi
57
58 .LP
59 .nf
60 \fBvoid\fR \fBgl_abandon_line\fR(\fBGetLine *\fR\fIgl\fR);
61 .fi
62
63 .LP
64 .nf
65 \fBvoid\fR \fBgl_handle_signal\fR(\fBint\fR \fIsigno\fR, \fBGetLine *\fR\fIgl\fR, \fBint\fR \fIngl\fR);
66 .fi
67
68 .LP
69 .nf
70 \fBGlPendingIO\fR \fBgl_pending_io\fR(\fBGetLine *\fR\fIgl\fR);
71 .fi
72
73 .SH DESCRIPTION
74 .sp
75 .LP
76 The \fBgl_get_line\fR(3TECLA) function supports two different I/O modes. These
77 are selected by calling the \fBgl_io_mode()\fR function. The \fImode\fR
78 argument of \fBgl_io_mode()\fR specifies the new I/O mode and must be one of
79 the following.
80 .sp
81 .ne 2
82 .na
83 \fB\fBGL_NORMAL_MODE\fR\fR
84 .ad
85 .RS 18n
86 Select the normal blocking-I/O mode. In this mode \fBgl_get_line()\fR does not
87 return until either an error occurs of the user finishes entering a new line.
88 .RE
89
90 .sp
91 .ne 2
92 .na
93 \fB\fBGL_SERVER_MODE\fR\fR
94 .ad
95 .RS 18n
96 Select non-blocking server I/O mode. In this mode, since non-blocking terminal
97 I/O is used, the entry of each new input line typically requires many calls to
98 \fBgl_get_line()\fR from an external I/O-driven event loop.
99 .RE
100
101 .sp
102 .LP
103 Newly created GetLine objects start in normal I/O mode, so to switch to
104 non-blocking server mode requires an initial call to \fBgl_io_mode()\fR.
105 .SS "Server I/O Mode"
106 .sp
107 .LP
108 In non-blocking server I/O mode, the application is required to have an event
109 loop that calls \fBgl_get_line()\fR whenever the terminal file descriptor can
110 perform the type I/O that \fBgl_get_line()\fR is waiting for. To determine
111 which type of I/O \fBgl_get_line()\fR is waiting for, the application calls the
112 \fBgl_pending_io()\fR function. The return value is one of the following two
113 enumerated values.
114 .sp
115 .ne 2
116 .na
117 \fB\fBGLP_READ\fR\fR
118 .ad
119 .RS 13n
120 \fBgl_get_line()\fR is waiting to write a character to the terminal.
121 .RE
122
123 .sp
124 .ne 2
125 .na
126 \fB\fBGLP_WRITE\fR\fR
127 .ad
128 .RS 13n
129 \fBgl_get_line()\fR is waiting to read a character from the keyboad.
130 .RE
131
132 .sp
133 .LP
134 If the application is using either the \fBselect\fR(3C) or \fBpoll\fR(2)
135 function to watch for I/O on a group of file descriptors, then it should call
136 the \fBgl_pending_io()\fR function before each call to these functions to
137 determine which direction of I/O it should tell them to watch for, and
138 configure their arguments accordingly. In the case of the \fBselect()\fR
139 function, this means using the \fBFD_SET()\fR macro to add the terminal file
140 descriptor either to the set of file descriptors to be watched for readability
141 or the set to be watched for writability.
142 .sp
143 .LP
144 As in normal I/O mode, the return value of \fBgl_get_line()\fR is either a
145 pointer to a completed input line or \fINULL\fR. However, whereas in normal I/O
146 mode a \fINULL\fR return value always means that an error occurred, in
147 non-blocking server mode, \fINULL\fR is also returned when \fBgl_get_line()\fR
148 cannot read or write to the terminal without blocking. Thus in non-blocking
149 server mode, in order to determine when a \fINULL\fR return value signifies
150 that an error occurred or not, it is necessary to call the
151 \fBgl_return_status()\fR function. If this function returns the enumerated
152 value \fBGLR_BLOCKED\fR, \fBgl_get_line()\fR is waiting for I/O and no error
153 has occurred.
154 .sp
155 .LP
156 When \fBgl_get_line()\fR returns \fINULL\fR and \fBgl_return_status()\fR
157 indicates that this is due to blocked terminal I/O, the application should call
158 \fBgl_get_line()\fR again when the type of I/O reported by
159 \fBgl_pending_io()\fR becomes possible. The \fIprompt\fR, \fIstart_line\fR and
160 \fIstart_pos\fR arguments of \fBgl_get_line()\fR will be ignored on these
161 calls. If you need to change the prompt of the line that is currently being
162 edited, you can call the \fBgl_replace_prompt\fR(3TECLA) function between calls
163 to \fBgl_get_line()\fR.
164 .SS "Giving Up The Terminal"
165 .sp
166 .LP
167 A complication that is unique to non-blocking server mode is that it requires
168 that the terminal be left in raw mode between calls to \fBgl_get_line()\fR. If
169 this were not the case, the external event loop would not be able to detect
170 individual key-presses, and the basic line editing implemented by the terminal
171 driver would clash with the editing provided by \fBgl_get_line()\fR. When the
172 terminal needs to be used for purposes other than entering a new input line
173 with \fBgl_get_line()\fR, it needs to be restored to a usable state. In
174 particular, whenever the process is suspended or terminated, the terminal must
175 be returned to a normal state. If this is not done, then depending on the
176 characteristics of the shell that was used to invoke the program, the user
177 could end up with a hung terminal. To this end, the \fBgl_normal_io()\fR
178 function is provided for switching the terminal back to the state that it was
179 in when raw mode was last established.
180 .sp
181 .LP
182 The \fBgl_normal_io()\fR function first flushes any pending output to the
183 terminal, then moves the cursor to the start of the terminal line which follows
184 the end of the incompletely entered input line. At this point it is safe to
185 suspend or terminate the process, and it is safe for the application to read
186 and write to the terminal. To resume entry of the input line, the application
187 should call the \fBgl_raw_io()\fR function.
188 .sp
189 .LP
190 The \fBgl_normal_io()\fR function starts a new line, redisplays the partially
191 completed input line (if any), restores the cursor position within this line to
192 where it was when \fBgl_normal_io()\fR was called, then switches back to raw,
193 non-blocking terminal mode ready to continue entry of the input line when
194 \fBgl_get_line()\fR is next called.
195 .sp
196 .LP
197 Note that in non-blocking server mode, if \fBgl_get_line()\fR is called after a
198 call to \fBgl_normal_io()\fR, without an intervening call to \fBgl_raw_io()\fR,
199 \fBgl_get_line()\fR will call \fBgl_raw_mode()\fR itself, and the terminal will
200 remain in this mode when \fBgl_get_line()\fR returns.
201 .SS "Signal Handling"
202 .sp
203 .LP
204 In the previous section it was pointed out that in non-blocking server mode,
205 the terminal must be restored to a sane state whenever a signal is received
206 that either suspends or terminates the process. In normal I/O mode, this is
207 done for you by \fBgl_get_line()\fR, but in non-blocking server mode, since the
208 terminal is left in raw mode between calls to \fBgl_get_line()\fR, this signal
209 handling has to be done by the application. Since there are many signals that
210 can suspend or terminate a process, as well as other signals that are important
211 to \fBgl_get_line()\fR, such as the \fBSIGWINCH\fR signal, which tells it when
212 the terminal size has changed, the \fBgl_tty_signals()\fR function is provided
213 for installing signal handlers for all pertinent signals.
214 .sp
215 .LP
216 The \fBgl_tty_signals()\fR function uses \fBgl_get_line()\fR's internal list of
217 signals to assign specified signal handlers to groups of signals. The arguments
218 of this function are as follows.
219 .sp
220 .ne 2
221 .na
222 \fB\fIterm_handler\fR\fR
223 .ad
272 The \fBgl_tty_signals()\fR function uses the POSIX \fBsigaction\fR(2) function
273 to install these signal handlers, and it is careful to use the \fIsa_mask\fR
274 member of each \fBsigaction\fR structure to ensure that only one of these
275 signals is ever delivered at a time. This guards against different instances of
276 these signal handlers from simultaneously trying to write to common global
277 data, such as a shared \fBsigsetjmp\fR(3C) buffer or a signal-received flag.
278 The signal handlers installed by this function should call the
279 \fBgl_handle_signal()\fR.
280 .sp
281 .LP
282 The \fIsigno\fR argument tells this function which signal it is being asked to
283 respond to, and the \fIgl\fR argument should be a pointer to the first element
284 of an array of \fIngl\fR \fBGetLine\fR objects. If your application has only
285 one of these objects, pass its pointer as the \fIgl\fR argument and specify
286 \fIngl\fR as 1.
287 .sp
288 .LP
289 Depending on the signal that is being handled, this function does different
290 things.
291 .SS "Process termination signals"
292 .sp
293 .LP
294 If the signal that was caught is one of those that by default terminates any
295 process that receives it, then \fBgl_handle_signal()\fR does the following
296 steps.
297 .RS +4
298 .TP
299 1.
300 First it blocks the delivery of all signals that can be blocked (ie.
301 \fBSIGKILL\fR and \fBSIGSTOP\fR cannot be blocked).
302 .RE
303 .RS +4
304 .TP
305 2.
306 Next it calls \fBgl_normal_io()\fR for each of the ngl GetLine objects. Note
307 that this does nothing to any of the GetLine objects that are not currently in
308 raw mode.
309 .RE
310 .RS +4
311 .TP
312 3.
313 Next it sets the signal handler of the signal to its default,
314 process-termination disposition.
315 .RE
316 .RS +4
317 .TP
318 4.
319 Next it re-sends the process the signal that was caught.
320 .RE
321 .RS +4
322 .TP
323 5.
324 Finally it unblocks delivery of this signal, which results in the process
325 being terminated.
326 .RE
327 .SS "Process suspension signals"
328 .sp
329 .LP
330 If the default disposition of the signal is to suspend the process, the same
331 steps are executed as for process termination signals, except that when the
332 process is later resumed, \fBgl_handle_signal()\fR continues, and does the
333 following steps.
334 .RS +4
335 .TP
336 1.
337 It re-blocks delivery of the signal.
338 .RE
339 .RS +4
340 .TP
341 2.
342 It reinstates the signal handler of the signal to the one that was displaced
343 when its default disposition was substituted.
344 .RE
345 .RS +4
346 .TP
347 3.
348 For any of the GetLine objects that were in raw mode when
349 \fBgl_handle_signal()\fR was called, \fBgl_handle_signal()\fR then calls
350 \fBgl_raw_io()\fR, to resume entry of the input lines on those terminals.
351 .RE
352 .RS +4
353 .TP
354 4.
355 Finally, it restores the signal process mask to how it was when
356 \fBgl_handle_signal()\fR was called.
357 .RE
358 .sp
359 .LP
360 Note that the process is suspended or terminated using the original signal that
361 was caught, rather than using the uncatchable \fBSIGSTOP\fR and \fBSIGKILL\fR
362 signals. This is important, because when a process is suspended or terminated,
363 the parent of the process may wish to use the status value returned by the wait
364 system call to figure out which signal was responsible. In particular, most
365 shells use this information to print a corresponding message to the terminal.
366 Users would be rightly confused if when their process received a \fBSIGPIPE\fR
367 signal, the program responded by sending itself a \fBSIGKILL\fR signal, and the
368 shell then printed out the provocative statement, "Killed!".
369 .SS "Interrupting The Event Loop"
370 .sp
371 .LP
372 If a signal is caught and handled when the application's event loop is waiting
373 in \fBselect()\fR or \fBpoll()\fR, these functions will be aborted with
374 \fBerrno\fR set to \fBEINTR\fR. When this happens the event loop should call
375 \fBgl_pending_io()\fR before calling \fBselect()\fR or \fBpoll()\fR again. It
376 should then arrange for \fBselect()\fR or \fBpoll()\fR to wait for the type of
377 I/O that \fBgl_pending_io()\fR reports. This is necessary because any signal
378 handler that calls \fBgl_handle_signal()\fR will frequently change the type of
379 I/O that \fBgl_get_line()\fR is waiting for.
380 .sp
381 .LP
382 If a signal arrives between the statements that configure the arguments of
383 \fBselect()\fR or \fBpoll()\fR and the calls to these functions, the signal
384 will not be seen by these functions, which will then not be aborted. If these
385 functions are waiting for keyboard input from the user when the signal is
386 received, and the signal handler arranges to redraw the input line to
387 accommodate a terminal resize or the resumption of the process. This redisplay
388 will be delayed until the user presses the next key. Apart from puzzling the
389 user, this clearly is not a serious problem. However there is a way, albeit
390 complicated, to completely avoid this race condition. The following steps
391 illustrate this.
448 When select returns, again block the signals that were unblocked in step 7.
449 .sp
450 If a signal is arrived any time during the above steps, our signal handler will
451 be triggered and cause control to return to the \fBsigsetjmp()\fR statement,
452 where this time, \fBsigsetjmp()\fR will return non-zero, indicating that a
453 signal was caught. When this happens we simply skip the above block of
454 statements, and continue with the following statements, which are executed
455 regardless of whether or not a signal is caught. Note that when
456 \fBsigsetjmp()\fR returns, regardless of why it returned, the process signal
457 mask is returned to how it was when \fBsigsetjmp()\fR was called. Thus the
458 following statements are always executed with all of our signals blocked.
459 .RE
460 .RS +4
461 .TP
462 10.
463 Reinstate the signal handlers that were displaced in step 5.
464 .RE
465 .RS +4
466 .TP
467 11.
468 Check wether a signal was caught, by checking the file-scope variable that
469 the signal handler records signal numbers in.
470 .RE
471 .RS +4
472 .TP
473 12.
474 If a signal was caught, send this signal to the application again and
475 unblock only this signal so that it invokes the signal handler which was just
476 reinstated in step 10.
477 .RE
478 .RS +4
479 .TP
480 13.
481 Unblock all of the signals that were blocked in step 7.
482 .RE
483 .SS "Signals Caught By \fBgl_get_line()\fR"
484 .sp
485 .LP
486 Since the application is expected to handle signals in non-blocking server
487 mode, \fBgl_get_line()\fR does not attempt to duplicate this when it is being
488 called. If one of the signals that it is configured to catch is sent to the
489 application while \fBgl_get_line()\fR is being called, \fBgl_get_line()\fR
490 reinstates the caller's signal handlers, then immediately before returning,
491 re-sends the signal to the process to let the application's signal handler
492 handle it. If the process is not terminated by this signal, \fBgl_get_line()\fR
493 returns \fINULL\fR, and a following call to \fBgl_return_status()\fR returns
494 the enumerated value \fBGLR_SIGNAL\fR.
495 .SS "Aborting Line Input"
496 .sp
497 .LP
498 Often, rather than letting it terminate the process, applications respond to
499 the \fBSIGINT\fR user-interrupt signal by aborting the current input line. This
500 can be accomplished in non-blocking server-I/O mode by not calling
501 \fBgl_handle_signal()\fR when this signal is caught, but by calling instead the
502 \fBgl_abandon_line()\fR function. This function arranges that when
503 \fBgl_get_line()\fR is next called, it first flushes any pending output to the
504 terminal, discardes the current input line, outputs a new prompt on the next
505 line, and finally starts accepting input of a new input line from the user.
506 .SS "Signal Safe Functions"
507 .sp
508 .LP
509 Provided that certain rules are followed, the \fBgl_normal_io()\fR,
510 \fBgl_raw_io()\fR, \fBgl_handle_signal()\fR, and \fBgl_abandon_line()\fR
511 functions can be written to be safely callable from signal handlers. Other
512 functions in this library should not be called from signal handlers. For this
513 to be true, all signal handlers that call these functions must be registered in
514 such a way that only one instance of any one of them can be running at one
515 time. The way to do this is to use the POSIX \fBsigaction()\fR function to
516 register all signal handlers, and when doing this, use the \fIsa_mask\fR member
517 of the corresponding \fBsigaction\fR structure to indicate that all of the
518 signals whose handlers invoke the above functions should be blocked when the
519 current signal is being handled. This prevents two signal handlers from
520 operating on a \fBGetLine\fR object at the same time.
521 .sp
522 .LP
523 To prevent signal handlers from accessing a \fBGetLine\fR object while
524 \fBgl_get_line()\fR or any of its associated public functions are operating on
525 it, all public functions associated with \fBgl_get_line()\fR, including
526 \fBgl_get_line()\fR itself, temporarily block the delivery of signals when they
527 are accessing \fBGetLine\fR objects. Beware that the only signals that they
528 block are the signals that \fBgl_get_line()\fR is currently configured to
529 catch, so be sure that if you call any of the above functions from signal
530 handlers, that the signals that these handlers are assigned to are configured
531 to be caught by \fBgl_get_line()\fR. See \fBgl_trap_signal\fR(3TECLA).
532 .SS "Using Timeouts To Poll"
533 .sp
534 .LP
535 If instead of using \fBselect()\fR or \fBpoll()\fR to wait for I/O your
536 application needs only to get out of \fBgl_get_line()\fR periodically to
537 briefly do something else before returning to accept input from the user, use
538 the \fBgl_inactivity_timeout\fR(3TECLA) function in non-blocking server mode to
539 specify that a callback function that returns \fBGLTO_CONTINUE\fR should be
540 called whenever \fBgl_get_line()\fR has been waiting for I/O for more than a
541 specified amount of time. When this callback is triggered, \fBgl_get_line()\fR
542 will return \fINULL\fR and a following call to \fBgl_return_status()\fR will
543 return \fBGLR_BLOCKED\fR.
544 .sp
545 .LP
546 The \fBgl_get_line()\fR function will not return until the user has not typed a
547 key for the specified interval, so if the interval is long and the user keeps
548 typing, \fBgl_get_line()\fR might not return for a while. There is no guarantee
549 that it will return in the time specified.
550 .SH ATTRIBUTES
551 .sp
552 .LP
553 See \fBattributes\fR(5) for descriptions of the following attributes:
554 .sp
555
556 .sp
557 .TS
558 box;
559 c | c
560 l | l .
561 ATTRIBUTE TYPE ATTRIBUTE VALUE
562 _
563 Interface Stability Evolving
564 _
565 MT-Level MT-Safe
566 .TE
567
568 .SH SEE ALSO
569 .sp
570 .LP
571 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
572 \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBpca_lookup_file\fR(3TECLA),
573 \fBattributes\fR(5), \fBtecla\fR(5)
|
8 .\" to whom the Software is furnished to do so, provided that the above
9 .\" copyright notice(s) and this permission notice appear in all copies of
10 .\" the Software and that both the above copyright notice(s) and this
11 .\" permission notice appear in supporting documentation.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
15 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
16 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
17 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
18 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
19 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
20 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
21 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22 .\"
23 .\" Except as contained in this notice, the name of a copyright holder
24 .\" shall not be used in advertising or otherwise to promote the sale, use
25 .\" or other dealings in this Software without prior written authorization
26 .\" of the copyright holder.
27 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
28 .TH GL_IO_MODE 3TECLA "January 18, 2020"
29 .SH NAME
30 gl_io_mode, gl_raw_io, gl_normal_io, gl_tty_signals, gl_abandon_line,
31 gl_handle_signal, gl_pending_io \- use \fBgl_get_line()\fR from an external
32 event loop
33 .SH SYNOPSIS
34 .nf
35 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
36 #include <libtecla.h>
37
38 \fBint\fR \fBgl_io_mode\fR(\fBGetLine *\fR\fIgl\fR, \fBGlIOMode\fR \fImode\fR);
39 .fi
40
41 .LP
42 .nf
43 \fBint\fR \fBgl_raw_io\fR(\fBGetLine *\fR\fIgl\fR);
44 .fi
45
46 .LP
47 .nf
48 \fBint\fR \fBgl_normal_io\fR(\fBGetLine *\fR\fIgl\fR);
49 .fi
50
51 .LP
52 .nf
53 \fBint\fR \fBgl_tty_signals\fR(\fBvoid (*\fR\fIterm_handler\fR)(int), \fBvoid (*\fR\fIsusp_handler\fR)(int),
54 \fBvoid (*\fR\fIcont_handler\fR)(int), \fBvoid (*\fR\fIsize_handler\fR)(int));
55 .fi
56
57 .LP
58 .nf
59 \fBvoid\fR \fBgl_abandon_line\fR(\fBGetLine *\fR\fIgl\fR);
60 .fi
61
62 .LP
63 .nf
64 \fBvoid\fR \fBgl_handle_signal\fR(\fBint\fR \fIsigno\fR, \fBGetLine *\fR\fIgl\fR, \fBint\fR \fIngl\fR);
65 .fi
66
67 .LP
68 .nf
69 \fBGlPendingIO\fR \fBgl_pending_io\fR(\fBGetLine *\fR\fIgl\fR);
70 .fi
71
72 .SH DESCRIPTION
73 The \fBgl_get_line\fR(3TECLA) function supports two different I/O modes. These
74 are selected by calling the \fBgl_io_mode()\fR function. The \fImode\fR
75 argument of \fBgl_io_mode()\fR specifies the new I/O mode and must be one of
76 the following.
77 .sp
78 .ne 2
79 .na
80 \fB\fBGL_NORMAL_MODE\fR\fR
81 .ad
82 .RS 18n
83 Select the normal blocking-I/O mode. In this mode \fBgl_get_line()\fR does not
84 return until either an error occurs of the user finishes entering a new line.
85 .RE
86
87 .sp
88 .ne 2
89 .na
90 \fB\fBGL_SERVER_MODE\fR\fR
91 .ad
92 .RS 18n
93 Select non-blocking server I/O mode. In this mode, since non-blocking terminal
94 I/O is used, the entry of each new input line typically requires many calls to
95 \fBgl_get_line()\fR from an external I/O-driven event loop.
96 .RE
97
98 .sp
99 .LP
100 Newly created GetLine objects start in normal I/O mode, so to switch to
101 non-blocking server mode requires an initial call to \fBgl_io_mode()\fR.
102 .SS "Server I/O Mode"
103 In non-blocking server I/O mode, the application is required to have an event
104 loop that calls \fBgl_get_line()\fR whenever the terminal file descriptor can
105 perform the type of I/O that \fBgl_get_line()\fR is waiting for. To determine
106 which type of I/O \fBgl_get_line()\fR is waiting for, the application calls the
107 \fBgl_pending_io()\fR function. The return value is one of the following two
108 enumerated values.
109 .sp
110 .ne 2
111 .na
112 \fB\fBGLP_READ\fR\fR
113 .ad
114 .RS 13n
115 \fBgl_get_line()\fR is waiting to write a character to the terminal.
116 .RE
117
118 .sp
119 .ne 2
120 .na
121 \fB\fBGLP_WRITE\fR\fR
122 .ad
123 .RS 13n
124 \fBgl_get_line()\fR is waiting to read a character from the keyboard.
125 .RE
126
127 .sp
128 .LP
129 If the application is using either the \fBselect\fR(3C) or \fBpoll\fR(2)
130 function to watch for I/O on a group of file descriptors, then it should call
131 the \fBgl_pending_io()\fR function before each call to these functions to
132 determine which direction of I/O it should tell them to watch for, and
133 configure their arguments accordingly. In the case of the \fBselect()\fR
134 function, this means using the \fBFD_SET()\fR macro to add the terminal file
135 descriptor either to the set of file descriptors to be watched for readability
136 or the set to be watched for writability.
137 .sp
138 .LP
139 As in normal I/O mode, the return value of \fBgl_get_line()\fR is either a
140 pointer to a completed input line or \fINULL\fR. However, whereas in normal I/O
141 mode a \fINULL\fR return value always means that an error occurred, in
142 non-blocking server mode, \fINULL\fR is also returned when \fBgl_get_line()\fR
143 cannot read or write to the terminal without blocking. Thus in non-blocking
144 server mode, in order to determine when a \fINULL\fR return value signifies
145 that an error occurred or not, it is necessary to call the
146 \fBgl_return_status()\fR function. If this function returns the enumerated
147 value \fBGLR_BLOCKED\fR, \fBgl_get_line()\fR is waiting for I/O and no error
148 has occurred.
149 .sp
150 .LP
151 When \fBgl_get_line()\fR returns \fINULL\fR and \fBgl_return_status()\fR
152 indicates that this is due to blocked terminal I/O, the application should call
153 \fBgl_get_line()\fR again when the type of I/O reported by
154 \fBgl_pending_io()\fR becomes possible. The \fIprompt\fR, \fIstart_line\fR and
155 \fIstart_pos\fR arguments of \fBgl_get_line()\fR will be ignored on these
156 calls. If you need to change the prompt of the line that is currently being
157 edited, you can call the \fBgl_replace_prompt\fR(3TECLA) function between calls
158 to \fBgl_get_line()\fR.
159 .SS "Giving Up The Terminal"
160 A complication that is unique to non-blocking server mode is that it requires
161 that the terminal be left in raw mode between calls to \fBgl_get_line()\fR. If
162 this were not the case, the external event loop would not be able to detect
163 individual key-presses, and the basic line editing implemented by the terminal
164 driver would clash with the editing provided by \fBgl_get_line()\fR. When the
165 terminal needs to be used for purposes other than entering a new input line
166 with \fBgl_get_line()\fR, it needs to be restored to a usable state. In
167 particular, whenever the process is suspended or terminated, the terminal must
168 be returned to a normal state. If this is not done, then depending on the
169 characteristics of the shell that was used to invoke the program, the user
170 could end up with a hung terminal. To this end, the \fBgl_normal_io()\fR
171 function is provided for switching the terminal back to the state that it was
172 in when raw mode was last established.
173 .sp
174 .LP
175 The \fBgl_normal_io()\fR function first flushes any pending output to the
176 terminal, then moves the cursor to the start of the terminal line which follows
177 the end of the incompletely entered input line. At this point it is safe to
178 suspend or terminate the process, and it is safe for the application to read
179 and write to the terminal. To resume entry of the input line, the application
180 should call the \fBgl_raw_io()\fR function.
181 .sp
182 .LP
183 The \fBgl_normal_io()\fR function starts a new line, redisplays the partially
184 completed input line (if any), restores the cursor position within this line to
185 where it was when \fBgl_normal_io()\fR was called, then switches back to raw,
186 non-blocking terminal mode ready to continue entry of the input line when
187 \fBgl_get_line()\fR is next called.
188 .sp
189 .LP
190 Note that in non-blocking server mode, if \fBgl_get_line()\fR is called after a
191 call to \fBgl_normal_io()\fR, without an intervening call to \fBgl_raw_io()\fR,
192 \fBgl_get_line()\fR will call \fBgl_raw_mode()\fR itself, and the terminal will
193 remain in this mode when \fBgl_get_line()\fR returns.
194 .SS "Signal Handling"
195 In the previous section it was pointed out that in non-blocking server mode,
196 the terminal must be restored to a sane state whenever a signal is received
197 that either suspends or terminates the process. In normal I/O mode, this is
198 done for you by \fBgl_get_line()\fR, but in non-blocking server mode, since the
199 terminal is left in raw mode between calls to \fBgl_get_line()\fR, this signal
200 handling has to be done by the application. Since there are many signals that
201 can suspend or terminate a process, as well as other signals that are important
202 to \fBgl_get_line()\fR, such as the \fBSIGWINCH\fR signal, which tells it when
203 the terminal size has changed, the \fBgl_tty_signals()\fR function is provided
204 for installing signal handlers for all pertinent signals.
205 .sp
206 .LP
207 The \fBgl_tty_signals()\fR function uses \fBgl_get_line()\fR's internal list of
208 signals to assign specified signal handlers to groups of signals. The arguments
209 of this function are as follows.
210 .sp
211 .ne 2
212 .na
213 \fB\fIterm_handler\fR\fR
214 .ad
263 The \fBgl_tty_signals()\fR function uses the POSIX \fBsigaction\fR(2) function
264 to install these signal handlers, and it is careful to use the \fIsa_mask\fR
265 member of each \fBsigaction\fR structure to ensure that only one of these
266 signals is ever delivered at a time. This guards against different instances of
267 these signal handlers from simultaneously trying to write to common global
268 data, such as a shared \fBsigsetjmp\fR(3C) buffer or a signal-received flag.
269 The signal handlers installed by this function should call the
270 \fBgl_handle_signal()\fR.
271 .sp
272 .LP
273 The \fIsigno\fR argument tells this function which signal it is being asked to
274 respond to, and the \fIgl\fR argument should be a pointer to the first element
275 of an array of \fIngl\fR \fBGetLine\fR objects. If your application has only
276 one of these objects, pass its pointer as the \fIgl\fR argument and specify
277 \fIngl\fR as 1.
278 .sp
279 .LP
280 Depending on the signal that is being handled, this function does different
281 things.
282 .SS "Process termination signals"
283 If the signal that was caught is one of those that by default terminates any
284 process that receives it, then \fBgl_handle_signal()\fR does the following
285 steps.
286 .RS +4
287 .TP
288 1.
289 First it blocks the delivery of all signals that can be blocked (ie.
290 \fBSIGKILL\fR and \fBSIGSTOP\fR cannot be blocked).
291 .RE
292 .RS +4
293 .TP
294 2.
295 Next it calls \fBgl_normal_io()\fR for each of the ngl GetLine objects. Note
296 that this does nothing to any of the GetLine objects that are not currently in
297 raw mode.
298 .RE
299 .RS +4
300 .TP
301 3.
302 Next it sets the signal handler of the signal to its default,
303 process-termination disposition.
304 .RE
305 .RS +4
306 .TP
307 4.
308 Next it re-sends the process the signal that was caught.
309 .RE
310 .RS +4
311 .TP
312 5.
313 Finally it unblocks delivery of this signal, which results in the process
314 being terminated.
315 .RE
316 .SS "Process suspension signals"
317 If the default disposition of the signal is to suspend the process, the same
318 steps are executed as for process termination signals, except that when the
319 process is later resumed, \fBgl_handle_signal()\fR continues, and does the
320 following steps.
321 .RS +4
322 .TP
323 1.
324 It re-blocks delivery of the signal.
325 .RE
326 .RS +4
327 .TP
328 2.
329 It reinstates the signal handler of the signal to the one that was displaced
330 when its default disposition was substituted.
331 .RE
332 .RS +4
333 .TP
334 3.
335 For any of the GetLine objects that were in raw mode when
336 \fBgl_handle_signal()\fR was called, \fBgl_handle_signal()\fR then calls
337 \fBgl_raw_io()\fR, to resume entry of the input lines on those terminals.
338 .RE
339 .RS +4
340 .TP
341 4.
342 Finally, it restores the signal process mask to how it was when
343 \fBgl_handle_signal()\fR was called.
344 .RE
345 .sp
346 .LP
347 Note that the process is suspended or terminated using the original signal that
348 was caught, rather than using the uncatchable \fBSIGSTOP\fR and \fBSIGKILL\fR
349 signals. This is important, because when a process is suspended or terminated,
350 the parent of the process may wish to use the status value returned by the wait
351 system call to figure out which signal was responsible. In particular, most
352 shells use this information to print a corresponding message to the terminal.
353 Users would be rightly confused if when their process received a \fBSIGPIPE\fR
354 signal, the program responded by sending itself a \fBSIGKILL\fR signal, and the
355 shell then printed out the provocative statement, "Killed!".
356 .SS "Interrupting The Event Loop"
357 If a signal is caught and handled when the application's event loop is waiting
358 in \fBselect()\fR or \fBpoll()\fR, these functions will be aborted with
359 \fBerrno\fR set to \fBEINTR\fR. When this happens the event loop should call
360 \fBgl_pending_io()\fR before calling \fBselect()\fR or \fBpoll()\fR again. It
361 should then arrange for \fBselect()\fR or \fBpoll()\fR to wait for the type of
362 I/O that \fBgl_pending_io()\fR reports. This is necessary because any signal
363 handler that calls \fBgl_handle_signal()\fR will frequently change the type of
364 I/O that \fBgl_get_line()\fR is waiting for.
365 .sp
366 .LP
367 If a signal arrives between the statements that configure the arguments of
368 \fBselect()\fR or \fBpoll()\fR and the calls to these functions, the signal
369 will not be seen by these functions, which will then not be aborted. If these
370 functions are waiting for keyboard input from the user when the signal is
371 received, and the signal handler arranges to redraw the input line to
372 accommodate a terminal resize or the resumption of the process. This redisplay
373 will be delayed until the user presses the next key. Apart from puzzling the
374 user, this clearly is not a serious problem. However there is a way, albeit
375 complicated, to completely avoid this race condition. The following steps
376 illustrate this.
433 When select returns, again block the signals that were unblocked in step 7.
434 .sp
435 If a signal is arrived any time during the above steps, our signal handler will
436 be triggered and cause control to return to the \fBsigsetjmp()\fR statement,
437 where this time, \fBsigsetjmp()\fR will return non-zero, indicating that a
438 signal was caught. When this happens we simply skip the above block of
439 statements, and continue with the following statements, which are executed
440 regardless of whether or not a signal is caught. Note that when
441 \fBsigsetjmp()\fR returns, regardless of why it returned, the process signal
442 mask is returned to how it was when \fBsigsetjmp()\fR was called. Thus the
443 following statements are always executed with all of our signals blocked.
444 .RE
445 .RS +4
446 .TP
447 10.
448 Reinstate the signal handlers that were displaced in step 5.
449 .RE
450 .RS +4
451 .TP
452 11.
453 Check whether a signal was caught, by checking the file-scope variable that
454 the signal handler records signal numbers in.
455 .RE
456 .RS +4
457 .TP
458 12.
459 If a signal was caught, send this signal to the application again and
460 unblock only this signal so that it invokes the signal handler which was just
461 reinstated in step 10.
462 .RE
463 .RS +4
464 .TP
465 13.
466 Unblock all of the signals that were blocked in step 7.
467 .RE
468 .SS "Signals Caught By \fBgl_get_line()\fR"
469 Since the application is expected to handle signals in non-blocking server
470 mode, \fBgl_get_line()\fR does not attempt to duplicate this when it is being
471 called. If one of the signals that it is configured to catch is sent to the
472 application while \fBgl_get_line()\fR is being called, \fBgl_get_line()\fR
473 reinstates the caller's signal handlers, then immediately before returning,
474 re-sends the signal to the process to let the application's signal handler
475 handle it. If the process is not terminated by this signal, \fBgl_get_line()\fR
476 returns \fINULL\fR, and a following call to \fBgl_return_status()\fR returns
477 the enumerated value \fBGLR_SIGNAL\fR.
478 .SS "Aborting Line Input"
479 Often, rather than letting it terminate the process, applications respond to
480 the \fBSIGINT\fR user-interrupt signal by aborting the current input line. This
481 can be accomplished in non-blocking server-I/O mode by not calling
482 \fBgl_handle_signal()\fR when this signal is caught, but by calling instead the
483 \fBgl_abandon_line()\fR function. This function arranges that when
484 \fBgl_get_line()\fR is next called, it first flushes any pending output to the
485 terminal, discards the current input line, outputs a new prompt on the next
486 line, and finally starts accepting input of a new input line from the user.
487 .SS "Signal Safe Functions"
488 Provided that certain rules are followed, the \fBgl_normal_io()\fR,
489 \fBgl_raw_io()\fR, \fBgl_handle_signal()\fR, and \fBgl_abandon_line()\fR
490 functions can be written to be safely callable from signal handlers. Other
491 functions in this library should not be called from signal handlers. For this
492 to be true, all signal handlers that call these functions must be registered in
493 such a way that only one instance of any one of them can be running at one
494 time. The way to do this is to use the POSIX \fBsigaction()\fR function to
495 register all signal handlers, and when doing this, use the \fIsa_mask\fR member
496 of the corresponding \fBsigaction\fR structure to indicate that all of the
497 signals whose handlers invoke the above functions should be blocked when the
498 current signal is being handled. This prevents two signal handlers from
499 operating on a \fBGetLine\fR object at the same time.
500 .sp
501 .LP
502 To prevent signal handlers from accessing a \fBGetLine\fR object while
503 \fBgl_get_line()\fR or any of its associated public functions are operating on
504 it, all public functions associated with \fBgl_get_line()\fR, including
505 \fBgl_get_line()\fR itself, temporarily block the delivery of signals when they
506 are accessing \fBGetLine\fR objects. Beware that the only signals that they
507 block are the signals that \fBgl_get_line()\fR is currently configured to
508 catch, so be sure that if you call any of the above functions from signal
509 handlers, that the signals that these handlers are assigned to are configured
510 to be caught by \fBgl_get_line()\fR. See \fBgl_trap_signal\fR(3TECLA).
511 .SS "Using Timeouts To Poll"
512 If instead of using \fBselect()\fR or \fBpoll()\fR to wait for I/O your
513 application needs only to get out of \fBgl_get_line()\fR periodically to
514 briefly do something else before returning to accept input from the user, use
515 the \fBgl_inactivity_timeout\fR(3TECLA) function in non-blocking server mode to
516 specify that a callback function that returns \fBGLTO_CONTINUE\fR should be
517 called whenever \fBgl_get_line()\fR has been waiting for I/O for more than a
518 specified amount of time. When this callback is triggered, \fBgl_get_line()\fR
519 will return \fINULL\fR and a following call to \fBgl_return_status()\fR will
520 return \fBGLR_BLOCKED\fR.
521 .sp
522 .LP
523 The \fBgl_get_line()\fR function will not return until the user has not typed a
524 key for the specified interval, so if the interval is long and the user keeps
525 typing, \fBgl_get_line()\fR might not return for a while. There is no guarantee
526 that it will return in the time specified.
527 .SH ATTRIBUTES
528 See \fBattributes\fR(5) for descriptions of the following attributes:
529 .sp
530
531 .sp
532 .TS
533 box;
534 c | c
535 l | l .
536 ATTRIBUTE TYPE ATTRIBUTE VALUE
537 _
538 Interface Stability Evolving
539 _
540 MT-Level MT-Safe
541 .TE
542
543 .SH SEE ALSO
544 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
545 \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBpca_lookup_file\fR(3TECLA),
546 \fBattributes\fR(5), \fBtecla\fR(5)
|