'\"macro stdmacro
.if n .pH g3.signal @(#)signal	40.7 of 9/18/89
.\" Copyright (c) 1988 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.
.\"
.nr X
.if \nX=0 .ds x} signal 3 "BSD Compatibility Package" "\&"
.if \nX=1 .ds x} signal 3 "BSD Compatibility Package"
.if \nX=2 .ds x} signal 3 "" "\&"
.if \nX=3 .ds x} signal "" "" "\&"
.TH \*(x}
.ie t .ds d \(dg
.el .ds d \z|+
.ie t .ds b \(bu
.el .ds b @
.SH NAME
\f4signal\f1 \- simplified software signal facilities
.SH SYNOPSIS
.nf
\f4cc \f1[ \f2flag\f1... ] \f2file\f1 ... \f4\-lucb\f1
.P
\f4#include <signal.h>\f1
.P
\f4void (\(**signal(sig, func))()\f1
\f4void (\(**func)();\f1
.fi
.SH DESCRIPTION
\f4signal\f1
is a simplified interface to the more general
\f4sigvec\f1(2)
facility.  Programs that use
\f4signal\f1
in preference to
\f4sigvec\f1
are more likely to be portable to all
systems.
.P
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 \f4termio\f1(4)].
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
\f4SIGKILL\fP
and
\f4SIGSTOP\fP
signals, the
\f4signal\f1
call allows signals either to be ignored
or to interrupt to a specified location.
The following is a list of all signals with
names as in the include file
\f4<signal.h>\f1:
.RS
.P
.nf
.ta \w'\f4SIGVTALRM \fP'u +\w'15*  'u
\f4SIGHUP\f1		hangup
\f4SIGINT\f1		interrupt
\f4SIGQUIT\f1	*	quit
\f4SIGILL\f1	*	illegal instruction
\f4SIGTRAP\f1	*	trace trap
\f4SIGABRT\f1	*	abort (generated by \f4abort\fP(3) routine)
\f4SIGEMT\f1	*	emulator trap
\f4SIGFPE\f1	*	arithmetic exception
\f4SIGKILL\f1		kill (cannot be caught, blocked, or ignored)
\f4SIGBUS\f1	*	bus error
\f4SIGSEGV\f1	*	segmentation violation
\f4SIGSYS\f1	*	bad argument to system call
\f4SIGPIPE\f1		write on a pipe or other socket with no one to read it
\f4SIGALRM\f1		alarm clock
\f4SIGTERM\f1		software termination signal
\f4SIGURG\f1	\*b	urgent condition present on socket
\f4SIGSTOP\f1	\*d	stop (cannot be caught, blocked, or ignored)
\f4SIGTSTP\f1	\*d	stop signal generated from keyboard
\f4SIGCONT\f1	\*b	continue after stop (cannot be blocked)
\f4SIGCHLD\f1	\*b	child status has changed
\f4SIGTTIN\f1	\*d	background read attempted from control terminal
\f4SIGTTOU\f1	\*d	background write attempted to control terminal
\f4SIGIO\f1	\*b	I/O is possible on a descriptor [see \f4fcntl\f1(2)]
\f4SIGXCPU\f1	*	cpu time limit exceeded [see \f4getrlimit\f1(2)
\f4SIGXFSZ\f1	*	file size limit exceeded [see \f4getrlimit\f1(2)
\f4SIGVTALRM\f1		virtual time alarm [see \f4getitimer\f1(2)
\f4SIGPROF\f1		profiling timer alarm [see \f4getitimer\f1(2)]
\f4SIGWINCH\f1	\*b	window changed [see \f4termio\f1(4)]
\f4SIGUSR1\f1		user-defined signal 1
\f4SIGUSR2\f1		user-defined signal 2
.fi
.RE
.P
The starred signals in the list above cause a core image
if not caught or ignored.
.P
If
.I func
is
\f4SIG_DFL\f1,
the default action for signal
.I sig
is reinstated; this default is termination
(with a core image for starred signals)
except for signals marked with \*b or \*d.
Signals marked with \*b are discarded if the action
is
\f4SIG_DFL\f1;
signals marked with \*d cause the process to stop.  If
.I func
is
\f4SIG_IGN\fP
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
.I func
is called.
.P
A return from the function unblocks
the handled signal and
continues the process at the point it was interrupted.
.P
If a caught signal occurs
during certain system calls, 
terminating the call prematurely, the call
is automatically restarted.
In particular this can occur
during a
\f4read\f1(2)
or
\f4write\f1(2)
on a slow device (such as a terminal; but not a file)
and during a
\f4wait\f1(2).
.P
The value of
\f4signal\f1
is the previous (or initial)
value of
.I func
for the particular signal.
.P
After a
\f4fork\f1(2)
or
\f4vfork\f1(2)
the child inherits all signals.  An
\f4execve\f1(2)
resets all caught signals to the default action;
ignored signals remain ignored.
.SH NOTES
The handler routine can be declared:
.RS
.P
.nf
.ft 4
void handler(sig, code, scp, addr)
int sig, code;
struct sigcontext \(**scp;
char \(**addr;
.ft 1
.fi
.RE
.P
Here
.I sig
is the signal number;
.I code
is a parameter of certain signals that provides additional detail;
.I scp
is a pointer to the
\f4sigcontext\f1
structure (defined in
\f4<signal.h>\f1),
used to restore the context from before the signal;
and
.I addr
is additional address information.
See
\f4sigvec\f1(2)
for more details.
.SH "RETURN VALUE"
The previous action is returned on a successful call.
Otherwise, \-1 is returned and
\f4errno\f1
is set to indicate the error.
.SH ERRORS
\f4signal\f1
will fail and no action will take place if one of the
following occur:
.TP 20
\f4EINVAL\fP
.I sig
is not a valid signal number,
or is
\f4SIGKILL\fP
or
\f4SIGSTOP\f1.
.SH "SEE ALSO"
\f4setjmp\fP(3),
\f4sigblock\fP(3),
\f4sigpause\fP(3),
\f4sigsetmask\fP(3),
\f4sigstack\fP(3),
\f4sigvec\fP(3),
\f4wait\fP(3)
.P
\f4execve\fP(2),
\f4fork\fP(2),
\f4getitimer\fP(2),
\f4getrlimit\fP(2),
\f4kill\fP(2),
\f4ptrace\fP(2),
\f4read\fP(2),
\f4sigaction\fP(2)
\f4wait\fP(2),
\f4write\fP(2),
\f4setjmp\fP(3C),
in the \f2Programmer's Reference Manual\f1.
.br
\f4kill\fP(1),
in the \f2User's Reference Manual\f1.
.br
\f4termio\fP(7)
in the \f2System Administrator's Reference Manual\f1.
