Lines Matching full:to

4 .\" Permission is hereby granted, free of charge, to any person obtaining a copy of this software a…
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, and/or sell copies of the Software, and to permit persons
8 .\" to whom the Software is furnished to do so, provided that the above
14 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 .\" shall not be used in advertising or otherwise to promote the sale, use
94 I/O is used, the entry of each new input line typically requires many calls to
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.
103 In non-blocking server I/O mode, the application is required to have an event
105 perform the type of I/O that \fBgl_get_line()\fR is waiting for. To determine
115 \fBgl_get_line()\fR is waiting to write a character to the terminal.
124 \fBgl_get_line()\fR is waiting to read a character from the keyboard.
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
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.
140 pointer to a completed input line or \fINULL\fR. However, whereas in normal I/O
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
152 indicates that this is due to blocked terminal I/O, the application should call
156 calls. If you need to change the prompt of the line that is currently being
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
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
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
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
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
191 call to \fBgl_normal_io()\fR, without an intervening call to \fBgl_raw_io()\fR,
196 the terminal must be restored to a sane state whenever a signal is received
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
208 signals to assign specified signal handlers to groups of signals. The arguments
216 This is the signal handler that is used to trap signals that by default
227 This is the signal handler that is used to trap signals that by default suspend
237 This is the signal handler that is used to trap signals that are usually sent
239 that there is nothing to stop a user from sending one of these signals at other
249 This signal handler is used to trap signals that are sent to processes when
259 rarely useful to trap \fBSIGCONT\fR, so the \fIcont_handler\fR argument will
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
267 these signal handlers from simultaneously trying to write to common global
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
296 that this does nothing to any of the GetLine objects that are not currently in
302 Next it sets the signal handler of the signal to its default,
317 If the default disposition of the signal is to suspend the process, the same
329 It reinstates the signal handler of the signal to the one that was displaced
337 \fBgl_raw_io()\fR, to resume entry of the input lines on those terminals.
342 Finally, it restores the signal process mask to how it was when
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.
359 \fBerrno\fR set to \fBEINTR\fR. When this happens the event loop should call
361 should then arrange for \fBselect()\fR or \fBpoll()\fR to wait for the type of
368 \fBselect()\fR or \fBpoll()\fR and the calls to these functions, the signal
371 received, and the signal handler arranges to redraw the input line to
375 complicated, to completely avoid this race condition. The following steps
381 signal set returned by \fBgl_list_signals()\fR to \fBsigprocmask\fR(2).
398 control is not resuming there after a matching call to \fBsiglongjmp\fR(3C).
404 configured to catch, with a signal handler that first records the number of the
406 with a non-zero \fIval\fR argument, to return execution to the above
413 Set the file-scope variable that the above signal handler uses to record any
414 signal that is caught to -1, so that we can check whether a signal was caught
436 be triggered and cause control to return to the \fBsigsetjmp()\fR statement,
442 mask is returned to how it was when \fBsigsetjmp()\fR was called. Thus the
459 If a signal was caught, send this signal to the application again and
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
474 re-sends the signal to the process to let the application's signal handler
476 returns \fINULL\fR, and a following call to \fBgl_return_status()\fR returns
479 Often, rather than letting it terminate the process, applications respond to
484 \fBgl_get_line()\fR is next called, it first flushes any pending output to the
490 functions can be written to be safely callable from signal handlers. Other
494 time. The way to do this is to use the POSIX \fBsigaction()\fR function to
496 of the corresponding \fBsigaction\fR structure to indicate that all of the
507 block are the signals that \fBgl_get_line()\fR is currently configured to
509 handlers, that the signals that these handlers are assigned to are configured
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
519 will return \fINULL\fR and a following call to \fBgl_return_status()\fR will