<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE> S-Lang Library C Programmer's Guide, V1.4.0: Signal Functions</TITLE>
<LINK HREF="cslang-7.html" REL=next>
<LINK HREF="cslang-5.html" REL=previous>
<LINK HREF="cslang.html#toc6" REL=contents>
</HEAD>
<BODY>
<A HREF="cslang-7.html">Next</A>
<A HREF="cslang-5.html">Previous</A>
<A HREF="cslang.html#toc6">Contents</A>
<HR>
<H2><A NAME="s6">6. Signal Functions</A></H2>

<P> 
<P>Almost all non-trivial programs must worry about signals.  This is
especially true for programs that use the <B>S-Lang</B> terminal
input/output and screen management routines.  Unfortunately, there is
no fixed way to handle signals; otherwise, the Unix kernel would take
care of all issues regarding signals and the application programmer
would never have to worry about them.  For this reason, none of the
routines in the <B>S-Lang</B> library catch signals; however, some of the
routines block the delivery of signals during crucial moments.  It is
up to the application programmer to install handlers for the various
signals of interest.
<P>For the interpreter, the most important signal to worry about is
<CODE>SIGINT</CODE>.  This signal is usually generated when the user presses
<CODE>Ctrl-C</CODE> at the keyboard.  The interpreter checks the value of the
<CODE>SLang_Error</CODE> variable to determine whether or not it should abort the
interpreting process and return control back to the application.
This means that if <CODE>SIGINT</CODE> is to be used to abort the interpreter, a
signal handler for <CODE>SIGINT</CODE> should be installed.  The handler should
set the value of <CODE>SLang_Error</CODE> to <CODE>SL_USER_BREAK</CODE>.
<P>Applications that use the <CODE>tty</CODE> <CODE>getkey</CODE> routines or the screen
management routines must worry about about signals such as:
<BLOCKQUOTE><CODE>
<PRE>
     SIGINT                interrupt
     SIGTSTP               stop
     SIGQUIT               quit
     SIGTTOU               background write
     SIGTTIN               background read
     SIGWINCH              window resize
</PRE>
</CODE></BLOCKQUOTE>

It is important that handlers be established for these signals while
the either the <CODE>SLsmg</CODE> routines or the <CODE>getkey</CODE> routines are
initialized.  The <CODE>SLang_init_tty</CODE>, <CODE>SLang_reset_tty</CODE>,
<CODE>SLsmg_init_smg</CODE>, and <CODE>SLsmg_reset_smg</CODE> functions block these
signals from occuring while they are being called.
<P>Since a signal can be delivered at any time, it is important for the
signal handler to call only functions that can be called from a
signal handler.  This usually means that such function must be
re-entrant. In particular, the <CODE>SLsmg</CODE> routines are <EM>not</EM>
re-entrant; hence, they should not be called when a signal is being
processed unless the application can ensure that the signal was not
delivered while an <CODE>SLsmg</CODE> function was called.  This statement
applies to many other functions such as <CODE>malloc</CODE>, or, more
generally, any function that calls <CODE>malloc</CODE>.  The upshot is that
the signal handler should not attempt to do too much except set a
global variable for the application to look at while not in a signal
handler.
<P>The <B>S-Lang</B> library provides two functions for blocking and unblocking the
above signals:
<BLOCKQUOTE><CODE>
<PRE>
    int SLsig_block_signals (void);
    int SLsig_unblock_signals (void);
</PRE>
</CODE></BLOCKQUOTE>

It should be noted that for every call to <CODE>SLsig_block_signals</CODE>, a
corresponding call should be made to <CODE>SLsig_unblock_signals</CODE>, e.g.,
<BLOCKQUOTE><CODE>
<PRE>
    void update_screen ()
    {
       SLsig_block_signals ();
       
       /* Call SLsmg functions */
           .
           .
       SLsig_unblock_signals ();
    }
</PRE>
</CODE></BLOCKQUOTE>

See <CODE>demo/pager.c</CODE> for examples.
<P>
<P>
<P>
<HR>
<A HREF="cslang-7.html">Next</A>
<A HREF="cslang-5.html">Previous</A>
<A HREF="cslang.html#toc6">Contents</A>
</BODY>
</HTML>
