1.\" $NetBSD: signal.9,v 1.4 2002/10/14 13:43:33 wiz Exp $ 2.\" 3.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg and Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd July 8, 2002 38.Dt SIGNAL 9 39.Os 40.Sh NAME 41.Nm signal , 42.Nm siginit , 43.Nm sigactsinit , 44.Nm sigactsunshare , 45.Nm sigactsfree , 46.Nm execsigs , 47.Nm sigaction1 , 48.Nm sigprocmask1 , 49.Nm sigpending1 , 50.Nm sigsuspend1 , 51.Nm sigaltstack1 , 52.Nm gsignal , 53.Nm pgsignal , 54.Nm trapsignal , 55.Nm psignal , 56.Nm sched_psignal , 57.Nm issignal , 58.Nm postsig , 59.Nm killproc , 60.Nm sigexit , 61.Nm sigmasked , 62.Nm sendsig , 63.Nm sigcode , 64.Nm sigtramp , 65.Nd software signal facilities 66.Sh SYNOPSIS 67.Fd #include \*[Lt]sys/signal.h\*[Gt] 68.Fd #include \*[Lt]sys/signalvar.h\*[Gt] 69.Ft void 70.Fn siginit "struct proc *p" 71.Ft void 72.Fn sigactsinit "struct proc *np" "struct proc *pp" "int share" 73.Ft void 74.Fn sigactsunsuare "struct proc *p" 75.Ft void 76.Fn sigactsfree "struct proc *p" 77.Ft void 78.Fn execsigs "struct proc *p" 79.Ft int 80.Fn sigaction1 "struct proc *p" "int signum" "const struct sigaction *nsa" \ 81 "struct sigaction *osa" "void *tramp" "int vers" 82.Ft int 83.Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \ 84 "sigset_t *oss" 85.Ft void 86.Fn sigpending1 "struct proc *p" "sigset_t *ss" 87.Ft int 88.Fn sigsuspend1 "struct proc *p" "const sigset_t *ss" 89.Ft int 90.Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \ 91 "struct sigaltstack *oss" 92.Ft void 93.Fn gsignal "int pgid" "int signum" 94.Ft void 95.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" 96.Ft void 97.Fn trapsignal "struct proc *p" "int signum" "u_long code" 98.Ft void 99.Fn psignal "struct proc *p" "int signum" 100.Ft void 101.Fn sched_psignal "struct proc *p" "int signum" 102.Ft int 103.Fn issignal "struct proc *p" 104.Ft void 105.Fn postsig "int signum" 106.Ft void 107.Fn killproc "struct proc *p" "const char *why" 108.Ft void 109.Fn sigexit "struct proc *p" "int signum" 110.Ft int 111.Fn sigmasked "struct proc *p" "int signum" 112.Ft void 113.Fn sendsig "int signum" "sigset_t *mask" "u_long code" 114.Sh DESCRIPTION 115The system defines a set of signals that may be delivered to a process. 116These functions implement the kernel portion of the signal facility. 117.Pp 118Signal numbers used throughout the kernel signal facilities should 119always be within the range of 120.Bq 1- Ns NSIG . 121.Pp 122Most of the kernel's signal infrastructure is implemented in 123machine-independent code. 124Machine-dependent code provides support for invoking a process's 125signal handler, restoring context when the signal handler returns, 126generating signals when hardware traps occur, triggering the delivery 127of signals when a process is about to return from the kernel to userspace. 128.Pp 129The signal state for a process is contained in 130.Fa struct sigctx . 131This includes the list of signals with delivery pending, 132information about the signal handler stack, the signal mask, and the 133address of the signal trampoline. 134.Pp 135The registered signal handlers for a process are recorded in 136.Fa struct sigacts . 137This structure may be shared by multiple processes. 138.Pp 139The kernel's signal facilities are implemented by the following 140functions: 141.Bl -tag -width XXXXX 142.It void Fn siginit "struct proc *p" 143.Pp 144This function initializes the signal state of 145.Va proc0 146to the system default. 147This signal state is then inherited by 148.Xr init 8 149when it is started by the kernel. 150.It void Fn sigactsinit "struct proc *np" "struct proc *pp" "int share" 151.Pp 152This function creates an initial 153.Fa struct sigacts 154for the process 155.Fa np . 156If the 157.Fa share 158argument is non-zero, then 159.Fa np 160shares the 161.Fa struct sigacts 162with the process 163.Fa pp . 164Otherwise, 165.Fa np 166receives a new 167.Fa struct sigacts 168which is copied from 169.Fa pp 170if non-NULL. 171.It void Fn sigactsunshare "struct proc *p" 172.Pp 173This function causes the process 174.Fa p 175to no longer share its 176.Fa struct sigacts 177The current state of the signal actions is maintained in the new copy. 178.It void Fn sigactsfree "struct proc *p" 179.Pp 180This function decrements the reference count on the 181.Fa struct sigacts 182of process 183.Fa p . 184If the reference count reaches zero, the 185.Fa struct sigacts 186is freed. 187.It void Fn execsigs "struct proc *p" 188.Pp 189This function is used to reset the signal state of the process 190.Fa p 191to the system defaults when the process execs a new program image. 192.It int Fn sigaction1 "struct proc *p" "int signum" \ 193 "const struct sigaction *nsa" "struct sigaction *osa" \ 194 "void *tramp" "int vers" 195.Pp 196This function implements the 197.Xr sigaction 2 198system call. 199The 200.Fa tramp 201and 202.Fa vers 203arguments provide support for userspace signal trampolines. 204Trampoline version 0 is reserved for the legacy kernel-provided 205signal trampoline; 206.Fa tramp 207must be NULL in this case. 208Otherwise, 209.Fa vers 210specifies the ABI of the trampoline specified by 211.Fa tramp . 212The signal trampoline ABI is machine-dependent, and must be coordinated 213with the 214.Fn sendsig 215function. 216.It int Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \ 217 "sigset_t *oss" 218.Pp 219This function implements the 220.Xr sigprocmask 2 221system call. 222.It void Fn sigpending1 "struct proc *p" "sigset_t *ss" 223.Pp 224This function implements the 225.Xr sigpending 2 226system call. 227.It int Fn sigsuspend1 "struct proc *p" "const sigset_t *ss" 228.Pp 229This function implements the 230.Xr sigsuspend 2 231system call. 232.It int Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \ 233 "struct sigaltstack *oss" 234.Pp 235This function implements the 236.Xr sigaltstack 2 237system call. 238.It void Fn gsignal "int pgid" "int signum" 239.Pp 240Schedule the signal 241.Fa signum 242to be delivered to all members of the process group specified by 243.Fa pgid . 244See 245.Fn psignal 246below for a complete description of the signal scheduling semantics. 247.It void Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" 248.Pp 249Schedule the signal 250.Fa signum 251to be delivered to all members of the process group 252.Fa pgrp . 253If 254.Fa checkctty 255is non-zero, the signal is only sent to processes which have a 256controlling terminal. 257See 258.Fn psignal 259below for a complete description of the signal scheduling semantics. 260.It void Fn trapsignal "struct proc *p" "int signum" "u_long code" 261.Pp 262Sends the signal 263.Fa signum 264with code 265.Fa code 266caused by a hardware trap to the process 267.Fa p . 268This function is meant to be called by machine-dependent trap handling 269code. 270.It void Fn psignal "struct proc *p" "int signum" 271.Pp 272Schedule the signal 273.Fa signum 274to be delivered to the process 275.Fa p . 276With a few exceptions noted below, the target process signal disposition is 277updated and is marked as runnable, so further handling of the signal is done 278in the context of the target process after a context switch; see 279.Fn issignal 280below. 281Note that 282.Fn psignal 283does not by itself cause a context switch to happen. 284.Pp 285The target process is not marked as runnable in the following cases: 286.Bl -bullet -offset indent 287.It 288The target process is sleeping uninterruptibly. 289The signal will be noticed when the process returns from the system 290call or trap. 291.It 292The target process is currently ignoring the signal. 293.It 294If a stop signal is sent to a sleeping process that takes the 295default action 296.Pq see Xr sigaction 2 , 297the process is stopped without awakening it. 298.It 299SIGCONT 300restarts a stopped process 301.Pq or puts them back to sleep 302regardless of the signal action 303.Pq e.g., blocked or ignored . 304.El 305.Pp 306If the target process is being traced, 307.Fn psignal 308behaves as if the target process were taking the default action for 309.Fa signum . 310This allows the tracing process to be notified of the signal. 311.It void Fn sched_psignal "struct proc *p" "int signum" 312.Pp 313An alternate version of 314.Fn psignal 315which is intended for use by code which holds the scheduler lock. 316.It int Fn issignal "struct proc *p" 317.Pp 318This function determines which signal, if any, is to be posted to 319the process 320.Fa p . 321A signal is to be posted if: 322.Bl -bullet -offset indent 323.It 324The signal has a handler provided by the program image. 325.It 326The signal should cause the process to dump core and/or terminate. 327.It 328The signal should interrupt the current system call. 329.El 330.Pp 331Signals which cause the process to be stopped are handled within 332.Fn issignal 333directly. 334.Pp 335.Fn issignal 336should be called by machine-dependent code when returning to 337userspace from a system call or other trap or interrupt by 338using the following code: 339.Bd -literal -offset indent 340while (signum = CURSIG(curproc)) 341 postsig(signum); 342.Ed 343.Pp 344.It void Fn postsig "int signum" 345.Pp 346The 347.Fn postsig 348function is used to invoke the action for the signal 349.Fa signum 350in the current process. 351If the default action of a signal is to terminate the process, and the 352signal does not have a registered handler, the process exits using 353.Fn sigexit , 354dumping a core image if necessary. 355.It void Fn killproc "struct proc *p" "const char *why" 356.Pp 357This function sends a SIGKILL signal to the specified process. 358The message provided by 359.Fa why 360is sent to the system log and is also displayed on the process's 361controlling terminal. 362.It void Fn sigexit "struct proc *p" "int signum" 363.Pp 364This function forces the process 365.Fa p 366to exit with the signal 367.Fa signum , 368generating a core file if appropriate. 369No checks are made for masked or caught signals; the process always exits. 370.It int Fn sigmasked "struct proc *p" "int signum" 371.Pp 372This function returns non-zero if the signal specified by 373.Fa signum 374is ignored or masked for process 375.Fa p . 376.It void Fn sendsig "int sig" "sigset_t *mask" "u_long code" 377.Pp 378This function is provided by machine-dependent code, and is used to 379invoke a signal handler for the current process. 380.Fn sendsig 381must prepare the registers and stack of the current process to 382invoke the signal handler stored in the process's 383.Fa struct sigacts . 384This may include switching to an alternate signal 385stack specified by the process. 386The previous register, stack, and signal state are stored in a 387.Fa struct sigcontext , 388which is then copied out to the user's stack. 389.Pp 390The registers and stack must be set up to invoke the signal handler as 391follows: 392.Bd -literal -offset indent 393(*handler)(signum, code, scp) 394.Ed 395.Pp 396where 397.Fa signum 398is the signal number, 399.Fa code 400is a signal-specific code, and 401.Fa scp 402is the pointer to the 403.Fa struct sigcontext 404on the user's stack. 405The registers and stack must also arrange for the signal handler to 406return to the signal trampoline. 407The trampoline is then used to return to the code which was executing 408when the signal was delivered using the 409.Xr sigreturn 2 410system call. 411.Pp 412For performance reasons, it is recommended that 413.Fn sendsig 414arrange for the signal handler to be invoked directly on architectures 415where it is convenient to do so. 416In this case, the trampoline is used only for the signal return path. 417If it is not feasible to directly invoke the signal handler, the 418trampoline is also used to invoke the handler, performing any final 419set up that was not possible for 420.Fn sendsig 421to perform. 422.Pp 423.Fn sendsig 424must invoke the signal trampoline with the correct ABI. 425The ABI of the signal trampoline is specified on a per-signal basis in the 426.Fn sigacts 427structure for the process. 428Trampoline version 0 is reserved for the legacy kernel-provided, 429on-stack signal trampoline. 430All other trampoline versions indicate a specific trampoline ABI. 431This ABI is coordinated with machine-dependent code in the system 432C library. 433.El 434.Ss SIGNAL TRAMPOLINE 435The signal trampoline is a special piece of code which provides 436support for invoking the signal handlers for a process. 437The trampoline is used to return from the signal handler back to the 438code which was executing when the signal was delivered, and is also used 439to invoke the handler itself on architectures where it is not feasible to 440have the kernel invoke the handler directly. 441.Pp 442In traditional 443.Ux 444systems, the signal trampoline, also referred to as the 445.Dq sigcode , 446is provided by the kernel and copied to the top of the user's 447stack when a new process is created or a new program image is 448exec'd. 449Starting in 450.Nx 2.0 , 451the signal trampoline is provided by the system C library. 452This allows for more flexibility when the signal facility is extended, 453makes dealing with signals easier in debuggers, such as 454.Xr gdb 1 , 455and may also enhance system security by allowing the kernel to 456disallow execution of code on the stack. 457.Pp 458The signal trampoline is specified on a per-signal basis. 459The correct trampoline is selected automatically by the C library 460when a signal handler is registered by a process. 461.Pp 462Signal trampolines have a special naming convention which enables 463debuggers to determine the characteristics of the signal handler 464and its arguments. 465Trampoline functions are named like so: 466.Bd -literal -offset indent 467__sigtramp_\*[Lt]flavor\*[Gt]_\*[Lt]version\*[Gt] 468.Ed 469.Pp 470where: 471.Bl -tag -width versionXX 472.It \*[Lt]flavor\*[Gt] 473The flavor of the signal handler. 474The following flavors are valid: 475.Bl -tag -width sigcontextXX 476.It sigcontext 477Specifies a traditional BSD-style signal handler with the following 478signature: 479.Bd -literal 480void (*handler)(int signum, 481 int code, 482 struct sigcontext *scp); 483.Ed 484.It siginfo 485Specifies a POSIX-style signal handler with the following signature: 486.Bd -literal 487void (*handler)(int signum, 488 struct siginfo *si, 489 void *uc); 490.Ed 491.Pp 492Note: support for POSIX-style signal 493handlers is not yet implemented in the 494.Nx 495kernel. 496.El 497.It \*[Lt]version\*[Gt] 498Specifies the ABI version of the signal trampoline. 499The trampoline ABI is coordinated with the machine-dependent kernel 500.Fn sendsig 501function. 502.El 503.Pp 504The following is an example if a signal trampoline name which indicates 505that the trampoline is used for traditional BSD-style signal handlers 506and implements version 1 of the signal trampoline ABI: 507.Bd -literal -offset indent 508__sigtramp_sigcontext_1 509.Ed 510.Sh SEE ALSO 511.Xr sigaction 2 , 512.Xr signal 7 , 513.Xr tsleep 9 514