'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
.TH SIGNAL 3UCB "Oct 30, 2007"
.SH NAME
signal \- simplified software signal facilities
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ...
#include <signal.h>

\fBvoid\fR (\fB*signal(\fR\fIsig\fR, \fIfunc\fR))()
\fBint\fR \fIsig\fR;
\fBvoid\fR (\fB*\fR\fIfunc\fR)();
.fi

.SH DESCRIPTION
.sp
.LP
\fBsignal()\fR is a simplified interface to the more general \fBsigvec\fR(3UCB)
facility.  Programs that use \fBsignal()\fR in preference to \fBsigvec()\fR are
more likely to be portable to all systems.
.sp
.LP
A signal is generated by some abnormal event, initiated by a user at a terminal
(quit, interrupt, stop), by a program error (bus error, etc.), by request of
another program (kill), or when a process is stopped because it wishes to
access its control terminal while in the background (see \fBtermio\fR(7I)).
Signals are optionally generated when a process resumes after being stopped,
when the status of child processes changes, or when input is ready at the
control terminal. Most signals cause termination of the receiving process if no
action is taken; some signals instead cause the process receiving them to be
stopped, or are simply discarded if the process has not requested otherwise.
Except for the \fBSIGKILL\fR and \fBSIGSTOP\fR signals, the \fBsignal()\fR call
allows signals either to be ignored or to interrupt to a specified location.
See \fBsigvec\fR(3UCB) for a complete list of the signals.
.sp
.LP
If \fIfunc\fR is \fBSIG_DFL\fR, the default action for signal \fIsig\fR is
reinstated; this default is termination (with a core image for starred signals)
except for signals marked with \(bu or a dagger. Signals marked with \(bu are
discarded if the action is \fBSIG_DFL\fR; signals marked with a dagger cause
the process to stop.  If \fIfunc\fR is \fBSIG_IGN\fR the signal is subsequently
ignored and pending instances of the signal are discarded. Otherwise, when the
signal occurs further occurrences of the signal are automatically blocked and
\fIfunc\fR is called.
.sp
.LP
A return from the function unblocks the handled signal and continues the
process at the point it was interrupted.
.sp
.LP
If a caught signal occurs during certain functions,  terminating the call
prematurely, the call is automatically restarted. In particular this can occur
during a \fBread\fR(2) or \fBwrite\fR(2) on a slow device (such as a terminal;
but not a file) and during a \fBwait\fR(3C).
.sp
.LP
The value of \fBsignal()\fR is the previous (or initial) value of \fIfunc\fR
for the particular signal.
.sp
.LP
After a \fBfork\fR(2) or \fBvfork\fR(2) the child inherits all signals.  An
\fBexec\fR(2) resets all caught signals to the default action; ignored signals
remain ignored.
.SH RETURN VALUES
.sp
.LP
The previous action is returned on a successful call. Otherwise,\fB\(mi1\fR is
returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
\fBsignal()\fR will fail and no action will take place if the following occurs:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
\fIsig\fR is not a valid signal number, or is \fBSIGKILL\fR or \fBSIGSTOP\fR.
.RE

.SH SEE ALSO
.sp
.LP
\fBkill\fR(1), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2),
\fBgetitimer\fR(2), \fBgetrlimit\fR(2), \fBkill\fR(2), \fBread\fR(2),
\fBsigaction\fR(2), \fBwrite\fR(2), \fBabort\fR(3C), \fBptrace\fR(3C),
\fBsetjmp\fR(3C), \fBsetjmp\fR(3UCB), \fBsigblock\fR(3UCB), \fBsignal\fR(3C),
\fBsignal.h\fR(3HEAD), \fBsigstack\fR(3UCB), \fBsigvec\fR(3UCB),
\fBwait\fR(3C), \fBwait\fR(3UCB), \fBtermio\fR(7I)
.SH NOTES
.sp
.LP
Use of these interfaces should be restricted to only applications written on
BSD platforms.  Use of these interfaces with any of the system libraries or in
multi-threaded applications is unsupported.
.sp
.LP
The handler routine \fIfunc\fR can be declared:
.sp
.in +2
.nf
void handler(signum) int signum;
.fi
.in -2

.sp
.LP
Here \fIsignum\fR is the signal number. See \fBsigvec\fR(3UCB) for more
information.