xref: /freebsd/share/man/man9/signal.9 (revision 39beb93c) 
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 November 20, 2004
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 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
276.Va sched_lock
277lock may be acquired and released, and if
278.Va Giant
279is held, it may be released and reacquired.
280The
281.Vt sigacts
282structure
283.Fa td->td_proc->p_sigacts
284must be locked before calling
285.Fn issignal
286and may be released and reacquired during the call.
287The process lock for
288.Fa td->td_proc
289must be acquired before calling
290.Fn issignal
291and may be released and reacquired during the call.
292The lock for the parent of
293.Fa td->td_proc
294may also be acquired and released.
295Default signal actions are not taken for system processes and init.
296.Pp
297The
298.Fn killproc
299function delivers
300.Dv SIGKILL
301to
302.Fa p .
303.Fa why
304is logged as the reason
305.Em why
306the process was killed.
307.Pp
308The
309.Fn pgsigio
310function sends the signal
311.Fa sig
312to the process or process group
313.Fa sigiop->sio_pgid .
314If
315.Fa checkctty
316is non-zero, the signal is only delivered to processes in the process group
317that have a controlling terminal.
318If
319.Fa sigiop->sio_pgid
320is for a process (> 0), the lock for
321.Fa sigiop->sio_proc
322is acquired and released.
323If
324.Fa sigiop->sio_pgid
325is for a process group (< 0), the process group lock for
326.Fa sigiop->sio_pgrp
327is acquired and released.
328The lock
329.Va sigio_lock
330is acquired and released.
331.Pp
332The
333.Fn postsig
334function handles the actual delivery of the signal
335.Fa sig .
336.Fn postsig
337is called from
338.Fn ast
339after the kernel has been notified that a signal should be delivered
340(via a call to
341.Fn signotify ,
342which causes the flag
343.Dv PS_NEEDSIGCHK
344to be set).
345The lock for process that owns
346.Va curthread
347must be held before
348.Fn postsig
349is called, and the current process cannot be 0.
350The lock for the
351.Va p_sigacts
352field of the current process must be held before
353.Fn postsig
354is called, and may be released and reacquired.
355.Pp
356The
357.Fn sigexit
358function causes the process that owns
359.Fa td
360to exit with a return value of signal number
361.Fa sig .
362If required, the process will dump core.
363The lock for the process that owns
364.Fa td
365must be held before
366.Fn sigexit
367is called.
368.Pp
369The
370.Fn siginit
371function is called during system initialization to cause every signal with
372a default property of
373.Dv SA_IGNORE
374(except
375.Dv SIGCONT )
376to be ignored by
377.Fa p .
378The process lock for
379.Fa p
380is acquired and released by
381.Fn siginit .
382The only process that
383.Fn siginit
384is ever called for
385is
386.Va proc0 .
387.Pp
388The
389.Fn signotify
390function flags that there are unmasked signals pending that
391.Fn ast
392should handle.
393The lock for process
394.Fa td->td_proc
395must be held before
396.Fn signotify
397is called, and
398.Va sched_lock
399is acquired and released.
400.Pp
401The
402.Fn trapsignal
403function sends a signal that is the result of a trap to process
404.Fa td->td_proc .
405If the process is not being traced and the signal can be delivered
406immediately,
407.Fn trapsignal
408will deliver it directly; otherwise,
409.Fn trapsignal
410will call
411.Xr psignal 9
412to cause the signal to be delivered.
413The
414.Va sched_lock
415lock is acquired and released, as is the lock for
416.Fa td->td_proc .
417The lock for the
418.Va p_sigacts
419field of
420.Fa td->td_proc
421is acquired and released.
422.Sh RETURN VALUES
423The
424.Fn SIGISMEMBER ,
425.Fn SIGISEMPTY ,
426.Fn SIGNOTEMPTY ,
427.Fn SIGSETEQ ,
428.Fn SIGSETNEQ ,
429and
430.Fn SIGPENDING
431macros all return non-zero (true) if the condition they are checking
432is found to be true; otherwise, zero (false) is returned.
433.Pp
434The
435.Fn cursig
436function returns either a valid signal number or zero.
437.Pp
438.Fn issignal
439returns either a valid signal number or zero.
440.Sh SEE ALSO
441.Xr gsignal 9 ,
442.Xr pgsignal 9 ,
443.Xr psignal 9
444.Sh AUTHORS
445This manual page was written by
446.An Chad David Aq davidc@FreeBSD.org .
447