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 ALSOcpl_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)
