move fakcu, perror, remove to stdio; fakcu goes away

[unix-history] / usr / src / lib / libc / gen / signal.3

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)signal.3	6.5 (Berkeley) %G%
.\"
.TH SIGNAL 3C ""
.UC 4
.ie t .ds d \(dg
.el .ds d \z'|+'
.ie t .ds b \(bu
.el .ds b @
.SH NAME
signal \- simplified software signal facilities
.SH SYNOPSIS
.nf
.B #include <signal.h>
.PP
.B void (*signal(sig, func))()
.B void (*func)();
.fi
.SH DESCRIPTION
.I Signal
is a simplified interface to the more general
.IR sigaction (2)
facility.
.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, the
.I signal
call allows signals either to be ignored
or to cause an interrupt to a specified location.
The following is a list of all signals with
names as in the include file
.RI < signal.h >:
.LP
.nf
.ta \w'SIGVTALRM 'u +\w'15*  'u
SIGHUP	1	hangup
SIGINT	2	interrupt
SIGQUIT	3*	quit
SIGILL	4*	illegal instruction
SIGTRAP	5*	trace trap
SIGABRT	6*	\fIabort\fP() call (formerly SIGIOT)
SIGEMT	7*	EMT instruction
SIGFPE	8*	floating point exception
SIGKILL	9	kill (cannot be caught 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
SIGURG	16\*b	urgent condition present on socket
SIGSTOP	17\*d	stop (cannot be caught 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
SIGIO	23\*b	i/o is possible on a descriptor (see \fIfcntl\fP(2))
SIGXCPU	24	cpu time limit exceeded (see \fIsetrlimit\fP(2))
SIGXFSZ	25	file size limit exceeded (see \fIsetrlimit\fP(2))
SIGVTALRM	26	virtual time alarm (see \fIsetitimer\fP(2))
SIGPROF	27	profiling timer alarm (see \fIsetitimer\fP(2))
SIGWINCH	28\*b	Window size change
SIGINFO	29\*b	status request from keyboard
SIGUSR1	30	User defined signal 1
SIGUSR2	31	User defined signal 2
.fi
.PP
The starred signals in the list above cause a core image
if not caught 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_IGN 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.
.PP
A return from the function unblocks
the handled signal and
continues the process at the point it was interrupted.
\fBUnlike previous signal facilities, the handler \fIfunc\fP
remains installed after a signal has been delivered.\fP
.PP
If a caught signal occurs
during certain system calls, causing
the call to terminate prematurely, the call
is automatically restarted
(the handler is installed using the SA_RESTART flag with
.IR sigaction (2)).
The affected system calls include
.IR read (2),
.IR write (2),
.IR sendto (2),
.IR recvfrom (2),
.IR sendmsg (2)
and
.IR recvmsg (2)
on a communications channel or a slow device (such as a terminal,
but not a regular file)
and during a
.IR wait (2)
or
.IR ioctl (2).
However, calls that have already committed are not restarted,
but instead return a partial success (for example, a short read count).
.PP
The value of
.I signal
is the previous (or initial)
value of
.I func
for the particular signal.
.PP
After a
.IR fork (2)
or
.IR vfork (2)
the child inherits
all signals.
.IR  Execve (2)
resets all caught signals to the default action;
ignored signals remain ignored.
.SH "RETURN VALUE
The previous action is returned on a successful call.
Otherwise, \-1 is returned and 
.I errno
is set to indicate the error.
.SH ERRORS
.I Signal
will fail and no action will take place if one of the
following occur:
.TP 15
[EINVAL]
.I Sig
is not a valid signal number.
.TP 15
[EINVAL]
An attempt is made to ignore or supply a handler for SIGKILL
or SIGSTOP.
.SH "SEE ALSO"
kill(1), ptrace(2), kill(2),
sigaction(2), sigprocmask(2), sigsuspend(2),
sigstack(2), setjmp(3), tty(4)
.SH "NOTES  (VAX-11)"
The handler routine can be declared:
.PP
    void handler(sig, code, scp)
.PP
Here
.I sig
is the signal number, into which the hardware faults and traps are
mapped as defined below.  Code is a parameter which is either a constant
as given below or, for compatibility mode faults, the code provided by
the hardware. 
.I Scp
is a pointer to the
.I "struct sigcontext"
used by the system to restore the process context from before
the signal.
Compatibility mode faults are distinguished from the
other SIGILL traps by having PSL_CM set in the psl.
.PP
The following defines the mapping of hardware traps to signals
and codes.  All of these symbols are defined in
.RI < 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