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