share/man/man9/signal.9

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