gl_abandon_line man page on SmartOS

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

GL_IO_MODE(3TECLA)					    GL_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_handler)(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 ter‐
		    minal.

       GLP_WRITE
		    gl_get_line() is waiting to read a character from the key‐
		    boad.

       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 substi‐
		  tuted.

	   3.	  For any of the GetLine objects that were in  raw  mode  when
		  gl_handle_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 sig‐
		  procmask(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, indi‐
		  cating  that	control is not resuming there after a matching
		  call to siglongjmp(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  con‐
		  tains 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 han‐
		  dler, 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	state‐
		  ments, and continue with the following statements, which are
		  executed regardless of whether or not a  signal  is  caught.
		  Note	that  when  sigsetjmp()	 returns, regardless 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
		  variable 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)

				  Jun 1, 2004		    GL_IO_MODE(3TECLA)
[top]

List of man pages available for SmartOS

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