freebsd-dev/share/man/man9/signal.9

.\"
.\" Copyright (C) 2002 Chad David <davidc@FreeBSD.org>. All rights reserved.
.\"
.\" 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(s), this list of conditions and the following disclaimer as
.\"    the first lines of this file unmodified other than the possible
.\"    addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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.
.\"
.\" $FreeBSD$
.\"
.Dd June 9, 2002
.Dt SIGNAL 9
.Os
.Sh NAME
.Nm signal
.Nm SIGADDSET ,
.Nm SIGDELSET ,
.Nm SETEMPTYSET ,
.Nm SIGFILLSET ,
.Nm SIGISMEMBER ,
.Nm SIGISEMPTY ,
.Nm SIGNOTEMPTY,
.Nm SIGSETEQ ,
.Nm SIGSETNEQ ,
.Nm SIGSETOR ,
.Nm SIGSETAND ,
.Nm SIGSETNAND ,
.Nm SIGSETCANTMASK ,
.Nm SIG_STOPSIGMASK ,
.Nm SIG_CONTSIGMASK ,
.Nm SIGPENDING ,
.Nm CURSIG ,
.Nm execsigs ,
.Nm issignal ,
.Nm killproc ,
.Nm pgsigio ,
.Nm postsig ,
.Nm sigexit ,
.Nm siginit ,
.Nm signotify ,
.Nm trapsignal
.Nd "kernel signal functions"
.Sh SYNOPSIS
.In sys/param.h
.In sys/proc.h
.In sys/signalvar.h
.Ft void
.Fn SIGADDSET "sigset_t set" "int signo"
.Ft void
.Fn SIGDELSET "sigset_t set" "int signo"
.Ft void
.Fn SIGEMPTYSET "sigset_t set"
.Ft void
.Fn SIGFILLSET "sigset_t set"
.Ft int
.Fn SIGISMEMBER "sigset_t set" "int signo"
.Ft int
.Fn SIGISEMPTY "sigset_t set"
.Ft int
.Fn SIGNOTEMPTY "sigset_t set"
.Ft int
.Fn SIGSETEQ "sigset_t set1" "sigset_t set2"
.Ft int
.Fn SIGSETNEQ "sigset_t set1" "sigset_t set2"
.Ft void
.Fn SIGSETOR "sigset_t set1" "sigset_t set2"
.Ft void
.Fn SIGSETAND "sigset_t set1" "sigset_t set2"
.Ft void
.Fn SIGSETNAND "sigset_t set1" "sigset_t set2"
.Ft void
.Fn SIG_CANTMASK "sigset_t set"
.Ft void
.Fn SIG_STOPSIGMASK "sigset_t set"
.Ft void
.Fn SIG_CONTSIGMASK "sigset_t set"
.Ft int
.Fn SIGPENDING "struct proc *p"
.Ft int
.Fn CURSIG "struct proc *p"
.Ft void
.Fn execsigs "struct proc *p"
.Ft int
.Fn issignal "struct proc *p"
.Ft void
.Fn killproc "struct proc *p" "char *why"
.Ft void
.Fn pgsigio "struct sigio **sigiop" "int sig" "int checkctty"
.Ft void
.Fn postsig "int sig"
.Ft void
.Fn sigexit "struct thread *td" "int signum"
.Ft void
.Fn siginit "struct proc *p"
.Ft void
.Fn signotify "struct proc *p"
.Ft void
.Fn trapsignal "struct proc *p" "int sig" "u_long code"
.Sh DESCRIPTION
The
.Fn SIGADDSET
macro adds
.Fa signo
to
.Fa set .
No effort is made to ensure that
.Fa signo
is a valid signal number.
.Pp
The
.Fn SIGDELSET
macro removes
.Fa signo
from
.Fa set .
No effort is made to ensure that
.Fa signo
is a valid signal number.
.Pp
The
.Fn SIGEMPTYSET
macro clears all signals in
.Fa set .
.Pp
The
.Fn SIGFILLSET
macro sets all signals in
.Fa set .
.Pp
The
.Fn SIGISMEMBER
macro determines if
.Fa signo
is set in
.Fa set .
.Pp
The
.Fn SIGISEMPTY
macro determines if
.Fa set
does not have any signals set.
.Pp
The
.Fn SIGNOTEMPTY
macro determines if
.Fa set
has any signals set.
.Pp
The
.Fn SIGSETEQ
macro determines if two signal sets are equal; that is, the same signals
are set in both.
.Pp
The
.Fn SIGSETNEQ
macro determines if two signal sets differ; that is, if any signal set in
one is not set in the other.
.Pp
The
.Fn SIGSETOR
macro ors the signals set in
.Fa set2
into
.Fa set1 .
.Pp
The
.Fn SIGSETAND
macro ands the signals set in
.Fa set2
into
.Fa set1 .
.Pp
The
.Fn SIGSETNAND
macro nands the signals set in
.Fa set2
into
.Fa set1 .
.Pp
The
.Fn SIG_CANTMASK
macro clears the
.Dv SIGKILL
and
.Dv SIGSTOP
signals from
.Fa set .
These two signals cannot be blocked or caught and
.Fn SIG_CANTMASK
is used in code where signals are manipulated to ensure this policy
is enforced.
.Pp
The
.Fn SIG_STOPSIGMASK
macro clears the
.Dv SIGSTOP ,
.Dv SIGTSTP ,
.Dv SIGTTIN ,
and
.Dv SIGTTOU
signals from
.Fa set .
.Fn SIG_STOPSIGMASK
is used to clear stop signals when a process is waiting for a child to
exit or exec, and when a process is continuing after having been
suspended.
.Pp
The
.Fn SIG_CONTSIGMASK
macro clears the
.Dv SIGCONT
signal from
.Fa set .
.Fn SIG_CONTSIGMASK
is call when a process is stopped.
.Pp
The
.Fn SIGPENDING
macro determines if the given process has any pending signals that are
not masked.
If the process has a pending signal and the process is currently being
traced
.Fn SIGPENDING
will return true even if the signal is masked.
.Pp
The
.Fn CURSIG
function returns the signal number that should be delivered to
.Fa p .
If there are no signals pending zero is returned.
.Pp
The
.Fn execsigs
function resets the signal set and signal stack of a process in preparation
for an
.Fn exec 2 .
The lock for
.Fa p
must be held before
.Fn execsigs
is called.
.Pp
The
.Fn issignal
function determines if there are any pending signals for
.Fa p
that should be caught, cause 
.Fa p
to terminate or interrupt the
current system call.
If
.Fa p
is currently being traced, ignored signals will be handled and
.Fa p
is always stopped.
Stop signals are handled and cleared right away by
.Fn issignal ,
unless the process is a member of an orphaned process group and the stop
signal originated from a tty.
.Fa sched_lock
may be acquired and released and if
.Fa Giant
is held it may be released and reacquired.
.Fa p
must be locked before
.Fn issignal
is called and may be released and reacquired during the call; as well,
.Fa p's
parent's lock may be acquired and released.
Default signal actions are not taken for system processes and init.
.Pp
The
.Fn killproc
function delivers
.Dv SIGKILL to
.Fa p .
.Fa why
is logged as the reason "why" the process was killed.
.Pp
The
.Fn pgsigio
function sends the signal
.Fa sig
to the process or process group
.Fa sigiop->sio_pgid .
If
.Fa checkctty
is non-zero the signal is only delivered to processes in the process group
that have a controlling terminal.
If
.Va sigiop->sio_pgid
is for a process (\> 0), the lock for
.Va sigiop->sio_proc
is acquired and released.
If
.Va sigiop->sio_pgid
is for a process group (\< 0), the process group lock for
.Va sigiop->sio_pgrp
is acquired and released.
.Fa sigio_lock
is acquired and released.
.Pp
The
.Fn postsig
function handles the actual delivery of the signal
.Fa sig .
.Fn postsig
is called called from
.Fn ast
after the kernel has been notified that a signal should be delivered
(via a call to
.Fn signotify ,
which causes the flag
.Dv PS_NEEDSIGCHK
to be set).
The lock for process that owns
.Va curthread
must be held before
.Fn postsig
is called, and the current process cannot be 0.
.Pp
The
.Fn sigexit
function causes the process that owns
.Fa td
to exit with a return value of signal number
.Fa sig.
If required, the process will dump core.
The lock for the process that owns
.Fa td
must be held before
.Fn sigexit
is called, and
.Fa Giant
will be acquired if it is not already held.
.Pp
The
.Fn siginit
function is called during system initialization to cause every signal with
a default property of
.Dv SA_IGNORE
(except
.Dv SIGCONT )
to be ignored by
.Fa p .
The process lock for
.Fa p
is acquired and released by
.Fn siginit .
The only process that
.Fn siginit
is ever called for
is
.Va proc0.
.Pp
The
.Fn signotify
function flags that there are unmasked signals pending that
.Fn ast
should handle.
The lock for
.Pa p
must be held before
.Fn signotify
is called, and
.Fa sched_lock
is acquired and released.
.Pp
The
.Fn trapsignal
function sends a signal that is the result of a trap to
.Fa p .
If the process is not being traced and the signal can be delivered
immediately
.Fn trapsignal
will deliver it directly; otherwise,
.Fn trapsignal
will call
.Xr psignal 9
to cause the signal to be delivered.
Giant is acquired and released, as is the lock for
.Fa p .
.Sh RETURN VALUES
The
.Fn SIGISMEMBER ,
.Fn SIGISEMPTY ,
.Fn SIGNOTEMPTY ,
.Fn SIGSETEQ ,
.Fn SIGSETNEQ ,
and
.Fn SIGPENDING
macros all return non\-zero (true) if the condition they are checking
is found to be true; otherwise, zero (false) is returned.
.Pp
.Fn CURSIG
returns either a valid signal number or zero.
.Pp
.Fn issignal
returns either a valid signal number or zero.
.Sh SEE ALSO
.Xr gsignal 9 ,
.Xr pgsignal 9 ,
.Xr psignal 9
.Sh AUTHORS
This man page was written by
.An Chad David Aq davidc@FreeBSD.org .