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