Unleashed v1.4

[unleashed.git] / share / man / man3tecla / gl_io_mode.3tecla

'\" te
.\" Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
.\" All Rights Reserved.
.\" Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, and/or sell copies of the Software, and to permit persons
.\" to whom the Software is furnished to do so, provided that the above
.\" copyright notice(s) and this permission notice appear in all copies of
.\" the Software and that both the above copyright notice(s) and this
.\" permission notice appear in supporting documentation.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" Except as contained in this notice, the name of a copyright holder
.\" shall not be used in advertising or otherwise to promote the sale, use
.\" or other dealings in this Software without prior written authorization
.\" of the copyright holder.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.TH GL_IO_MODE 3TECLA "Jun 1, 2004"
.SH NAME
gl_io_mode, gl_raw_io, gl_normal_io, gl_tty_signals, gl_abandon_line,
gl_handle_signal, gl_pending_io \- use \fBgl_get_line()\fR from an external
event loop
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libtecla.h>

\fBint\fR \fBgl_io_mode\fR(\fBGetLine *\fR\fIgl\fR, \fBGlIOMode\fR \fImode\fR);
.fi

.LP
.nf
\fBint\fR \fBgl_raw_io\fR(\fBGetLine *\fR\fIgl\fR);
.fi

.LP
.nf
\fBint\fR \fBgl_normal_io\fR(\fBGetLine *\fR\fIgl\fR);
.fi

.LP
.nf
\fBint\fR \fBgl_tty_signals\fR(\fBvoid (*\fR\fIterm_handler\fR)(int), \fBvoid (*\fR\fIsusp_handler\fR)(int),
     \fBvoid (*\fR\fIcont_handler\fR)(int), \fBvoid (*\fR\fIsize_handler\fR)(int));
.fi

.LP
.nf
\fBvoid\fR \fBgl_abandon_line\fR(\fBGetLine *\fR\fIgl\fR);
.fi

.LP
.nf
\fBvoid\fR \fBgl_handle_signal\fR(\fBint\fR \fIsigno\fR, \fBGetLine *\fR\fIgl\fR, \fBint\fR \fIngl\fR);
.fi

.LP
.nf
\fBGlPendingIO\fR \fBgl_pending_io\fR(\fBGetLine *\fR\fIgl\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgl_get_line\fR(3TECLA) function supports two different I/O modes. These
are selected by calling the \fBgl_io_mode()\fR function. The \fImode\fR
argument of \fBgl_io_mode()\fR specifies the new I/O mode and must be one of
the following.
.sp
.ne 2
.na
\fB\fBGL_NORMAL_MODE\fR\fR
.ad
.RS 18n
Select the normal blocking-I/O mode. In this mode \fBgl_get_line()\fR does not
return until either an error occurs of the user finishes entering a new line.
.RE

.sp
.ne 2
.na
\fB\fBGL_SERVER_MODE\fR\fR
.ad
.RS 18n
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
\fBgl_get_line()\fR from an external I/O-driven event loop.
.RE

.sp
.LP
Newly created GetLine objects start in normal I/O mode, so to switch to
non-blocking server mode requires an initial call to \fBgl_io_mode()\fR.
.SS "Server I/O Mode"
.sp
.LP
In non-blocking server I/O mode, the application is required to have an event
loop that calls \fBgl_get_line()\fR whenever the terminal file descriptor can
perform the type I/O that \fBgl_get_line()\fR is waiting for. To determine
which type of I/O \fBgl_get_line()\fR is waiting for, the application calls the
\fBgl_pending_io()\fR function.  The return value is one of the following two
enumerated values.
.sp
.ne 2
.na
\fB\fBGLP_READ\fR\fR
.ad
.RS 13n
\fBgl_get_line()\fR is waiting to write a character to the terminal.
.RE

.sp
.ne 2
.na
\fB\fBGLP_WRITE\fR\fR
.ad
.RS 13n
\fBgl_get_line()\fR is waiting to read a character from the keyboad.
.RE

.sp
.LP
If the application is using either the \fBselect\fR(3C) or \fBpoll\fR(2)
function to watch for I/O on a group of file descriptors, then it should call
the \fBgl_pending_io()\fR 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 \fBselect()\fR
function, this means using the \fBFD_SET()\fR 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.
.sp
.LP
As in normal I/O mode, the return value of \fBgl_get_line()\fR is either a
pointer to a completed input line or \fINULL\fR. However, whereas in normal I/O
mode a \fINULL\fR return value always means that an error occurred, in
non-blocking server mode, \fINULL\fR is also returned when \fBgl_get_line()\fR
cannot read or write to the terminal without blocking. Thus in non-blocking
server mode, in order to determine when a \fINULL\fR return value signifies
that an error occurred or not, it is necessary to call the
\fBgl_return_status()\fR function. If this function returns the enumerated
value \fBGLR_BLOCKED\fR, \fBgl_get_line()\fR is waiting for I/O and no error
has occurred.
.sp
.LP
When \fBgl_get_line()\fR returns \fINULL\fR and \fBgl_return_status()\fR
indicates that this is due to blocked terminal I/O, the application should call
\fBgl_get_line()\fR again when the type of I/O reported by
\fBgl_pending_io()\fR becomes possible. The \fIprompt\fR, \fIstart_line\fR and
\fIstart_pos\fR arguments of \fBgl_get_line()\fR 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 \fBgl_replace_prompt\fR(3TECLA) function between calls
to \fBgl_get_line()\fR.
.SS "Giving Up The Terminal"
.sp
.LP
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 \fBgl_get_line()\fR. 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 \fBgl_get_line()\fR. When the
terminal needs to be used for purposes other than entering a new input line
with \fBgl_get_line()\fR, 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 \fBgl_normal_io()\fR
function is provided for switching the terminal back to the state that it was
in when raw mode was last established.
.sp
.LP
The \fBgl_normal_io()\fR 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 \fBgl_raw_io()\fR function.
.sp
.LP
The \fBgl_normal_io()\fR 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 \fBgl_normal_io()\fR was called, then switches back to raw,
non-blocking terminal mode ready to continue entry of the input line when
\fBgl_get_line()\fR is next called.
.sp
.LP
Note that in non-blocking server mode, if \fBgl_get_line()\fR is called after a
call to \fBgl_normal_io()\fR, without an intervening call to \fBgl_raw_io()\fR,
\fBgl_get_line()\fR will call \fBgl_raw_mode()\fR itself, and the terminal will
remain in this mode when \fBgl_get_line()\fR returns.
.SS "Signal Handling"
.sp
.LP
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 \fBgl_get_line()\fR, but in non-blocking server mode, since the
terminal is left in raw mode between calls to \fBgl_get_line()\fR, 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 \fBgl_get_line()\fR, such as the \fBSIGWINCH\fR signal, which tells it when
the terminal size has changed, the \fBgl_tty_signals()\fR function is provided
for installing signal handlers for all pertinent signals.
.sp
.LP
The \fBgl_tty_signals()\fR function uses \fBgl_get_line()\fR's internal list of
signals to assign specified signal handlers to groups of signals. The arguments
of this function are as follows.
.sp
.ne 2
.na
\fB\fIterm_handler\fR\fR
.ad
.RS 16n
This is the signal handler that is used to trap signals that by default
terminate any process that receives them (for example, \fBSIGINT\fR or
\fBSIGTERM\fR).
.RE

.sp
.ne 2
.na
\fB\fIsusp_handler\fR\fR
.ad
.RS 16n
This is the signal handler that is used to trap signals that by default suspend
any process that receives them, (for example, \fBSIGTSTP\fR or \fBSIGTTOU\fR).
.RE

.sp
.ne 2
.na
\fB\fIcont_handler\fR\fR
.ad
.RS 16n
This is the signal handler that is used to trap signals that are usually sent
when a process resumes after being suspended (usually \fBSIGCONT\fR). Beware
that there is nothing to stop a user from sending one of these signals at other
times.
.RE

.sp
.ne 2
.na
\fB\fIsize_handler\fR\fR
.ad
.RS 16n
This signal handler is used to trap signals that are sent to processes when
their controlling terminals are resized by the user (for example,
\fBSIGWINCH\fR).
.RE

.sp
.LP
These arguments can all be the same, if so desired, and \fBSIG_IGN\fR (ignore
this signal) or \fBSIG_DFL\fR (use the system-provided default signal handler)
can be specified instead of a function where pertinent. In particular, it is
rarely useful to trap \fBSIGCONT\fR, so the \fIcont_handler\fR argument will
usually be \fBSIG_DFL\fR or \fBSIG_IGN\fR.
.sp
.LP
The \fBgl_tty_signals()\fR function uses the POSIX \fBsigaction\fR(2) function
to install these signal handlers, and it is careful to use the \fIsa_mask\fR
member of each \fBsigaction\fR 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 \fBsigsetjmp\fR(3C) buffer or a signal-received flag.
The signal handlers installed by this function should call the
\fBgl_handle_signal()\fR.
.sp
.LP
The \fIsigno\fR argument tells this function which signal it is being asked to
respond to, and the \fIgl\fR argument should be a pointer to the first element
of an array of \fIngl\fR \fBGetLine\fR objects. If your application has only
one of these objects, pass its pointer as the \fIgl\fR argument and specify
\fIngl\fR as 1.
.sp
.LP
Depending on the signal that is being handled, this function does different
things.
.SS "Process termination signals"
.sp
.LP
If the signal that was caught is one of those that by default terminates any
process that receives it, then \fBgl_handle_signal()\fR does the following
steps.
.RS +4
.TP
1.
First it blocks the delivery of all signals that can be blocked (ie.
\fBSIGKILL\fR and \fBSIGSTOP\fR cannot be blocked).
.RE
.RS +4
.TP
2.
Next it calls \fBgl_normal_io()\fR 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.
.RE
.RS +4
.TP
3.
Next it sets the signal handler of the signal to its default,
process-termination disposition.
.RE
.RS +4
.TP
4.
Next it re-sends the process the signal that was caught.
.RE
.RS +4
.TP
5.
Finally it unblocks delivery of this signal, which results in the process
being terminated.
.RE
.SS "Process suspension signals"
.sp
.LP
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, \fBgl_handle_signal()\fR continues, and does the
following steps.
.RS +4
.TP
1.
It re-blocks delivery of the signal.
.RE
.RS +4
.TP
2.
It reinstates the signal handler of the signal to the one that was displaced
when its default disposition was substituted.
.RE
.RS +4
.TP
3.
For any of the GetLine objects that were in raw mode when
\fBgl_handle_signal()\fR was called, \fBgl_handle_signal()\fR then calls
\fBgl_raw_io()\fR, to resume entry of the input lines on those terminals.
.RE
.RS +4
.TP
4.
Finally, it restores the signal process mask to how it was when
\fBgl_handle_signal()\fR was called.
.RE
.sp
.LP
Note that the process is suspended or terminated using the original signal that
was caught, rather than using the uncatchable \fBSIGSTOP\fR and \fBSIGKILL\fR
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 \fBSIGPIPE\fR
signal, the program responded by sending itself a \fBSIGKILL\fR signal, and the
shell then printed out the provocative statement, "Killed!".
.SS "Interrupting The Event Loop"
.sp
.LP
If a signal is caught and handled when the application's event loop is waiting
in \fBselect()\fR or \fBpoll()\fR, these functions will be aborted with
\fBerrno\fR set to \fBEINTR\fR. When this happens the event loop should call
\fBgl_pending_io()\fR before calling \fBselect()\fR or \fBpoll()\fR again. It
should then arrange for \fBselect()\fR or \fBpoll()\fR to wait for the type of
I/O that \fBgl_pending_io()\fR reports. This is necessary because any signal
handler that calls \fBgl_handle_signal()\fR will frequently change the type of
I/O that \fBgl_get_line()\fR is waiting for.
.sp
.LP
If a signal arrives between the statements that configure the arguments of
\fBselect()\fR or \fBpoll()\fR 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.
.RS +4
.TP
1.
Block all of the signals that \fBgl_get_line()\fR catches, by passing the
signal set returned by \fBgl_list_signals()\fR to \fBsigprocmask\fR(2).
.RE
.RS +4
.TP
2.
Call \fBgl_pending_io()\fR and set up the arguments of \fBselect()\fR or
\fBpoll()\fR accordingly.
.RE
.RS +4
.TP
3.
Call \fBsigsetjmp\fR(3C) with a non-zero \fIsavemask\fR argument.
.RE
.RS +4
.TP
4.
Initially this \fBsigsetjmp()\fR statement will return zero, indicating that
control is not resuming there after a matching call to \fBsiglongjmp\fR(3C).
.RE
.RS +4
.TP
5.
Replace all of the handlers of the signals that \fBgl_get_line()\fR 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 \fBsiglongjmp()\fR
with a non-zero \fIval\fR argument, to return execution to the above
\fBsigsetjmp()\fR statement. Registering these signal handlers can conveniently
be done using the \fBgl_tty_signals()\fR function.
.RE
.RS +4
.TP
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.
.RE
.RS +4
.TP
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.
.RE
.RS +4
.TP
8.
Now call \fBselect()\fR or \fBpoll()\fR.
.RE
.RS +4
.TP
9.
When select returns, again block the signals that were unblocked in step 7.
.sp
If a signal is arrived any time during the above steps, our signal handler will
be triggered and cause control to return to the \fBsigsetjmp()\fR statement,
where this time, \fBsigsetjmp()\fR 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
\fBsigsetjmp()\fR returns, regardless of why it returned, the process signal
mask is returned to how it was when \fBsigsetjmp()\fR was called. Thus the
following statements are always executed with all of our signals blocked.
.RE
.RS +4
.TP
10.
Reinstate the signal handlers that were displaced in step 5.
.RE
.RS +4
.TP
11.
Check wether a signal was caught, by checking the file-scope variable that
the signal handler records signal numbers in.
.RE
.RS +4
.TP
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.
.RE
.RS +4
.TP
13.
Unblock all of the signals that were blocked in step 7.
.RE
.SS "Signals Caught By \fBgl_get_line()\fR"
.sp
.LP
Since the application is expected to handle signals in non-blocking server
mode, \fBgl_get_line()\fR 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 \fBgl_get_line()\fR is being called, \fBgl_get_line()\fR
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, \fBgl_get_line()\fR
returns \fINULL\fR, and a following call to \fBgl_return_status()\fR returns
the enumerated value \fBGLR_SIGNAL\fR.
.SS "Aborting Line Input"
.sp
.LP
Often, rather than letting it terminate the process, applications respond to
the \fBSIGINT\fR user-interrupt signal by aborting the current input line. This
can be accomplished in non-blocking server-I/O mode by not calling
\fBgl_handle_signal()\fR when this signal is caught, but by calling instead the
\fBgl_abandon_line()\fR function. This function arranges that when
\fBgl_get_line()\fR 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.
.SS "Signal Safe Functions"
.sp
.LP
Provided that certain rules are followed, the \fBgl_normal_io()\fR,
\fBgl_raw_io()\fR, \fBgl_handle_signal()\fR, and \fBgl_abandon_line()\fR
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 \fBsigaction()\fR function to
register all signal handlers, and when doing this, use the \fIsa_mask\fR member
of the corresponding \fBsigaction\fR 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 \fBGetLine\fR object at the same time.
.sp
.LP
To prevent signal handlers from accessing a \fBGetLine\fR object while
\fBgl_get_line()\fR or any of its associated public functions are operating on
it, all public functions associated with \fBgl_get_line()\fR, including
\fBgl_get_line()\fR itself, temporarily block the delivery of signals when they
are accessing \fBGetLine\fR objects. Beware that the only signals that they
block are the signals that \fBgl_get_line()\fR 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 \fBgl_get_line()\fR. See \fBgl_trap_signal\fR(3TECLA).
.SS "Using Timeouts To Poll"
.sp
.LP
If instead of using \fBselect()\fR or \fBpoll()\fR to wait for I/O your
application needs only to get out of \fBgl_get_line()\fR periodically to
briefly do something else before returning to accept input from the user, use
the \fBgl_inactivity_timeout\fR(3TECLA) function in non-blocking server mode to
specify that a callback function that returns \fBGLTO_CONTINUE\fR should be
called whenever \fBgl_get_line()\fR has been waiting for I/O for more than a
specified amount of time. When this callback is triggered, \fBgl_get_line()\fR
will return \fINULL\fR and a following call to \fBgl_return_status()\fR will
return \fBGLR_BLOCKED\fR.
.sp
.LP
The \fBgl_get_line()\fR 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, \fBgl_get_line()\fR might not return for a while. There is no guarantee
that it will return in the time specified.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     Evolving
_
MT-Level        MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
\fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBpca_lookup_file\fR(3TECLA),
\fBattributes\fR(5), \fBtecla\fR(5)