gl_normal_io man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

gl_io_mode(3TECInteractive Command-line Input Library Functigl_io_mode(3TECLA)

NAME
       gl_io_mode,  gl_raw_io,	gl_normal_io, gl_tty_signals, gl_abandon_line,
       gl_handle_signal, gl_pending_io - use gl_get_line()  from  an  external
       event loop

SYNOPSIS
       cc [ flag... ] file... -ltecla [ library... ]
       #include <libtecla.h>

       int gl_io_mode(GetLine *gl, GlIOMode mode);

       int gl_raw_io(GetLine *gl);

       int gl_normal_io(GetLine *gl);

       int    gl_tty_signals(void   (*term_handler)(int),   void   (*susp_han‐
       dler)(int), void (*cont_handler)(int), void (*size_handler)(int));

       void gl_abandon_line(GetLine *gl);

       void gl_handle_signal(int signo, GetLine *gl, int ngl);

       GlPendingIO gl_pending_io(GetLine *gl);

DESCRIPTION
       The gl_get_line(3TECLA) function	 supports  two	different  I/O	modes.
       These are selected by calling the gl_io_mode() function. The mode argu‐
       ment of gl_io_mode() specifies the new I/O mode and must be one of  the
       following.

       GL_NORMAL_MODE	       Select  the  normal  blocking-I/O mode. In this
			       mode gl_get_line() does not return until either
			       an error occurs of the user finishes entering a
			       new line.

       GL_SERVER_MODE	       Select non-blocking server I/O  mode.  In  this
			       mode,  since non-blocking terminal I/O is used,
			       the entry of  each  new	input  line  typically
			       requires	 many  calls  to gl_get_line() from an
			       external I/O-driven event loop.

       Newly created GetLine objects start in normal I/O mode, so to switch to
       non-blocking server mode requires an initial call to gl_io_mode().

   Server I/O Mode
       In non-blocking server I/O mode, the application is required to have an
       event loop that calls gl_get_line() whenever the terminal file descrip‐
       tor  can	 perform  the  type  I/O that gl_get_line() is waiting for. To
       determine which type of I/O gl_get_line() is waiting for, the  applica‐
       tion  calls  the	 gl_pending_io() function.  The return value is one of
       the following two enumerated values.

       GLP_READ	       gl_get_line() is waiting to write a  character  to  the
		       terminal.

       GLP_WRITE       gl_get_line()  is  waiting to read a character from the
		       keyboad.

       If the application is using either the select(3C) or  poll(2)  function
       to  watch  for  I/O on a group of file descriptors, then it should call
       the gl_pending_io() function before each call  to  these	 functions  to
       determine  which direction of I/O it should tell them to watch for, and
       configure their arguments accordingly. In  the  case  of	 the  select()
       function,  this means using the FD_SET() macro to add the terminal file
       descriptor either to the set of file  descriptors  to  be  watched  for
       readability or the set to be watched for writability.

       As  in  normal  I/O mode, the return value of gl_get_line() is either a
       pointer to a completed input line or NULL. However, whereas  in	normal
       I/O  mode  a  NULL return value always means that an error occurred, in
       non-blocking server mode, NULL is also returned when gl_get_line() can‐
       not  read or write to the terminal without blocking. Thus in non-block‐
       ing server mode, in order to determine when a NULL return value	signi‐
       fies  that  an  error  occurred	or  not,  it  is necessary to call the
       gl_return_status() function. If this function  returns  the  enumerated
       value  GLR_BLOCKED,  gl_get_line()  is waiting for I/O and no error has
       occurred.

       When gl_get_line() returns NULL and gl_return_status()  indicates  that
       this  is	 due  to  blocked  terminal  I/O,  the application should call
       gl_get_line() again when the type of I/O	 reported  by  gl_pending_io()
       becomes	possible.  The	prompt,	 start_line and start_pos arguments of
       gl_get_line() will be ignored on these calls. If you need to change the
       prompt  of  the	line  that is currently being edited, you can call the
       gl_replace_prompt(3TECLA) function between calls to gl_get_line().

   Giving Up The Terminal
       A complication that is unique to non-blocking server mode  is  that  it
       requires	 that  the  terminal  be  left	in  raw	 mode between calls to
       gl_get_line(). If this were not the case, the external event loop would
       not  be able to detect individual key-presses, and the basic line edit‐
       ing implemented by the terminal driver would  clash  with  the  editing
       provided	 by gl_get_line(). When the terminal needs to be used for pur‐
       poses other than entering a new input line with gl_get_line(), it needs
       to  be  restored to a usable state. In particular, whenever the process
       is suspended or terminated, the terminal must be returned to  a	normal
       state.  If  this	 is not done, then depending on the characteristics of
       the shell that was used to invoke the program, the user	could  end  up
       with  a hung terminal. To this end, the gl_normal_io() function is pro‐
       vided for switching the terminal back to the state that it was in  when
       raw mode was last established.

       The  gl_normal_io()  function  first  flushes any pending output to the
       terminal, then moves the cursor to the start of the terminal line which
       follows	the  end of the incompletely entered input line. At this point
       it is safe to suspend or terminate the process, and it is safe for  the
       application  to	read and write to the terminal. To resume entry of the
       input line, the application should call the gl_raw_io() function.

       The gl_normal_io() function starts a new line, redisplays the partially
       completed input line (if any), restores the cursor position within this
       line to where it was when gl_normal_io() was called, then switches back
       to raw, non-blocking terminal mode ready to continue entry of the input
       line when gl_get_line() is next called.

       Note that in non-blocking server mode, if gl_get_line() is called after
       a  call	to gl_normal_io(), without an intervening call to gl_raw_io(),
       gl_get_line() will call gl_raw_mode() itself,  and  the	terminal  will
       remain in this mode when gl_get_line() returns.

   Signal Handling
       In  the previous section it was pointed out that in non-blocking server
       mode, the terminal must be restored to a sane state whenever  a	signal
       is  received  that either suspends or terminates the process. In normal
       I/O mode, this is done for you by gl_get_line(),	 but  in  non-blocking
       server  mode,  since  the terminal is left in raw mode between calls to
       gl_get_line(), this signal handling has to be done by the  application.
       Since  there  are many signals that can suspend or terminate a process,
       as well as other signals that are important to gl_get_line(),  such  as
       the SIGWINCH signal, which tells it when the terminal size has changed,
       the gl_tty_signals() function is provided for  installing  signal  han‐
       dlers for all pertinent signals.

       The  gl_tty_signals()  function	uses  gl_get_line()'s internal list of
       signals to assign specified signal handlers to groups of	 signals.  The
       arguments of this function are as follows.

       term_handler    This is the signal handler that is used to trap signals
		       that by default terminate  any  process	that  receives
		       them (for example, SIGINT or SIGTERM).

       susp_handler    This is the signal handler that is used to trap signals
		       that by default suspend any process that receives them,
		       (for example, SIGTSTP or SIGTTOU).

       cont_handler    This is the signal handler that is used to trap signals
		       that are usually sent  when  a  process	resumes	 after
		       being suspended (usually SIGCONT). Beware that there is
		       nothing to stop a user from sending one of  these  sig‐
		       nals at other times.

       size_handler    This  signal  handler  is used to trap signals that are
		       sent to processes when their controlling terminals  are
		       resized by the user (for example, SIGWINCH).

       These arguments can all be the same, if so desired, and SIG_IGN (ignore
       this signal) or SIG_DFL (use the system-provided	 default  signal  han‐
       dler)  can  be specified instead of a function where pertinent. In par‐
       ticular, it is rarely useful to trap SIGCONT, so the cont_handler argu‐
       ment will usually be SIG_DFL or SIG_IGN.

       The  gl_tty_signals()  function uses the POSIX sigaction(2) function to
       install these signal handlers, and it is careful	 to  use  the  sa_mask
       member  of  each	 sigaction  structure to ensure that only one of these
       signals is ever delivered at a  time.  This  guards  against  different
       instances  of these signal handlers from simultaneously trying to write
       to common global data, such as a shared sigsetjmp(3C) buffer or a  sig‐
       nal-received  flag.  The	 signal	 handlers  installed  by this function
       should call the gl_handle_signal().

       The signo argument tells this function which signal it is  being	 asked
       to  respond  to,	 and  the gl argument should be a pointer to the first
       element of an array of ngl GetLine objects.  If	your  application  has
       only  one  of  these  objects,  pass its pointer as the gl argument and
       specify ngl as 1.

       Depending on the signal that is being handled, this function does  dif‐
       ferent things.

   Process termination signals
       If  the	signal	that was caught is one of those that by default termi‐
       nates any process that receives it, then	 gl_handle_signal()  does  the
       following steps.

       1.  First  it  blocks  the  delivery of all signals that can be blocked
	   (ie. SIGKILL and SIGSTOP cannot be blocked).

       2.  Next it calls gl_normal_io() for each of the ngl  GetLine  objects.
	   Note	 that this does nothing to any of the GetLine objects that are
	   not currently in raw mode.

       3.  Next it sets the signal handler  of	the  signal  to	 its  default,
	   process-termination disposition.

       4.  Next it re-sends the process the signal that was caught.

       5.  Finally  it	unblocks delivery of this signal, which results in the
	   process being terminated.

   Process suspension signals
       If the default disposition of the signal is to suspend the process, the
       same steps are executed as for process termination signals, except that
       when the process is later resumed,  gl_handle_signal()  continues,  and
       does the following steps.

       1.  It re-blocks delivery of the signal.

       2.  It  reinstates the signal handler of the signal to the one that was
	   displaced when its default disposition was substituted.

       3.  For any of the GetLine objects that were in raw mode	 when  gl_han‐
	   dle_signal() was called, gl_handle_signal() then calls gl_raw_io(),
	   to resume entry of the input lines on those terminals.

       4.  Finally, it restores the signal process mask to  how	 it  was  when
	   gl_handle_signal() was called.

       Note  that  the	process	 is suspended or terminated using the original
       signal that was caught, rather than using the uncatchable  SIGSTOP  and
       SIGKILL signals. This is important, because when a process is suspended
       or terminated, the parent of the process may wish  to  use  the	status
       value  returned	by the wait system call to figure out which signal was
       responsible. In particular, most shells use this information to print a
       corresponding  message to the terminal. Users would be rightly confused
       if when their process received a SIGPIPE signal, the program  responded
       by  sending itself a SIGKILL signal, and the shell then printed out the
       provocative statement, "Killed!".

   Interrupting The Event Loop
       If a signal is caught and handled when the application's event loop  is
       waiting	in  select()  or  poll(), these functions will be aborted with
       errno set to EINTR. When	 this  happens	the  event  loop  should  call
       gl_pending_io() before calling select() or poll() again. It should then
       arrange for select() or poll()  to  wait	 for  the  type	 of  I/O  that
       gl_pending_io()	reports.  This is necessary because any signal handler
       that calls gl_handle_signal() will frequently change the	 type  of  I/O
       that gl_get_line() is waiting for.

       If a signal arrives between the statements that configure the arguments
       of select() or poll() and the calls to these functions, the signal will
       not  be	seen  by  these	 functions, which will then not be aborted. If
       these functions are waiting for keyboard input from the user  when  the
       signal is received, and the signal handler arranges to redraw the input
       line to accommodate a terminal resize or the resumption of the process.
       This  redisplay	will  be  delayed until the user presses the next key.
       Apart from puzzling the user, this clearly is not  a  serious  problem.
       However	there  is  a way, albeit complicated, to completely avoid this
       race condition. The following steps illustrate this.

       1.  Block all of the signals that gl_get_line() catches, by passing the
	   signal set returned by gl_list_signals() to sigprocmask(2).

       2.  Call gl_pending_io() and set up the arguments of select() or poll()
	   accordingly.

       3.  Call sigsetjmp(3C) with a non-zero savemask argument.

       4.  Initially this sigsetjmp() statement will return  zero,  indicating
	   that	 control  is  not resuming there after a matching call to sig‐
	   longjmp(3C).

       5.  Replace all of the handlers of the signals  that  gl_get_line()  is
	   configured  to  catch, with a signal handler that first records the
	   number of the signal that was caught,  in  a	 file-scope  variable,
	   then	 calls	siglongjmp()  with  a non-zero val argument, to return
	   execution to the above  sigsetjmp()	statement.  Registering	 these
	   signal handlers can conveniently be done using the gl_tty_signals()
	   function.

       6.  Set the file-scope variable that the above signal handler  uses  to
	   record  any	signal	that  is  caught  to  -1, so that we can check
	   whether a signal was caught by seeing if it contains a valid signal
	   number.

       7.  Now	unblock	 the  signals  that were blocked in step 1. Any signal
	   that was received by the process in between step 1 and now will now
	   be  delivered,  and	trigger our signal handler, as will any signal
	   that is received until we block these signals again.

       8.  Now call select() or poll().

       9.  When select returns, again block the signals that were unblocked in
	   step 7.

	   If  a signal is arrived any time during the above steps, our signal
	   handler will be triggered  and  cause  control  to  return  to  the
	   sigsetjmp()	statement,  where  this	 time, sigsetjmp() will return
	   non-zero, indicating that a signal was caught. When this happens we
	   simply  skip	 the  above block of statements, and continue with the
	   following statements, which are executed regardless of  whether  or
	   not a signal is caught. Note that when sigsetjmp() returns, regard‐
	   less of why it returned, the process signal mask is returned to how
	   it  was  when sigsetjmp() was called. Thus the following statements
	   are always executed with all of our signals blocked.

       10. Reinstate the signal handlers that were displaced in step 5.

       11. Check wether a signal was caught, by checking the file-scope	 vari‐
	   able that the signal handler records signal numbers in.

       12. If  a  signal was caught, send this signal to the application again
	   and unblock only this signal so that it invokes the signal  handler
	   which was just reinstated in step 10.

       13. Unblock all of the signals that were blocked in step 7.

   Signals Caught By gl_get_line()
       Since  the  application	is  expected to handle signals in non-blocking
       server mode, gl_get_line() does not attempt to duplicate this  when  it
       is  being  called. If one of the signals that it is configured to catch
       is sent	to  the	 application  while  gl_get_line()  is	being  called,
       gl_get_line() reinstates the caller's signal handlers, then immediately
       before returning, re-sends the signal to the process to let the	appli‐
       cation's	 signal handler handle it. If the process is not terminated by
       this signal, gl_get_line()  returns  NULL,  and	a  following  call  to
       gl_return_status() returns the enumerated value GLR_SIGNAL.

   Aborting Line Input
       Often,  rather  than  letting  it  terminate  the process, applications
       respond to the SIGINT user-interrupt signal  by	aborting  the  current
       input line. This can be accomplished in non-blocking server-I/O mode by
       not calling gl_handle_signal() when this signal is caught, but by call‐
       ing instead the gl_abandon_line() function. This function arranges that
       when gl_get_line() is next called, it first flushes any pending	output
       to the terminal, discardes the current input line, outputs a new prompt
       on the next line, and finally starts accepting input  of	 a  new	 input
       line from the user.

   Signal Safe Functions
       Provided	  that	 certain   rules  are  followed,  the  gl_normal_io(),
       gl_raw_io(), gl_handle_signal(), and gl_abandon_line() functions can be
       written	to be safely callable from signal handlers. Other functions in
       this library should not be called from signal handlers. For this to  be
       true,  all signal handlers that call these functions must be registered
       in such a way that only one instance of any one of them can be  running
       at  one	time. The way to do this is to use the POSIX sigaction() func‐
       tion to register all signal handlers, and  when	doing  this,  use  the
       sa_mask	member	of  the	 corresponding sigaction structure to indicate
       that all of the signals	whose  handlers	 invoke	 the  above  functions
       should  be  blocked when the current signal is being handled. This pre‐
       vents two signal handlers from operating on a  GetLine  object  at  the
       same time.

       To  prevent  signal  handlers  from  accessing  a  GetLine object while
       gl_get_line() or any of its associated public functions	are  operating
       on  it,	all  public functions associated with gl_get_line(), including
       gl_get_line() itself, temporarily block the delivery  of	 signals  when
       they  are  accessing GetLine objects. Beware that the only signals that
       they block are the signals that gl_get_line() is	 currently  configured
       to  catch,  so be sure that if you call any of the above functions from
       signal handlers, that the signals that these handlers are  assigned  to
       are   configured	 to  be	 caught	 by  gl_get_line().  See  gl_trap_sig‐
       nal(3TECLA).

   Using Timeouts To Poll
       If instead of using select() or poll() to wait for I/O your application
       needs only to get out of gl_get_line() periodically to briefly do some‐
       thing else before returning to accept input  from  the  user,  use  the
       gl_inactivity_timeout(3TECLA)  function	in non-blocking server mode to
       specify that a callback function that returns GLTO_CONTINUE  should  be
       called  whenever gl_get_line() has been waiting for I/O for more than a
       specified  amount  of  time.   When   this   callback   is   triggered,
       gl_get_line()  will  return NULL and a following call to gl_return_sta‐
       tus() will return GLR_BLOCKED.

       The gl_get_line() function will not return until the user has not typed
       a  key  for  the specified interval, so if the interval is long and the
       user keeps typing, gl_get_line() might not return for a while. There is
       no guarantee that it will return in the time specified.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Evolving			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
       libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5), tecla(5)

SunOS 5.10			  1 Jun 2004		    gl_io_mode(3TECLA)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net