Interactive Command-line Input Library Functions
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
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() func-
tion. The mode argument 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 togl_get_line() from an external I/O-driven
event loop.SunOS 5.11 Last change: 1 Jun 2004 1
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
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 descriptor 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 application 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 argu-
ments 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 bewatched for readability or the set to be watched for writa-
bility.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() cannot read or write to the
terminal without blocking. Thus in non-blocking server mode,
in order to determine when a NULL return value signifies that an error occurred or not, it is necessary to call thegl_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() indi-
cates that this is due to blocked terminal I/O, the applica-
tion should call gl_get_line() again when the type of I/O
reported by gl_pending_io() becomes possible. The prompt,
SunOS 5.11 Last change: 1 Jun 2004 2
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
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 thegl_replace_prompt(3TECLA) function between calls to
gl_get_line().
Giving Up The TerminalA complication that is unique to non-blocking server mode is
that it requires that the terminal be left in raw modebetween calls to gl_get_line(). If this were not the case,
the external event loop would not be able to detect indivi-
dual key-presses, and the basic line editing implemented by
the terminal driver would clash with the editing provided bygl_get_line(). When the terminal needs to be used for pur-
poses other than entering a new input line withgl_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 upwith a hung terminal. To this end, the gl_normal_io() func-
tion is provided 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 inputline, 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 whengl_normal_io() was called, then switches back to raw, non-
blocking terminal mode ready to continue entry of the inputline 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 interven-
ing 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 HandlingIn the previous section it was pointed out that in non-
blocking server mode, the terminal must be restored to aSunOS 5.11 Last change: 1 Jun 2004 3
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
sane state whenever a signal is received that eithersuspends 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 callsto 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 areimportant to gl_get_line(), such as the SIGWINCH signal,
which tells it when the terminal size has changed, thegl_tty_signals() function is provided for installing signal
handlers 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 aprocess resumes after being suspended (usu-
ally SIGCONT). Beware that there is nothing to stop a user from sending one of these signals at other times.size_handler This signal handler is used to trap signals
that are sent to processes when their con-
trolling terminals are resized by the user (for example, SIGWINCH). These arguments can all be the same, if so desired, andSIG_IGN (ignore this signal) or SIG_DFL (use the system-
provided default signal handler) can be specified instead ofa function where pertinent. In particular, it is rarely use-
ful to trap SIGCONT, so the cont_handler argument will usu-
ally be SIG_DFL or SIG_IGN.
SunOS 5.11 Last change: 1 Jun 2004 4
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
The gl_tty_signals() function uses the POSIX sigaction(2)
function to install these signal handlers, and it is carefulto use the sa_mask member of each sigaction structure to
ensure that only one of these signals is ever delivered at atime. This guards against different instances of these sig-
nal handlers from simultaneously trying to write to common global data, such as a shared sigsetjmp(3C) buffer or asignal-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 different things. Process termination signals If the signal that was caught is one of those that by default terminates any process that receives it, thengl_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 toits 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 theprocess, the same steps are executed as for process termina-
tion 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.
SunOS 5.11 Last change: 1 Jun 2004 5
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
2. It reinstates the signal handler of the signal tothe one that was displaced when its default dispo-
sition was substituted. 3. For any of the GetLine objects that were in rawmode 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 howit 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 signalwas responsible. In particular, most shells use this infor-
mation 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 happensthe event loop should call gl_pending_io() before calling
select() or poll() again. It should then arrange forselect() or poll() to wait for the type of I/O that
gl_pending_io() reports. This is necessary because any sig-
nal 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 wait-
ing for keyboard input from the user when the signal is received, and the signal handler arranges to redraw theinput line to accommodate a terminal resize or the resump-
tion 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 away, albeit complicated, to completely avoid this race con-
dition. The following steps illustrate this.SunOS 5.11 Last change: 1 Jun 2004 6
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
1. Block all of the signals that gl_get_line()
catches, by passing the signal set returned bygl_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 argu-
ment. 4. Initially this sigsetjmp() statement will return zero, indicating that control is not resuming there after a matching call to siglongjmp(3C). 5. Replace all of the handlers of the signals thatgl_get_line() is configured to catch, with a signal
handler that first records the number of the signalthat was caught, in a file-scope variable, then
calls siglongjmp() with a non-zero val argument, to
return execution to the above sigsetjmp() state-
ment. Registering these signal handlers can con-
veniently be done using the gl_tty_signals() func-
tion.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 andcause control to return to the sigsetjmp() state-
ment, where this time, sigsetjmp() will returnnon-zero, indicating that a signal was caught. When
this happens we simply skip the above block ofstatements, and continue with the following state-
ments, which are executed regardless of whether or not a signal is caught. Note that when sigsetjmp() returns, regardless of why it returned, the processSunOS 5.11 Last change: 1 Jun 2004 7
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
signal mask is returned to how it was when sig-
setjmp() 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 thefile-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 sig-
nals that it is configured to catch is sent to the applica-
tion while gl_get_line() is being called, gl_get_line()
reinstates the caller's signal handlers, then immediatelybefore returning, re-sends the signal to the process to let
the application's signal handler handle it. If the processis 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 InputOften, rather than letting it terminate the process, appli-
cations respond to the SIGINT user-interrupt signal by
aborting the current input line. This can be accomplished innon-blocking server-I/O mode by not calling
gl_handle_signal() when this signal is caught, but by cal-
ling 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, thegl_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 thisSunOS 5.11 Last change: 1 Jun 2004 8
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
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() function to registerall 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 prevents two signal handlers from operating on a GetLine object at the same time. To prevent signal handlers from accessing a GetLine objectwhile gl_get_line() or any of its associated public func-
tions are operating on it, all public functions associatedwith gl_get_line(), including gl_get_line() itself, tem-
porarily block the delivery of signals when they are access-
ing GetLine objects. Beware that the only signals that theyblock are the signals that gl_get_line() is currently con-
figured 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 caughtby gl_get_line(). See gl_trap_signal(3TECLA).
Using Timeouts To PollIf instead of using select() or poll() to wait for I/O your
application needs only to get out of gl_get_line() periodi-
cally to briefly do something else before returning to accept input from the user, use thegl_inactivity_timeout(3TECLA) function in non-blocking
server mode to specify that a callback function that returnsGLTO_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_status() 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 theinterval 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 attri-
butes:SunOS 5.11 Last change: 1 Jun 2004 9
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
______________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| 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.11 Last change: 1 Jun 2004 10
Interactive Command-line Input Library Functions
gl_io_mode(3TECLA)
SunOS 5.11 Last change: 1 Jun 2004 11