Print this page 
12212 typos in some section 3tecla man pages
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3tecla/gl_io_mode.3tecla
          +++ new/usr/src/man/man3tecla/gl_io_mode.3tecla
↓ open down ↓ 17 lines elided ↑ open up ↑ 
  18   18  .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  19   19  .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  20   20  .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  21   21  .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22   22  .\"
  23   23  .\" Except as contained in this notice, the name of a copyright holder
  24   24  .\" shall not be used in advertising or otherwise to promote the sale, use
  25   25  .\" or other dealings in this Software without prior written authorization
  26   26  .\" of the copyright holder.
  27   27  .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  28      -.TH GL_IO_MODE 3TECLA "Jun 1, 2004"
       28 +.TH GL_IO_MODE 3TECLA "January 18, 2020"
  29   29  .SH NAME
  30   30  gl_io_mode, gl_raw_io, gl_normal_io, gl_tty_signals, gl_abandon_line,
  31   31  gl_handle_signal, gl_pending_io \- use \fBgl_get_line()\fR from an external
  32   32  event loop
  33   33  .SH SYNOPSIS
  34      -.LP
  35   34  .nf
  36   35  cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
  37   36  #include <libtecla.h>
  38   37  
  39   38  \fBint\fR \fBgl_io_mode\fR(\fBGetLine *\fR\fIgl\fR, \fBGlIOMode\fR \fImode\fR);
  40   39  .fi
  41   40  
  42   41  .LP
  43   42  .nf
  44   43  \fBint\fR \fBgl_raw_io\fR(\fBGetLine *\fR\fIgl\fR);
↓ open down ↓ 19 lines elided ↑ open up ↑ 
  64   63  .nf
  65   64  \fBvoid\fR \fBgl_handle_signal\fR(\fBint\fR \fIsigno\fR, \fBGetLine *\fR\fIgl\fR, \fBint\fR \fIngl\fR);
  66   65  .fi
  67   66  
  68   67  .LP
  69   68  .nf
  70   69  \fBGlPendingIO\fR \fBgl_pending_io\fR(\fBGetLine *\fR\fIgl\fR);
  71   70  .fi
  72   71  
  73   72  .SH DESCRIPTION
  74      -.sp
  75      -.LP
  76   73  The \fBgl_get_line\fR(3TECLA) function supports two different I/O modes. These
  77   74  are selected by calling the \fBgl_io_mode()\fR function. The \fImode\fR
  78   75  argument of \fBgl_io_mode()\fR specifies the new I/O mode and must be one of
  79   76  the following.
  80   77  .sp
  81   78  .ne 2
  82   79  .na
  83   80  \fB\fBGL_NORMAL_MODE\fR\fR
  84   81  .ad
  85   82  .RS 18n
↓ open down ↓ 10 lines elided ↑ open up ↑ 
  96   93  Select non-blocking server I/O mode. In this mode, since non-blocking terminal
  97   94  I/O is used, the entry of each new input line typically requires many calls to
  98   95  \fBgl_get_line()\fR from an external I/O-driven event loop.
  99   96  .RE
 100   97  
 101   98  .sp
 102   99  .LP
 103  100  Newly created GetLine objects start in normal I/O mode, so to switch to
 104  101  non-blocking server mode requires an initial call to \fBgl_io_mode()\fR.
 105  102  .SS "Server I/O Mode"
 106      -.sp
 107      -.LP
 108  103  In non-blocking server I/O mode, the application is required to have an event
 109  104  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
      105 +perform the type of I/O that \fBgl_get_line()\fR is waiting for. To determine
 111  106  which type of I/O \fBgl_get_line()\fR is waiting for, the application calls the
 112  107  \fBgl_pending_io()\fR function.  The return value is one of the following two
 113  108  enumerated values.
 114  109  .sp
 115  110  .ne 2
 116  111  .na
 117  112  \fB\fBGLP_READ\fR\fR
 118  113  .ad
 119  114  .RS 13n
 120  115  \fBgl_get_line()\fR is waiting to write a character to the terminal.
 121  116  .RE
 122  117  
 123  118  .sp
 124  119  .ne 2
 125  120  .na
 126  121  \fB\fBGLP_WRITE\fR\fR
 127  122  .ad
 128  123  .RS 13n
 129      -\fBgl_get_line()\fR is waiting to read a character from the keyboad.
      124 +\fBgl_get_line()\fR is waiting to read a character from the keyboard.
 130  125  .RE
 131  126  
 132  127  .sp
 133  128  .LP
 134  129  If the application is using either the \fBselect\fR(3C) or \fBpoll\fR(2)
 135  130  function to watch for I/O on a group of file descriptors, then it should call
 136  131  the \fBgl_pending_io()\fR function before each call to these functions to
 137  132  determine which direction of I/O it should tell them to watch for, and
 138  133  configure their arguments accordingly. In the case of the \fBselect()\fR
 139  134  function, this means using the \fBFD_SET()\fR macro to add the terminal file
↓ open down ↓ 15 lines elided ↑ open up ↑ 
 155  150  .LP
 156  151  When \fBgl_get_line()\fR returns \fINULL\fR and \fBgl_return_status()\fR
 157  152  indicates that this is due to blocked terminal I/O, the application should call
 158  153  \fBgl_get_line()\fR again when the type of I/O reported by
 159  154  \fBgl_pending_io()\fR becomes possible. The \fIprompt\fR, \fIstart_line\fR and
 160  155  \fIstart_pos\fR arguments of \fBgl_get_line()\fR will be ignored on these
 161  156  calls. If you need to change the prompt of the line that is currently being
 162  157  edited, you can call the \fBgl_replace_prompt\fR(3TECLA) function between calls
 163  158  to \fBgl_get_line()\fR.
 164  159  .SS "Giving Up The Terminal"
 165      -.sp
 166      -.LP
 167  160  A complication that is unique to non-blocking server mode is that it requires
 168  161  that the terminal be left in raw mode between calls to \fBgl_get_line()\fR. If
 169  162  this were not the case, the external event loop would not be able to detect
 170  163  individual key-presses, and the basic line editing implemented by the terminal
 171  164  driver would clash with the editing provided by \fBgl_get_line()\fR. When the
 172  165  terminal needs to be used for purposes other than entering a new input line
 173  166  with \fBgl_get_line()\fR, it needs to be restored to a usable state. In
 174  167  particular, whenever the process is suspended or terminated, the terminal must
 175  168  be returned to a normal state. If this is not done, then depending on the
 176  169  characteristics of the shell that was used to invoke the program, the user
↓ open down ↓ 15 lines elided ↑ open up ↑ 
 192  185  where it was when \fBgl_normal_io()\fR was called, then switches back to raw,
 193  186  non-blocking terminal mode ready to continue entry of the input line when
 194  187  \fBgl_get_line()\fR is next called.
 195  188  .sp
 196  189  .LP
 197  190  Note that in non-blocking server mode, if \fBgl_get_line()\fR is called after a
 198  191  call to \fBgl_normal_io()\fR, without an intervening call to \fBgl_raw_io()\fR,
 199  192  \fBgl_get_line()\fR will call \fBgl_raw_mode()\fR itself, and the terminal will
 200  193  remain in this mode when \fBgl_get_line()\fR returns.
 201  194  .SS "Signal Handling"
 202      -.sp
 203      -.LP
 204  195  In the previous section it was pointed out that in non-blocking server mode,
 205  196  the terminal must be restored to a sane state whenever a signal is received
 206  197  that either suspends or terminates the process. In normal I/O mode, this is
 207  198  done for you by \fBgl_get_line()\fR, but in non-blocking server mode, since the
 208  199  terminal is left in raw mode between calls to \fBgl_get_line()\fR, this signal
 209  200  handling has to be done by the application. Since there are many signals that
 210  201  can suspend or terminate a process, as well as other signals that are important
 211  202  to \fBgl_get_line()\fR, such as the \fBSIGWINCH\fR signal, which tells it when
 212  203  the terminal size has changed, the \fBgl_tty_signals()\fR function is provided
 213  204  for installing signal handlers for all pertinent signals.
↓ open down ↓ 68 lines elided ↑ open up ↑ 
 282  273  The \fIsigno\fR argument tells this function which signal it is being asked to
 283  274  respond to, and the \fIgl\fR argument should be a pointer to the first element
 284  275  of an array of \fIngl\fR \fBGetLine\fR objects. If your application has only
 285  276  one of these objects, pass its pointer as the \fIgl\fR argument and specify
 286  277  \fIngl\fR as 1.
 287  278  .sp
 288  279  .LP
 289  280  Depending on the signal that is being handled, this function does different
 290  281  things.
 291  282  .SS "Process termination signals"
 292      -.sp
 293      -.LP
 294  283  If the signal that was caught is one of those that by default terminates any
 295  284  process that receives it, then \fBgl_handle_signal()\fR does the following
 296  285  steps.
 297  286  .RS +4
 298  287  .TP
 299  288  1.
 300  289  First it blocks the delivery of all signals that can be blocked (ie.
 301  290  \fBSIGKILL\fR and \fBSIGSTOP\fR cannot be blocked).
 302  291  .RE
 303  292  .RS +4
↓ open down ↓ 14 lines elided ↑ open up ↑ 
 318  307  4.
 319  308  Next it re-sends the process the signal that was caught.
 320  309  .RE
 321  310  .RS +4
 322  311  .TP
 323  312  5.
 324  313  Finally it unblocks delivery of this signal, which results in the process
 325  314  being terminated.
 326  315  .RE
 327  316  .SS "Process suspension signals"
 328      -.sp
 329      -.LP
 330  317  If the default disposition of the signal is to suspend the process, the same
 331  318  steps are executed as for process termination signals, except that when the
 332  319  process is later resumed, \fBgl_handle_signal()\fR continues, and does the
 333  320  following steps.
 334  321  .RS +4
 335  322  .TP
 336  323  1.
 337  324  It re-blocks delivery of the signal.
 338  325  .RE
 339  326  .RS +4
↓ open down ↓ 20 lines elided ↑ open up ↑ 
 360  347  Note that the process is suspended or terminated using the original signal that
 361  348  was caught, rather than using the uncatchable \fBSIGSTOP\fR and \fBSIGKILL\fR
 362  349  signals. This is important, because when a process is suspended or terminated,
 363  350  the parent of the process may wish to use the status value returned by the wait
 364  351  system call to figure out which signal was responsible. In particular, most
 365  352  shells use this information to print a corresponding message to the terminal.
 366  353  Users would be rightly confused if when their process received a \fBSIGPIPE\fR
 367  354  signal, the program responded by sending itself a \fBSIGKILL\fR signal, and the
 368  355  shell then printed out the provocative statement, "Killed!".
 369  356  .SS "Interrupting The Event Loop"
 370      -.sp
 371      -.LP
 372  357  If a signal is caught and handled when the application's event loop is waiting
 373  358  in \fBselect()\fR or \fBpoll()\fR, these functions will be aborted with
 374  359  \fBerrno\fR set to \fBEINTR\fR. When this happens the event loop should call
 375  360  \fBgl_pending_io()\fR before calling \fBselect()\fR or \fBpoll()\fR again. It
 376  361  should then arrange for \fBselect()\fR or \fBpoll()\fR to wait for the type of
 377  362  I/O that \fBgl_pending_io()\fR reports. This is necessary because any signal
 378  363  handler that calls \fBgl_handle_signal()\fR will frequently change the type of
 379  364  I/O that \fBgl_get_line()\fR is waiting for.
 380  365  .sp
 381  366  .LP
↓ open down ↓ 76 lines elided ↑ open up ↑ 
 458  443  following statements are always executed with all of our signals blocked.
 459  444  .RE
 460  445  .RS +4
 461  446  .TP
 462  447  10.
 463  448  Reinstate the signal handlers that were displaced in step 5.
 464  449  .RE
 465  450  .RS +4
 466  451  .TP
 467  452  11.
 468      -Check wether a signal was caught, by checking the file-scope variable that
      453 +Check whether a signal was caught, by checking the file-scope variable that
 469  454  the signal handler records signal numbers in.
 470  455  .RE
 471  456  .RS +4
 472  457  .TP
 473  458  12.
 474  459  If a signal was caught, send this signal to the application again and
 475  460  unblock only this signal so that it invokes the signal handler which was just
 476  461  reinstated in step 10.
 477  462  .RE
 478  463  .RS +4
 479  464  .TP
 480  465  13.
 481  466  Unblock all of the signals that were blocked in step 7.
 482  467  .RE
 483  468  .SS "Signals Caught By \fBgl_get_line()\fR"
 484      -.sp
 485      -.LP
 486  469  Since the application is expected to handle signals in non-blocking server
 487  470  mode, \fBgl_get_line()\fR does not attempt to duplicate this when it is being
 488  471  called. If one of the signals that it is configured to catch is sent to the
 489  472  application while \fBgl_get_line()\fR is being called, \fBgl_get_line()\fR
 490  473  reinstates the caller's signal handlers, then immediately before returning,
 491  474  re-sends the signal to the process to let the application's signal handler
 492  475  handle it. If the process is not terminated by this signal, \fBgl_get_line()\fR
 493  476  returns \fINULL\fR, and a following call to \fBgl_return_status()\fR returns
 494  477  the enumerated value \fBGLR_SIGNAL\fR.
 495  478  .SS "Aborting Line Input"
 496      -.sp
 497      -.LP
 498  479  Often, rather than letting it terminate the process, applications respond to
 499  480  the \fBSIGINT\fR user-interrupt signal by aborting the current input line. This
 500  481  can be accomplished in non-blocking server-I/O mode by not calling
 501  482  \fBgl_handle_signal()\fR when this signal is caught, but by calling instead the
 502  483  \fBgl_abandon_line()\fR function. This function arranges that when
 503  484  \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
      485 +terminal, discards the current input line, outputs a new prompt on the next
 505  486  line, and finally starts accepting input of a new input line from the user.
 506  487  .SS "Signal Safe Functions"
 507      -.sp
 508      -.LP
 509  488  Provided that certain rules are followed, the \fBgl_normal_io()\fR,
 510  489  \fBgl_raw_io()\fR, \fBgl_handle_signal()\fR, and \fBgl_abandon_line()\fR
 511  490  functions can be written to be safely callable from signal handlers. Other
 512  491  functions in this library should not be called from signal handlers. For this
 513  492  to be true, all signal handlers that call these functions must be registered in
 514  493  such a way that only one instance of any one of them can be running at one
 515  494  time. The way to do this is to use the POSIX \fBsigaction()\fR function to
 516  495  register all signal handlers, and when doing this, use the \fIsa_mask\fR member
 517  496  of the corresponding \fBsigaction\fR structure to indicate that all of the
 518  497  signals whose handlers invoke the above functions should be blocked when the
↓ open down ↓ 4 lines elided ↑ open up ↑ 
 523  502  To prevent signal handlers from accessing a \fBGetLine\fR object while
 524  503  \fBgl_get_line()\fR or any of its associated public functions are operating on
 525  504  it, all public functions associated with \fBgl_get_line()\fR, including
 526  505  \fBgl_get_line()\fR itself, temporarily block the delivery of signals when they
 527  506  are accessing \fBGetLine\fR objects. Beware that the only signals that they
 528  507  block are the signals that \fBgl_get_line()\fR is currently configured to
 529  508  catch, so be sure that if you call any of the above functions from signal
 530  509  handlers, that the signals that these handlers are assigned to are configured
 531  510  to be caught by \fBgl_get_line()\fR. See \fBgl_trap_signal\fR(3TECLA).
 532  511  .SS "Using Timeouts To Poll"
 533      -.sp
 534      -.LP
 535  512  If instead of using \fBselect()\fR or \fBpoll()\fR to wait for I/O your
 536  513  application needs only to get out of \fBgl_get_line()\fR periodically to
 537  514  briefly do something else before returning to accept input from the user, use
 538  515  the \fBgl_inactivity_timeout\fR(3TECLA) function in non-blocking server mode to
 539  516  specify that a callback function that returns \fBGLTO_CONTINUE\fR should be
 540  517  called whenever \fBgl_get_line()\fR has been waiting for I/O for more than a
 541  518  specified amount of time. When this callback is triggered, \fBgl_get_line()\fR
 542  519  will return \fINULL\fR and a following call to \fBgl_return_status()\fR will
 543  520  return \fBGLR_BLOCKED\fR.
 544  521  .sp
 545  522  .LP
 546  523  The \fBgl_get_line()\fR function will not return until the user has not typed a
 547  524  key for the specified interval, so if the interval is long and the user keeps
 548  525  typing, \fBgl_get_line()\fR might not return for a while. There is no guarantee
 549  526  that it will return in the time specified.
 550  527  .SH ATTRIBUTES
 551      -.sp
 552      -.LP
 553  528  See \fBattributes\fR(5) for descriptions of the following attributes:
 554  529  .sp
 555  530  
 556  531  .sp
 557  532  .TS
 558  533  box;
 559  534  c | c
 560  535  l | l .
 561  536  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 562  537  _
 563  538  Interface Stability     Evolving
 564  539  _
 565  540  MT-Level        MT-Safe
 566  541  .TE
 567  542  
 568  543  .SH SEE ALSO
 569      -.sp
 570      -.LP
 571  544  \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
 572  545  \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBpca_lookup_file\fR(3TECLA),
 573  546  \fBattributes\fR(5), \fBtecla\fR(5)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX