xref: /freebsd/share/man/man9/signal.9 (revision 06c3fb27) 
1.\"
2.\" Copyright (C) 2002 Chad David <davidc@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice(s), this list of conditions and the following disclaimer as
9.\"    the first lines of this file unmodified other than the possible
10.\"    addition of one or more copyright notices.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice(s), this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
25.\" DAMAGE.
26.\"
27.Dd July 14, 2023
28.Dt SIGNAL 9
29.Os
30.Sh NAME
31.Nm signal ,
32.Nm SIGADDSET ,
33.Nm SIGDELSET ,
34.Nm SETEMPTYSET ,
35.Nm SIGFILLSET ,
36.Nm SIGISMEMBER ,
37.Nm SIGISEMPTY ,
38.Nm SIGNOTEMPTY ,
39.Nm SIGSETEQ ,
40.Nm SIGSETNEQ ,
41.Nm SIGSETOR ,
42.Nm SIGSETAND ,
43.Nm SIGSETNAND ,
44.Nm SIGSETCANTMASK ,
45.Nm SIG_STOPSIGMASK ,
46.Nm SIG_CONTSIGMASK ,
47.Nm SIGPENDING ,
48.Nm cursig ,
49.Nm execsigs ,
50.Nm issignal ,
51.Nm killproc ,
52.Nm pgsigio ,
53.Nm postsig ,
54.Nm sigexit ,
55.Nm siginit ,
56.Nm signotify ,
57.Nm trapsignal
58.Nd "kernel signal functions"
59.Sh SYNOPSIS
60.In sys/param.h
61.In sys/proc.h
62.In sys/signalvar.h
63.Ft void
64.Fn SIGADDSET "sigset_t set" "int signo"
65.Ft void
66.Fn SIGDELSET "sigset_t set" "int signo"
67.Ft void
68.Fn SIGEMPTYSET "sigset_t set"
69.Ft void
70.Fn SIGFILLSET "sigset_t set"
71.Ft int
72.Fn SIGISMEMBER "sigset_t set" "int signo"
73.Ft int
74.Fn SIGISEMPTY "sigset_t set"
75.Ft int
76.Fn SIGNOTEMPTY "sigset_t set"
77.Ft int
78.Fn SIGSETEQ "sigset_t set1" "sigset_t set2"
79.Ft int
80.Fn SIGSETNEQ "sigset_t set1" "sigset_t set2"
81.Ft void
82.Fn SIGSETOR "sigset_t set1" "sigset_t set2"
83.Ft void
84.Fn SIGSETAND "sigset_t set1" "sigset_t set2"
85.Ft void
86.Fn SIGSETNAND "sigset_t set1" "sigset_t set2"
87.Ft void
88.Fn SIG_CANTMASK "sigset_t set"
89.Ft void
90.Fn SIG_STOPSIGMASK "sigset_t set"
91.Ft void
92.Fn SIG_CONTSIGMASK "sigset_t set"
93.Ft int
94.Fn SIGPENDING "struct proc *p"
95.Ft int
96.Fn cursig "struct thread *td"
97.Ft void
98.Fn execsigs "struct proc *p"
99.Ft int
100.Fn issignal "struct thread *td"
101.Ft void
102.Fn killproc "struct proc *p" "char *why"
103.Ft void
104.Fn pgsigio "struct sigio **sigiop" "int sig" "int checkctty"
105.Ft void
106.Fn postsig "int sig"
107.Ft void
108.Fn sigexit "struct thread *td" "int signum"
109.Ft void
110.Fn siginit "struct proc *p"
111.Ft void
112.Fn signotify "struct thread *td"
113.Ft void
114.Fn trapsignal "struct thread *td" "int sig" "u_long code"
115.Sh DESCRIPTION
116The
117.Fn SIGADDSET
118macro adds
119.Fa signo
120to
121.Fa set .
122No effort is made to ensure that
123.Fa signo
124is a valid signal number.
125.Pp
126The
127.Fn SIGDELSET
128macro removes
129.Fa signo
130from
131.Fa set .
132No effort is made to ensure that
133.Fa signo
134is a valid signal number.
135.Pp
136The
137.Fn SIGEMPTYSET
138macro clears all signals in
139.Fa set .
140.Pp
141The
142.Fn SIGFILLSET
143macro sets all signals in
144.Fa set .
145.Pp
146The
147.Fn SIGISMEMBER
148macro determines if
149.Fa signo
150is set in
151.Fa set .
152.Pp
153The
154.Fn SIGISEMPTY
155macro determines if
156.Fa set
157does not have any signals set.
158.Pp
159The
160.Fn SIGNOTEMPTY
161macro determines if
162.Fa set
163has any signals set.
164.Pp
165The
166.Fn SIGSETEQ
167macro determines if two signal sets are equal; that is, the same signals
168are set in both.
169.Pp
170The
171.Fn SIGSETNEQ
172macro determines if two signal sets differ; that is, if any signal set in
173one is not set in the other.
174.Pp
175The
176.Fn SIGSETOR
177macro ORs the signals set in
178.Fa set2
179into
180.Fa set1 .
181.Pp
182The
183.Fn SIGSETAND
184macro ANDs the signals set in
185.Fa set2
186into
187.Fa set1 .
188.Pp
189The
190.Fn SIGSETNAND
191macro NANDs the signals set in
192.Fa set2
193into
194.Fa set1 .
195.Pp
196The
197.Fn SIG_CANTMASK
198macro clears the
199.Dv SIGKILL
200and
201.Dv SIGSTOP
202signals from
203.Fa set .
204These two signals cannot be blocked or caught and
205.Fn SIG_CANTMASK
206is used in code where signals are manipulated to ensure this policy
207is enforced.
208.Pp
209The
210.Fn SIG_STOPSIGMASK
211macro clears the
212.Dv SIGSTOP ,
213.Dv SIGTSTP ,
214.Dv SIGTTIN ,
215and
216.Dv SIGTTOU
217signals from
218.Fa set .
219.Fn SIG_STOPSIGMASK
220is used to clear stop signals when a process is waiting for a child to
221exit or exec, and when a process is continuing after having been
222suspended.
223.Pp
224The
225.Fn SIG_CONTSIGMASK
226macro clears the
227.Dv SIGCONT
228signal from
229.Fa set .
230.Fn SIG_CONTSIGMASK
231is called when a process is stopped.
232.Pp
233The
234.Fn SIGPENDING
235macro determines if the given process has any pending signals that are
236not masked.
237If the process has a pending signal and the process is currently being
238traced,
239.Fn SIGPENDING
240will return true even if the signal is masked.
241.Pp
242The
243.Fn cursig
244function returns the signal number that should be delivered to process
245.Fa td->td_proc .
246If there are no signals pending, zero is returned.
247.Pp
248The
249.Fn execsigs
250function resets the signal set and signal stack of a process in preparation
251for an
252.Xr execve 2 .
253The process lock for
254.Fa p
255must be held before
256.Fn execsigs
257is called.
258.Pp
259The
260.Fn issignal
261function determines if there are any pending signals for process
262.Fa td->td_proc
263that should be caught, or cause this process to terminate or interrupt its
264current system call.
265If process
266.Fa td->td_proc
267is currently being traced, ignored signals will be handled and the process
268is always stopped.
269Stop signals are handled and cleared right away by
270.Fn issignal
271unless the process is a member of an orphaned process group and the stop
272signal originated from a TTY.
273The process spin lock for
274.Fa td->td_proc
275may be acquired and released.
276The
277.Vt sigacts
278structure
279.Fa td->td_proc->p_sigacts
280must be locked before calling
281.Fn issignal
282and may be released and reacquired during the call.
283The process lock for
284.Fa td->td_proc
285must be acquired before calling
286.Fn issignal
287and may be released and reacquired during the call.
288Default signal actions are not taken for system processes and init.
289.Pp
290The
291.Fn killproc
292function delivers
293.Dv SIGKILL
294to
295.Fa p .
296.Fa why
297is logged as the reason
298.Em why
299the process was killed.
300.Pp
301The
302.Fn pgsigio
303function sends the signal
304.Fa sig
305to the process or process group
306.Fa sigiop->sio_pgid .
307If
308.Fa checkctty
309is non-zero, the signal is only delivered to processes in the process group
310that have a controlling terminal.
311If
312.Fa sigiop->sio_pgid
313is for a process (> 0), the lock for
314.Fa sigiop->sio_proc
315is acquired and released.
316If
317.Fa sigiop->sio_pgid
318is for a process group (< 0), the process group lock for
319.Fa sigiop->sio_pgrp
320is acquired and released.
321The lock
322.Va sigio_lock
323is acquired and released.
324.Pp
325The
326.Fn postsig
327function handles the actual delivery of the signal
328.Fa sig .
329.Fn postsig
330is called from
331.Fn ast
332after the kernel has been notified that a signal should be delivered
333(via a call to
334.Fn signotify ,
335which causes the flag
336.Dv PS_NEEDSIGCHK
337to be set).
338The process lock for process that owns
339.Va curthread
340must be held before
341.Fn postsig
342is called, and the current process cannot be 0.
343The lock for the
344.Va p_sigacts
345field of the current process must be held before
346.Fn postsig
347is called, and may be released and reacquired.
348.Pp
349The
350.Fn sigexit
351function causes the process that owns
352.Fa td
353to exit with a return value of signal number
354.Fa sig .
355If required, the process will dump core.
356The process lock for the process that owns
357.Fa td
358must be held before
359.Fn sigexit
360is called.
361.Pp
362The
363.Fn siginit
364function is called during system initialization to cause every signal with
365a default property of
366.Dv SA_IGNORE
367(except
368.Dv SIGCONT )
369to be ignored by
370.Fa p .
371The process lock for
372.Fa p
373is acquired and released, as is the lock for sigacts structure
374.Fa p->p_sigacts .
375The only process that
376.Fn siginit
377is ever called for
378is
379.Va proc0 .
380.Pp
381The
382.Fn signotify
383function flags that there are unmasked signals pending that
384.Fn ast
385should handle.
386The process lock for process
387.Fa td->td_proc
388must be held before
389.Fn signotify
390is called, and the thread lock is acquired and released.
391.Pp
392The
393.Fn trapsignal
394function sends a signal that is the result of a trap to process
395.Fa td->td_proc .
396If the process is not being traced and the signal can be delivered
397immediately,
398.Fn trapsignal
399will deliver it directly; otherwise,
400.Fn trapsignal
401will call
402.Xr psignal 9
403to cause the signal to be delivered.
404The process lock for
405.Fa td->td_proc
406is acquired and released.
407The lock for the
408.Va p_sigacts
409field of
410.Fa td->td_proc
411is acquired and released.
412.Sh RETURN VALUES
413The
414.Fn SIGISMEMBER ,
415.Fn SIGISEMPTY ,
416.Fn SIGNOTEMPTY ,
417.Fn SIGSETEQ ,
418.Fn SIGSETNEQ ,
419and
420.Fn SIGPENDING
421macros all return non-zero (true) if the condition they are checking
422is found to be true; otherwise, zero (false) is returned.
423.Pp
424The
425.Fn cursig
426function returns either a valid signal number or zero.
427.Pp
428.Fn issignal
429returns either a valid signal number or zero.
430.Sh SEE ALSO
431.Xr pgsignal 9 ,
432.Xr psignal 9
433.Sh AUTHORS
434This manual page was written by
435.An Chad David Aq Mt davidc@FreeBSD.org .
436