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