561 lines
17 KiB
Groff
561 lines
17 KiB
Groff
.\" $NetBSD: signal.9,v 1.10 2004/01/08 09:14:35 wiz 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 January 7, 2004
|
|
.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 gsignal ,
|
|
.Nm pgsignal ,
|
|
.Nm psignal ,
|
|
.Nm sched_psignal ,
|
|
.Nm issignal ,
|
|
.Nm postsig ,
|
|
.Nm killproc ,
|
|
.Nm sigexit ,
|
|
.Nm sigmasked ,
|
|
.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 *np" "struct proc *pp" "int share"
|
|
.Ft void
|
|
.Fn sigactsunsuare "struct proc *p"
|
|
.Ft void
|
|
.Fn sigactsfree "struct proc *p"
|
|
.Ft void
|
|
.Fn execsigs "struct proc *p"
|
|
.Ft int
|
|
.Fn sigaction1 "struct proc *p" "int signum" "const struct sigaction *nsa" \
|
|
"struct sigaction *osa" "void *tramp" "int vers"
|
|
.Ft int
|
|
.Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \
|
|
"sigset_t *oss"
|
|
.Ft void
|
|
.Fn sigpending1 "struct proc *p" "sigset_t *ss"
|
|
.Ft int
|
|
.Fn sigsuspend1 "struct proc *p" "const sigset_t *ss"
|
|
.Ft int
|
|
.Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \
|
|
"struct sigaltstack *oss"
|
|
.Ft void
|
|
.Fn gsignal "int pgid" "int signum"
|
|
.Ft void
|
|
.Fn kgsignal "int pgid" "ksiginfo_t *ks" "void *data"
|
|
.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 void
|
|
.Fn sched_psignal "struct proc *p" "int signum"
|
|
.Ft int
|
|
.Fn issignal "struct proc *p"
|
|
.Ft void
|
|
.Fn postsig "int signum"
|
|
.Ft void
|
|
.Fn killproc "struct proc *p" "const char *why"
|
|
.Ft void
|
|
.Fn sigexit "struct proc *p" "int signum"
|
|
.Ft int
|
|
.Fn sigmasked "struct proc *p" "int signum"
|
|
.Ft void
|
|
.Fn trapsignal "struct proc *p" "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 void Fn siginit "struct proc *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 void Fn sigactsinit "struct proc *np" "struct proc *pp" "int share"
|
|
.Pp
|
|
This function creates an initial
|
|
.Fa struct sigacts
|
|
for the process
|
|
.Fa np .
|
|
If the
|
|
.Fa share
|
|
argument is non-zero, then
|
|
.Fa np
|
|
shares the
|
|
.Fa struct sigacts
|
|
with the process
|
|
.Fa pp .
|
|
Otherwise,
|
|
.Fa np
|
|
receives a new
|
|
.Fa struct sigacts
|
|
which is copied from
|
|
.Fa pp
|
|
if
|
|
.No non- Ns Dv NULL .
|
|
.It void Fn sigactsunshare "struct proc *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 void Fn sigactsfree "struct proc *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 void Fn execsigs "struct proc *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 int Fn sigaction1 "struct proc *p" "int signum" \
|
|
"const struct sigaction *nsa" "struct sigaction *osa" \
|
|
"void *tramp" "int 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 int Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \
|
|
"sigset_t *oss"
|
|
.Pp
|
|
This function implements the
|
|
.Xr sigprocmask 2
|
|
system call.
|
|
.It void Fn sigpending1 "struct proc *p" "sigset_t *ss"
|
|
.Pp
|
|
This function implements the
|
|
.Xr sigpending 2
|
|
system call.
|
|
.It int Fn sigsuspend1 "struct proc *p" "const sigset_t *ss"
|
|
.Pp
|
|
This function implements the
|
|
.Xr sigsuspend 2
|
|
system call.
|
|
.It int Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \
|
|
"struct sigaltstack *oss"
|
|
.Pp
|
|
This function implements the
|
|
.Xr sigaltstack 2
|
|
system call.
|
|
.It void Fn gsignal "int pgid" "int signum"
|
|
.Pp
|
|
This is a wrapper function for
|
|
.Fn kgsignal
|
|
which is described below.
|
|
.It void Fn kgsignal "int pgid" "ksiginfo_t *ks" "void *data"
|
|
.Pp
|
|
Schedule the signal
|
|
.Fa ks-\*[Gt]ksi_signo
|
|
to be delivered to all members of the process group specified by
|
|
.Fa pgid .
|
|
The
|
|
.Fa data
|
|
argument and the complete signal scheduling semantics are described in the
|
|
.Fn kpsignal
|
|
function below.
|
|
below for a complete description of the signal scheduling semantics.
|
|
.It void Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty"
|
|
.Pp
|
|
This is a wrapper function for
|
|
.Fn kpgsignal
|
|
which is described below.
|
|
.It void Fn kpgsignal "struct pgrp *pgrp" "ksiginfo_t *ks" "void *data" "int 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 void Fn trapsignal "struct proc *p" "const ksiginfo_t *ks"
|
|
.Pp
|
|
Sends the signal
|
|
.Fa ks-\*[Gt]ksi_signo
|
|
caused by a hardware trap to the process
|
|
.Fa p .
|
|
This function is meant to be called by machine-dependent trap handling
|
|
code, through the
|
|
.Dv p->p_emul->e_trapsignal
|
|
function pointer because some emulations define their own trapsignal
|
|
functions that remap the signal information to what the emulation
|
|
expects.
|
|
.It void Fn psignal "struct proc *p" "int signum"
|
|
.Pp
|
|
This is a wrapper function for
|
|
.Fn kpgsignal
|
|
which is described below.
|
|
.It void Fn kpsignal "struct proc *p" "ksiginfo_t *ks" "void *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 void Fn sched_psignal "struct proc *p" "int signum"
|
|
.Pp
|
|
An alternate version of
|
|
.Fn kpsignal
|
|
which is intended for use by code which holds the scheduler lock.
|
|
.It int Fn issignal "struct proc *p"
|
|
.Pp
|
|
This function determines which signal, if any, is to be posted to
|
|
the process
|
|
.Fa p .
|
|
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 void Fn postsig "int 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 void Fn killproc "struct proc *p" "const char *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 void Fn sigexit "struct proc *p" "int signum"
|
|
.Pp
|
|
This function forces the process
|
|
.Fa p
|
|
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 int Fn sigmasked "struct proc *p" "int signum"
|
|
.Pp
|
|
This function returns non-zero if the signal specified by
|
|
.Fa signum
|
|
is ignored or masked for process
|
|
.Fa p .
|
|
.It void Fn sendsig "const ksiginfo_t *ks" "const sigset_t *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
|
|
.Pp
|
|
.Ed
|
|
.Pp
|
|
The current signal trampoline is:
|
|
.Bd -literal -offset indent
|
|
__sigtramp_siginfo_2
|
|
.Sh SEE ALSO
|
|
.Xr sigaction 2 ,
|
|
.Xr signal 7 ,
|
|
.Xr tsleep 9
|