xref: /freebsd/share/man/man9/signal.9 (revision f0adf7f5cdd241db2f2c817683191a6ef64a4e95) 
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 9, 2002
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 proc *p"
99.Ft void
100.Fn execsigs "struct proc *p"
101.Ft int
102.Fn issignal "struct proc *p"
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 proc *p"
115.Ft void
116.Fn trapsignal "struct proc *p" "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
247.Fa p .
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
264.Fa p
265that should be caught, cause
266.Fa p
267to terminate or interrupt the
268current system call.
269If
270.Fa p
271is currently being traced, ignored signals will be handled and
272.Fa p
273is always stopped.
274Stop signals are handled and cleared right away by
275.Fn issignal ,
276unless the process is a member of an orphaned process group and the stop
277signal originated from a TTY.
278The
279.Va sched_lock
280lock
281may be acquired and released, and if
282.Va Giant
283is held, it may be released and reacquired.
284.Fa p
285must be locked before
286.Fn issignal
287is called and may be released and reacquired during the call; as well,
288.Fa p
289parent's lock may be acquired and released.
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.
323.Fa sigio_lock
324is acquired and released.
325.Pp
326The
327.Fn postsig
328function handles the actual delivery of the signal
329.Fa sig .
330.Fn postsig
331is called from
332.Fn ast
333after the kernel has been notified that a signal should be delivered
334(via a call to
335.Fn signotify ,
336which causes the flag
337.Dv PS_NEEDSIGCHK
338to be set).
339The lock for process that owns
340.Va curthread
341must be held before
342.Fn postsig
343is called, and the current process cannot be 0.
344.Pp
345The
346.Fn sigexit
347function causes the process that owns
348.Fa td
349to exit with a return value of signal number
350.Fa sig .
351If required, the process will dump core.
352The lock for the process that owns
353.Fa td
354must be held before
355.Fn sigexit
356is called, and
357.Va Giant
358will be acquired if it is not already held.
359.Pp
360The
361.Fn siginit
362function is called during system initialization to cause every signal with
363a default property of
364.Dv SA_IGNORE
365(except
366.Dv SIGCONT )
367to be ignored by
368.Fa p .
369The process lock for
370.Fa p
371is acquired and released by
372.Fn siginit .
373The only process that
374.Fn siginit
375is ever called for
376is
377.Va proc0 .
378.Pp
379The
380.Fn signotify
381function flags that there are unmasked signals pending that
382.Fn ast
383should handle.
384The lock for
385.Fa p
386must be held before
387.Fn signotify
388is called, and
389.Va sched_lock
390is acquired and released.
391.Pp
392The
393.Fn trapsignal
394function sends a signal that is the result of a trap to
395.Fa p .
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.
404.Va Giant
405is acquired and released, as is the lock for
406.Fa p .
407.Sh RETURN VALUES
408The
409.Fn SIGISMEMBER ,
410.Fn SIGISEMPTY ,
411.Fn SIGNOTEMPTY ,
412.Fn SIGSETEQ ,
413.Fn SIGSETNEQ ,
414and
415.Fn SIGPENDING
416macros all return non-zero (true) if the condition they are checking
417is found to be true; otherwise, zero (false) is returned.
418.Pp
419.Fn CURSIG
420returns either a valid signal number or zero.
421.Pp
422.Fn issignal
423returns either a valid signal number or zero.
424.Sh SEE ALSO
425.Xr gsignal 9 ,
426.Xr pgsignal 9 ,
427.Xr psignal 9
428.Sh AUTHORS
429This man page was written by
430.An Chad David Aq davidc@FreeBSD.org .
431