1 '\" te
   2 .\" Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
   3 .\" All Rights Reserved.
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the
   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
   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
 224 .RS 16n
 225 This is the signal handler that is used to trap signals that by default
 226 terminate any process that receives them (for example, \fBSIGINT\fR or
 227 \fBSIGTERM\fR).
 228 .RE
 229 
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fIsusp_handler\fR\fR
 234 .ad
 235 .RS 16n
 236 This is the signal handler that is used to trap signals that by default suspend
 237 any process that receives them, (for example, \fBSIGTSTP\fR or \fBSIGTTOU\fR).
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fIcont_handler\fR\fR
 244 .ad
 245 .RS 16n
 246 This is the signal handler that is used to trap signals that are usually sent
 247 when a process resumes after being suspended (usually \fBSIGCONT\fR). Beware
 248 that there is nothing to stop a user from sending one of these signals at other
 249 times.
 250 .RE
 251 
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fIsize_handler\fR\fR
 256 .ad
 257 .RS 16n
 258 This signal handler is used to trap signals that are sent to processes when
 259 their controlling terminals are resized by the user (for example,
 260 \fBSIGWINCH\fR).
 261 .RE
 262 
 263 .sp
 264 .LP
 265 These arguments can all be the same, if so desired, and \fBSIG_IGN\fR (ignore
 266 this signal) or \fBSIG_DFL\fR (use the system-provided default signal handler)
 267 can be specified instead of a function where pertinent. In particular, it is
 268 rarely useful to trap \fBSIGCONT\fR, so the \fIcont_handler\fR argument will
 269 usually be \fBSIG_DFL\fR or \fBSIG_IGN\fR.
 270 .sp
 271 .LP
 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.
 392 .RS +4
 393 .TP
 394 1.
 395 Block all of the signals that \fBgl_get_line()\fR catches, by passing the
 396 signal set returned by \fBgl_list_signals()\fR to \fBsigprocmask\fR(2).
 397 .RE
 398 .RS +4
 399 .TP
 400 2.
 401 Call \fBgl_pending_io()\fR and set up the arguments of \fBselect()\fR or
 402 \fBpoll()\fR accordingly.
 403 .RE
 404 .RS +4
 405 .TP
 406 3.
 407 Call \fBsigsetjmp\fR(3C) with a non-zero \fIsavemask\fR argument.
 408 .RE
 409 .RS +4
 410 .TP
 411 4.
 412 Initially this \fBsigsetjmp()\fR statement will return zero, indicating that
 413 control is not resuming there after a matching call to \fBsiglongjmp\fR(3C).
 414 .RE
 415 .RS +4
 416 .TP
 417 5.
 418 Replace all of the handlers of the signals that \fBgl_get_line()\fR is
 419 configured to catch, with a signal handler that first records the number of the
 420 signal that was caught, in a file-scope variable, then calls \fBsiglongjmp()\fR
 421 with a non-zero \fIval\fR argument, to return execution to the above
 422 \fBsigsetjmp()\fR statement. Registering these signal handlers can conveniently
 423 be done using the \fBgl_tty_signals()\fR function.
 424 .RE
 425 .RS +4
 426 .TP
 427 6.
 428 Set the file-scope variable that the above signal handler uses to record any
 429 signal that is caught to -1, so that we can check whether a signal was caught
 430 by seeing if it contains a valid signal number.
 431 .RE
 432 .RS +4
 433 .TP
 434 7.
 435 Now unblock the signals that were blocked in step 1. Any signal that was
 436 received by the process in between step 1 and now will now be delivered, and
 437 trigger our signal handler, as will any signal that is received until we block
 438 these signals again.
 439 .RE
 440 .RS +4
 441 .TP
 442 8.
 443 Now call \fBselect()\fR or \fBpoll()\fR.
 444 .RE
 445 .RS +4
 446 .TP
 447 9.
 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)