.\"	$NetBSD: signal.9,v 1.23 2010/04/29 16:31:11 jruoho Exp $
.\"
.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg and Jason R. Thorpe.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 29, 2010
.Dt SIGNAL 9
.Os
.Sh NAME
.Nm signal ,
.Nm siginit ,
.Nm sigactsinit ,
.Nm sigactsunshare ,
.Nm sigactsfree ,
.Nm execsigs ,
.Nm sigaction1 ,
.Nm sigprocmask1 ,
.Nm sigpending1 ,
.Nm sigsuspend1 ,
.Nm sigaltstack1 ,
.Nm pgsignal ,
.Nm kpgsignal ,
.Nm psignal ,
.Nm kpsignal ,
.Nm issignal ,
.Nm postsig ,
.Nm killproc ,
.Nm sigexit ,
.Nm trapsignal ,
.Nm sendsig ,
.Nm sigcode ,
.Nm sigtramp
.Nd software signal facilities
.Sh SYNOPSIS
.In sys/signal.h
.In sys/signalvar.h
.Ft void
.Fn siginit "struct proc *p"
.Ft void
.Fn sigactsinit "struct proc *pp" "int share"
.Ft void
.Fn sigactsunshare "struct proc *p"
.Ft void
.Fn sigactsfree "struct proc *p"
.Ft void
.Fn execsigs "struct proc *p"
.Ft int
.Fn sigaction1 "struct lwp *l" "int signum" "const struct sigaction *nsa" \
    "struct sigaction *osa" "void *tramp" "int vers"
.Ft int
.Fn sigprocmask1 "struct lwp *l" "int how" "const sigset_t *nss" \
    "sigset_t *oss"
.Ft void
.Fn sigpending1 "struct lwp *l" "sigset_t *ss"
.Ft int
.Fn sigsuspend1 "struct lwp *l" "const sigset_t *ss"
.Ft int
.Fn sigaltstack1 "struct lwp *l" "const struct sigaltstack *nss" \
    "struct sigaltstack *oss"
.Ft void
.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty"
.Ft void
.Fn kpgsignal "struct pgrp *pgrp" "ksiginfo_t *ks" "void *data" "int checkctty"
.Ft void
.Fn psignal "struct proc *p" "int signum"
.Ft void
.Fn kpsignal "struct proc *p" "ksiginfo_t *ks" "void *data"
.Ft int
.Fn issignal "struct lwp *l"
.Ft void
.Fn postsig "int signum"
.Ft void
.Fn killproc "struct proc *p" "const char *why"
.Ft void
.Fn sigexit "struct lwp *l" "int signum"
.Ft void
.Fn trapsignal "struct lwp *l" "const ksiginfo_t *ks"
.Ft void
.Fn sendsig "const ksiginfo_t *ks" "const sigset_t *mask"
.Sh DESCRIPTION
The system defines a set of signals that may be delivered to a process.
These functions implement the kernel portion of the signal facility.
.Pp
Signal numbers used throughout the kernel signal facilities should
always be within the range of
.Bq 1- Ns NSIG .
.Pp
Most of the kernel's signal infrastructure is implemented in
machine-independent code.
Machine-dependent code provides support for invoking a process's
signal handler, restoring context when the signal handler returns,
generating signals when hardware traps occur, triggering the delivery
of signals when a process is about to return from the kernel to userspace.
.Pp
The signal state for a process is contained in
.Fa struct sigctx .
This includes the list of signals with delivery pending,
information about the signal handler stack, the signal mask, and the
address of the signal trampoline.
.Pp
The registered signal handlers for a process are recorded in
.Fa struct sigacts .
This structure may be shared by multiple processes.
.Pp
The kernel's signal facilities are implemented by the following
functions:
.Bl -tag -width XXXXX
.It Fn siginit "p"
.Pp
This function initializes the signal state of
.Va proc0
to the system default.
This signal state is then inherited by
.Xr init 8
when it is started by the kernel.
.It Fn sigactsinit "pp" "share"
.Pp
This function creates an initial
.Fa struct sigacts
for the process
.Fa pp .
If the
.Fa share
argument is non-zero, then
.Fa pp
shares the
.Fa struct sigacts
by holding a reference.
Otherwise,
.Fa pp
receives a new
.Fa struct sigacts
which is copied from the parent.
.It Fn sigactsunshare "p"
.Pp
This function causes the process
.Fa p
to no longer share its
.Fa struct sigacts
The current state of the signal actions is maintained in the new copy.
.It Fn sigactsfree "p"
.Pp
This function decrements the reference count on the
.Fa struct sigacts
of process
.Fa p .
If the reference count reaches zero, the
.Fa struct sigacts
is freed.
.It Fn execsigs "p"
.Pp
This function is used to reset the signal state of the process
.Fa p
to the system defaults when the process execs a new program image.
.It Fn sigaction1 "l" "signum" "nsa" "osa" "tramp" "vers"
.Pp
This function implements the
.Xr sigaction 2
system call.
The
.Fa tramp
and
.Fa vers
arguments provide support for userspace signal trampolines.
Trampoline version 0 is reserved for the legacy kernel-provided
signal trampoline;
.Fa tramp
must be
.Dv NULL
in this case.
Otherwise,
.Fa vers
specifies the ABI of the trampoline specified by
.Fa tramp .
The signal trampoline ABI is machine-dependent, and must be coordinated
with the
.Fn sendsig
function.
.It Fn sigprocmask1 "l" "how" "nss" "oss"
.Pp
This function implements the
.Xr sigprocmask 2
system call.
.It Fn sigpending1 "l" "ss"
.Pp
This function implements the
.Xr sigpending 2
system call.
.It Fn sigsuspend1 "l" "ss"
.Pp
This function implements the
.Xr sigsuspend 2
system call.
.It Fn sigaltstack1 "l" "nss" "oss"
.Pp
This function implements the
.Xr sigaltstack 2
system call.
.It Fn pgsignal "pgrp" "signum" "checkctty"
.Pp
This is a wrapper function for
.Fn kpgsignal
which is described below.
.It Fn kpgsignal "pgrp" "ks" "data" "checkctty"
.Pp
Schedule the signal
.Fa ks-\*[Gt]ksi_signo
to be delivered to all members of the process group
.Fa pgrp .
If
.Fa checkctty
is non-zero, the signal is only sent to processes which have a
controlling terminal.
The
.Fa data
argument and the complete signal scheduling semantics are described in the
.Fn kpsignal
function below.
.It Fn trapsignal "l" "ks"
.Pp
Sends the signal
.Fa ks-\*[Gt]ksi_signo
caused by a hardware trap to the current process.
.\"
.\" XXX: Check for reality in 2010.
.\"
.\" This function is meant to be called by machine-dependent trap handling
.\" code, through the
.\" .Dv p-\*[Gt]p_emul-\*[Gt]e_trapsignal
.\" function pointer because some emulations define their own trapsignal
.\" functions that remap the signal information to what the emulation
.\" expects.
.It Fn psignal "p" "signum"
.Pp
This is a wrapper function for
.Fn kpsignal
which is described below.
.It Fn kpsignal "p" "ks" "data"
.Pp
Schedule the signal
.Fa ks-\*[Gt]ksi_signo
to be delivered to the process
.Fa p .
The
.Fa data
argument, if not
.Dv NULL ,
points to the file descriptor data that caused the
signal to be generated in the
.Li SIGIO
case.
.Pp
With a few exceptions noted below, the target process signal disposition is
updated and is marked as runnable, so further handling of the signal is done
in the context of the target process after a context switch; see
.Fn issignal
below.
Note that
.Fn kpsignal
does not by itself cause a context switch to happen.
.Pp
The target process is not marked as runnable in the following cases:
.Bl -bullet -offset indent
.It
The target process is sleeping uninterruptibly.
The signal will be noticed when the process returns from the system
call or trap.
.It
The target process is currently ignoring the signal.
.It
If a stop signal is sent to a sleeping process that takes the
default action
.Pq see Xr sigaction 2 ,
the process is stopped without awakening it.
.It
SIGCONT
restarts a stopped process
.Pq or puts them back to sleep
regardless of the signal action
.Pq e.g., blocked or ignored .
.El
.Pp
If the target process is being traced,
.Fn kpsignal
behaves as if the target process were taking the default action for
.Fa signum .
This allows the tracing process to be notified of the signal.
.It Fn issignal "l"
.Pp
This function determines which signal, if any,
is to be posted to the current process.
A signal is to be posted if:
.Bl -bullet -offset indent
.It
The signal has a handler provided by the program image.
.It
The signal should cause the process to dump core and/or terminate.
.It
The signal should interrupt the current system call.
.El
.Pp
Signals which cause the process to be stopped are handled within
.Fn issignal
directly.
.Pp
.Fn issignal
should be called by machine-dependent code when returning to
userspace from a system call or other trap or interrupt by
using the following code:
.Bd -literal -offset indent
while (signum = CURSIG(curproc))
	postsig(signum);
.Ed
.Pp
.It Fn postsig "signum"
.Pp
The
.Fn postsig
function is used to invoke the action for the signal
.Fa signum
in the current process.
If the default action of a signal is to terminate the process, and the
signal does not have a registered handler, the process exits using
.Fn sigexit ,
dumping a core image if necessary.
.It Fn killproc "p" "why"
.Pp
This function sends a SIGKILL signal to the specified process.
The message provided by
.Fa why
is sent to the system log and is also displayed on the process's
controlling terminal.
.It Fn sigexit "l" "signum"
.Pp
This function forces the current process to exit with the signal
.Fa signum ,
generating a core file if appropriate.
No checks are made for masked or caught signals; the process always exits.
.It Fn sendsig "ks" "mask"
.Pp
This function is provided by machine-dependent code, and is used to
invoke a signal handler for the current process.
.Fn sendsig
must prepare the registers and stack of the current process to
invoke the signal handler stored in the process's
.Fa struct sigacts .
This may include switching to an alternate signal
stack specified by the process.
The previous register, stack, and signal state are stored in a
.Fa ucontext_t ,
which is then copied out to the user's stack.
.Pp
The registers and stack must be set up to invoke the signal handler as
follows:
.Bd -literal -offset indent
(*handler)(int signum, siginfo_t *info, void *ctx)
.Ed
.Pp
where
.Fa signum
is the signal number,
.Fa info
contains additional signal specific information when
.Li SA_SIGINFO
is specified when setting up the signal handler.
.Fa ctx
is the pointer to
.Fa ucontext_t
on the user's stack.
The registers and stack must also arrange for the signal handler to
return to the signal trampoline.
The trampoline is then used to return to the code which was executing
when the signal was delivered using the
.Xr setcontext 2
system call.
.Pp
For performance reasons, it is recommended that
.Fn sendsig
arrange for the signal handler to be invoked directly on architectures
where it is convenient to do so.
In this case, the trampoline is used only for the signal return path.
If it is not feasible to directly invoke the signal handler, the
trampoline is also used to invoke the handler, performing any final
set up that was not possible for
.Fn sendsig
to perform.
.Pp
.Fn sendsig
must invoke the signal trampoline with the correct ABI.
The ABI of the signal trampoline is specified on a per-signal basis in the
.Fn sigacts
structure for the process.
Trampoline version 0 is reserved for the legacy kernel-provided,
on-stack signal trampoline.
All other trampoline versions indicate a specific trampoline ABI.
This ABI is coordinated with machine-dependent code in the system
C library.
.El
.Ss SIGNAL TRAMPOLINE
The signal trampoline is a special piece of code which provides
support for invoking the signal handlers for a process.
The trampoline is used to return from the signal handler back to the
code which was executing when the signal was delivered, and is also used
to invoke the handler itself on architectures where it is not feasible to
have the kernel invoke the handler directly.
.Pp
In traditional
.Ux
systems, the signal trampoline, also referred to as the
.Dq sigcode ,
is provided by the kernel and copied to the top of the user's
stack when a new process is created or a new program image is
exec'd.
Starting in
.Nx 2.0 ,
the signal trampoline is provided by the system C library.
This allows for more flexibility when the signal facility is extended,
makes dealing with signals easier in debuggers, such as
.Xr gdb 1 ,
and may also enhance system security by allowing the kernel to
disallow execution of code on the stack.
.Pp
The signal trampoline is specified on a per-signal basis.
The correct trampoline is selected automatically by the C library
when a signal handler is registered by a process.
.Pp
Signal trampolines have a special naming convention which enables
debuggers to determine the characteristics of the signal handler
and its arguments.
Trampoline functions are named like so:
.Bd -literal -offset indent
__sigtramp_\*[Lt]flavor\*[Gt]_\*[Lt]version\*[Gt]
.Ed
.Pp
where:
.Bl -tag -width versionXX
.It Aq flavor
The flavor of the signal handler.
The following flavors are valid:
.Bl -tag -width sigcontextXX
.It sigcontext
Specifies a traditional BSD-style (deprecated) signal handler with the
following signature:
.Bd -literal
void (*handler)(int signum,
	int code,
	struct sigcontext *scp);
.Ed
.It siginfo
Specifies a POSIX-style signal handler with the following signature:
.Bd -literal
void (*handler)(int signum,
	siginfo_t *si,
	void *uc);
.Ed
.Pp
Note: sigcontext style signal handlers are deprecated, and retained only
for compatibility with older binaries.
.El
.It Aq version
Specifies the ABI version of the signal trampoline.
The trampoline ABI is coordinated with the machine-dependent kernel
.Fn sendsig
function.
The trampoline version needs to be unique even across different trampoline
flavors, in order to simplify trampoline selection in the kernel.
.El
.Pp
The following is an example if a signal trampoline name which indicates
that the trampoline is used for traditional BSD-style signal handlers
and implements version 1 of the signal trampoline ABI:
.Bd -literal -offset indent
__sigtramp_sigcontext_1
.Ed
.Pp
The current signal trampoline is:
.Bd -literal -offset indent
__sigtramp_siginfo_2
.Ed
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr signal 7 ,
.Xr condvar 9