2.9BSD/usr/man/man2/sigsys.2j

.TH SIGSYS 2J
.UC
.ie t .ds d \(dg
.el .ds d \z'|+'
.ie t .ds b \(bu
.el .ds b @
.SH NAME
sigsys \- catch or ignore signals
.SH SYNOPSIS
.nf
.B #include <signal.h>
.PP
.B (*sigsys(sig, func))()
.B void (*func)();
.BI "int (*func)();" " (if void is not supported)"
.PP
.B cc ... \-ljobs
.fi
.SH DESCRIPTION
.IR N.B. :
The system currently supports two signal implementations.
The one described in
.IR signal (2)
is standard in version 7 UNIX systems,
and retained for backward compatibility
as it is different
in a number of ways.
The one described here (with the interface in
.IR sigset (3J))
provides for the needs of the job control mechanisms (see
.IR intro (3J))
used by
.IR csh (1),
and corrects the bugs in the standard implementation of signals,
allowing programs which process interrupts to be written reliably.
.PP
The routine
.I sigsys
is not normally called directly; rather the routines of
.IR sigset (3J)
should be used.
These routines are kept in the ``jobs'' library, accessible by
giving the loader option
.B \-ljobs.
The features described here are less portable then those of
.IR signal (2)
and should not be used in programs which are
to be moved to other versions of UNIX.
.PP
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
.IR tty (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 SIGKILL and SIGSTOP
signals which cannot be blocked, the
.I sigsys
call allows signals either to be ignored,
held until a later time (protecting critical sections in the process),
or to cause an interrupt to a specified location.
Here is the list of all signals with names as in the include file.
.LP
.nf
.ta \w'SIGMMMM 'u +\w'15*  'u
SIGHUP	1	hangup
SIGINT	2	interrupt
SIGQUIT	3*	quit
SIGILL	4*	illegal instruction (not reset when caught)
SIGTRAP	5*	trace trap (not reset when caught)
SIGIOT	6*	IOT instruction
SIGEMT	7*	EMT instruction
SIGFPE	8*	floating point exception
SIGKILL	9	kill (cannot be caught, held or ignored)
SIGBUS	10*	bus error
SIGSEGV	11*	segmentation violation
SIGSYS	12*	bad argument to system call
SIGPIPE	13	write on a pipe with no one to read it
SIGALRM	14	alarm clock
SIGTERM	15	software termination signal
	16	unassigned
SIGSTOP	17\*d	stop (cannot be caught, held or ignored)
SIGTSTP	18\*d	stop signal generated from keyboard
SIGCONT	19\*b	continue after stop
SIGCHLD	20\*b	child status has changed
SIGTTIN	21\*d	background read attempted from control terminal
SIGTTOU	22\*d	background write attempted to control terminal
SIGTINT	23\*b	input record is available at control terminal
SIGXCPU	24	cpu time limit exceeded (see \fIvlimit\fP\|(2)) (\fIVAX-11 only\fP)
SIGXFSZ	25	file size limit exceeded (see \fIvlimit\fP\|(2)) (\fIVAX-11 only\fP)
.fi
.PP
The starred signals in the list above cause a core image
if not caught, held or ignored.
.PP
If
.I func
is SIG_DFL, 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 SIG_DFL; signals marked
with \*d cause the process to stop.
If
.I func
is SIG_HOLD
the signal is remembered if it occurs, but not presented to the process;
it may be presented later if the process changes the action for the signal.
If
.I func
is SIG_IGN the signal is subsequently ignored,
and pending instances of the signal are discarded (i.e. if the
action was previously SIG_HOLD.)
Otherwise
when the signal occurs
.I func
will be called.
.PP
A return from the function will
continue the process at the point it was interrupted.
Except as indicated,
a signal, set with
.I sigsys,
is reset to SIG_DFL after being caught.  However by
specifying DEFERSIG(func) as the last argument to
.I sigsys,
one causes the action to be set to
SIG_HOLD before the interrupt is taken, so that recursive instances
of the signal cannot occur during handling of the signal.
.PP
When a caught signal occurs
during certain system calls, the call terminates prematurely.
In particular this can occur
during a
.I read
or
.IR write (2)
on a slow device (like a terminal; but not a file)
and during a
.I pause
or
.IR wait (2).
When a signal occurs
during one of these calls,
the saved user status
is arranged in such a way that,
when return from the
signal-catching takes place, it will appear that the
system call returned an error status.
The user's program may then, if it wishes,
re-execute the call.
.I Read
and
.I write
calls which have done no I/O,
.IR ioctl s
blocked with SIGTTOU,
and
.I wait2
or
.I wait3
calls are restarted.
.PP
The value of
.I sigsys
is the previous (or initial)
value of
.I func
for the particular signal.
.PP
The system provides two other functions by oring bits into the
signal number:
SIGDOPAUSE causes the process to
.I pause
after changing the signal action.  It can be used to atomically
re-enable a held signal which was being processed and wait for
another instance of the signal.
SIGDORTI causes the system to simulate an
.I rei
instruction
clearing the mark the system placed on the stack at the point of
interrupt before checking for further signals to be presented due
to the specified change in signal actions.  This allows a
signal package such as
.IR sigset (3J)
to dismiss from interrupts cleanly removing the old state from
the stack before another instance of the interrupt is presented.
.PP
After a
.IR fork (2)
or
.IR vfork (2)
the child inherits
all signals.
.IR  Exec (2)
resets all
caught signals to default action; held signals remain held
and ignored signals remain ignored.
.SH RETURN VALUE
The value BADSIG is returned if the
given signal is out of range.
.SH ERRORS
.I Sigsys
will fail if:
.TP 20
[EINVAL]
.I Sig
is an illegal signal number, including SIGKILL and SIGSTOP.
.SH "SEE ALSO"
kill(1), kill(2), ptrace(2), intro(3J), sigset(3J), setjmp(3), tty(4)
.SH BUGS
The job control facilities are not available in standard version 7 UNIX.
These facilities are still under development and may change in future
releases of the system as better inter-process communication facilities
and support for virtual terminals become available.  The options and
specifications of this facility and the system calls supporting it
are thus subject to change.
.PP
Since only one signal action can be changed at a time, it is not
possible to get the effect of SIGDOPAUSE for more than one signal
at a time.
.PP
The traps (listed below) should be distinguishable by extra arguments
to the signal handler, and all hardware supplied parameters should
be made available to the signal routine.
.SH "ASSEMBLER (PDP-11)"
(signal = 48.)
.br
.B sys  signal; sig; label
.br
(old label in r0)
.PP
If
.I label
is 0,
default action is reinstated.
If
.I label
is 1, the signal is ignored.
If
.I label
is 3, the signal is held.
Any other even
.I label
specifies an address in the process
where an interrupt is simulated.
If label is otherwise odd, the signal is sent to the function
whose address is the label with the low bit cleared
with the action set to SIG_HOLD.
(Thus DEFERSIG is indicated by the low bit of a signal catch address.
An RTI or RTT instruction will return from the
interrupt.)
.SH "NOTES (VAX-11)"
The handler routine can be declared:
.PP
    handler(signo, param, xx, pc, psl)
.PP
Here
.I signo
is the signal name, into which the hardware faults and traps are
mapped as defined below.  Param is the parameter which is either a constant
as given below or, for compatibility mode faults, the code provided by
the hardware.  Compatibility mode faults are distinguished from the
other SIGILL traps by having PSL_CM set in the psl.
.PP
The routine is actually called with only 3 parameters specified in
the \fIcalls\fP or \fIcallg\fP instruction.  After return from
the signal handler the \fIpc\fP and \fIpsl\fP are popped off of the
stack with an \fIrei\fP, so they act as ``value-result'' parameters
unlike normal C value parameters.
.PP
The following defines the mapping of hardware traps to signals
and codes.  All of these symbols are defined in <signal.h>:
.LP
.ta \w'     Floating/decimal divide by zero   'u +\w'15*  'u +8n
.nf
   Hardware condition	Signal	Code

Arithmetic traps:
   Integer overflow	SIGFPE	FPE_INTOVF_TRAP
   Integer division by zero	SIGFPE	FPE_INTDIV_TRAP
   Floating overflow trap	SIGFPE	FPE_FLTOVF_TRAP
   Floating/decimal division by zero	SIGFPE	FPE_FLTDIV_TRAP
   Floating underflow trap	SIGFPE	FPE_FLTUND_TRAP
   Decimal overflow trap	SIGFPE	FPE_DECOVF_TRAP
   Subscript-range	SIGFPE	FPE_SUBRNG_TRAP
   Floating overflow fault	SIGFPE	FPE_FLTOVF_FAULT
   Floating divide by zero fault	SIGFPE	FPE_FLTDIV_FAULT
   Floating underflow fault	SIGFPE	FPE_FLTUND_FAULT
Length access control	SIGSEGV
Protection violation	SIGBUS
Reserved instruction	SIGILL	ILL_RESAD_FAULT
Customer-reserved instr.	SIGEMT
Reserved operand	SIGILL	ILL_PRIVIN_FAULT
Reserved addressing	SIGILL	ILL_RESOP_FAULT
Trace pending	SIGTRAP
Bpt instruction	SIGTRAP
Compatibility-mode	SIGILL	hardware supplied code
Chme	SIGSEGV
Chms	SIGSEGV
Chmu	SIGSEGV
.fi