xref: /freebsd/share/man/man9/psignal.9 (revision bb15ca603fa442c72dde3f3cb8b46db6970e3950)
1.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
2.\" All rights reserved.
3.\"
4.\" This code is derived from software contributed to The NetBSD Foundation
5.\" by Paul Kranenburg.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26.\" POSSIBILITY OF SUCH DAMAGE.
27.\"
28.\"	$NetBSD: psignal.9,v 1.1 1996/06/22 22:57:35 pk Exp $
29.\" $FreeBSD$
30.\"
31.Dd October 8, 2011
32.Dt PSIGNAL 9
33.Os
34.Sh NAME
35.Nm psignal ,
36.Nm pgsignal ,
37.Nm gsignal ,
38.Nm tdsignal
39.Nd post signal to a thread, process, or process group
40.Sh SYNOPSIS
41.In sys/types.h
42.In sys/signalvar.h
43.Ft void
44.Fn psignal "struct proc *p" "int signum"
45.Ft void
46.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty"
47.Ft void
48.Fn gsignal "int pgid" "int signum"
49.Ft void
50.Fn tdsignal "struct thread *td" "int signum"
51.Sh DESCRIPTION
52These functions post a signal to a thread or one or more processes.
53The argument
54.Fa signum
55common to all three functions should be in the range
56.Bq 1- Ns Dv NSIG .
57.Pp
58The
59.Fn psignal
60function posts signal number
61.Fa signum
62to the process represented by the process structure
63.Fa p .
64With a few exceptions noted below, the target process signal disposition is
65updated and is marked as runnable, so further handling of the signal is done
66in the context of the target process after a context switch.
67Note that
68.Fn psignal
69does not by itself cause a context switch to happen.
70.Pp
71The target process is not marked as runnable in the following cases:
72.Bl -bullet -offset indent
73.It
74The target process is sleeping uninterruptibly.
75The signal will be
76noticed when the process returns from the system call or trap.
77.It
78The target process is currently ignoring the signal.
79.It
80If a stop signal is sent to a sleeping process that takes the
81default action
82(see
83.Xr sigaction 2 ) ,
84the process is stopped without awakening it.
85.It
86.Dv SIGCONT
87restarts a stopped process
88(or puts them back to sleep)
89regardless of the signal action
90(e.g., blocked or ignored).
91.El
92.Pp
93If the target process is being traced
94.Fn psignal
95behaves as if the target process were taking the default action for
96.Fa signum .
97This allows the tracing process to be notified of the signal.
98.Pp
99The
100.Fn pgsignal
101function posts signal number
102.Fa signum
103to each member of the process group described by
104.Fa pgrp .
105If
106.Fa checkctty
107is non-zero, the signal will be posted only to processes that have
108a controlling terminal.
109.Fn pgsignal
110is implemented by walking along the process list headed by the field
111.Li pg_members
112of the process group structure
113pointed at by
114.Fa pgrp
115and calling
116.Fn psignal
117as appropriate.
118If
119.Fa pgrp
120is
121.Dv NULL
122no action is taken.
123.Pp
124The
125.Fn gsignal
126function posts signal number
127.Fa signum
128to each member of the process group identified by the group id
129.Fa pgid .
130.Fn gsignal
131first finds the group structure associated with
132.Fa pgid ,
133then invokes
134.Fn pgsignal
135with the argument
136.Fa checkctty
137set to zero.
138If
139.Fa pgid
140is zero no action is taken.
141.Pp
142The
143.Fn tdsignal
144function posts signal number
145.Fa signum
146to the thread represented by the thread structure
147.Fa td .
148.Sh SEE ALSO
149.Xr sigaction 2 ,
150.Xr signal 9 ,
151.Xr tsleep 9
152