<refentry id="signal">
<refnamediv>
<refname>Signal</refname>
<refpurpose>catch or ignore interrupts</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;signal.h&gt;

typedef int (*sighandler_t)(int);
</funcsynopsisinfo>
<funcprototype>
  <funcdef>sighandler_t <function>signal</function></funcdef>
  <paramdef>int <parameter>interrupt</parameter></paramdef>
  <paramdef>sighandler_t <parameter>address</parameter></paramdef>

</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
This call is a comprehensive method of catching or ignoring
signals sent to the current process. Notice that "kill()" does
the sending of signals, and "signal()" does the catching.
</para>
<para>
Normally, a signal sent to a process causes it to terminate
with the status of the signal. If, in advance of the
anticipated signal, this system call is used, the program has
the choice of ignoring the signal or designating a function to
be executed when it is received. Different functions may be
designated for different signals.
</para>
<para>
The values for "address" have the following meanings:
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.7in"/>
<colspec colwidth="3in"/>
<tbody>
<row>
<entry>0</entry>
<entry>reset to the default i.e. abort when received.</entry>
</row>
<row>
<entry>1</entry>
<entry>ignore; this will apply until reset to another value.</entry>
</row>
<row>
<entry>Otherwise</entry>
<entry>taken to be the address of a C function which
is to be executed on receipt of the signal.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
If the latter case is chosen, when the signal is received by
the process the "address" is reset to 0, the default, before
the function is executed. This means that if the next signal
received should be caught then another call to "signal()"
should be made immediately. This is normally the first action
taken by the "interrupt" function. The function may access the
signal number which caused its execution by looking at its
argument. On completion of this function the program resumes
at the point at which is was "interrupted" by the signal.
</para>
<para>
An example should help to clarify all this. Suppose a program
needs to create a temporary file which should be deleted before
exiting. The body of the program might contain fragments like
this:
<programlisting>
pn  =  creat("temp",3);          /*  create  a temporary file */
signal(2,intrupt);               /*   ensure   tidying   up   */
signal(3,intrupt);
write(pn,string,count);
close(pn);                       /* finished writing */
unlink("temp");                  /* delete it */
exit(0);                         /* normal exit */
</programlisting>
The call to "signal()" will ensure that if a keyboard or quit
signal is received then the function "intrupt()" will be
executed and this might be written:
<programlisting>
intrupt(sig)
{
close(pn);                 /* close it if open */
unlink("temp");            /* delete it */
exit(sig);                 /* received signal er exit status */
}
</programlisting>
</para>
<para>
In this case, as the function will be exiting before another
signal is received, it is unnecessary to call "signal()" again
to reset its pointer. Note that either the function
"intrupt()" should appear in the source code before the call to
"signal()", or it should be pre-declared.
</para>
<para>
The signals used by OS-9 are defined in the header file as
follows:
</para>
<programlisting>
/* OS-9 signals */
#define        SIGKILL 0  /* system abort (cannot be caught or ignored)*/
#define        SIGWAKE 1    /* wake up */
#define        SIGQUIT 2    /* keyboard abort */
#define        SIGINT  3    /* keyboard interrupt */

/* special addresses */
#define        SIG_DFL 0    /* reset to default */
#define        SIG_IGN 1    /* ignore */
</programlisting>
<para>
Please note that there is another method of trapping signals,
namely "intercept()" (q.v.). However, since "signal()" and
"intercept()" are mutually incompatible, calls to both of them
must not appear in the same program. The link-loader will
preven the creation of an executable program in which both are
called by aborting with an "entry name clash" error for
"_sigint".
</para>
</refsect1>

<refsect1><title>See Also</title>
<para>
<link linkend="intercept">intercept()</link>,
OS-9 shell command "kill",
<link linkend="kill">kill()</link>
</para>
</refsect1>

</refentry>