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);
The gl_get_line(3TECLA) function supports two different I/O modes. These
are selected by calling the gl_io_mode() function. 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 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().
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 of 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 keyboard.
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() 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 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().
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 editing implemented by the terminal
driver would clash with the editing provided by gl_get_line(). When the
terminal needs to be used for purposes 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 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 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.
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 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 a process resumes after being suspended (usually
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 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 handler) can be specified instead of a
function where pertinent. In particular, it is rarely useful to trap
SIGCONT, so the cont_handler argument 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 signal-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.
If the signal that was caught is one of those that by default terminates 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.
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_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!".
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
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 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, 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 whether 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.
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 application'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.
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 calling 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, discards 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.
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() function 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 prevents 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_signal(3TECLA).
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 something 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_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 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.