1.\" $NetBSD: signal.9,v 1.3 2002/07/28 22:18:52 manu 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. Machine-dependent code provides 124support for invoking a process's signal handler, restoring 125context when the signal handler returns, generating signals 126when hardware traps occur, triggering the delivery of signals 127when 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. This signal state is then inherited by 147.Xr init 8 148when it is started by the kernel. 149.It void Fn sigactsinit "struct proc *np" "struct proc *pp" "int share" 150.Pp 151This function creates an initial 152.Fa struct sigacts 153for the process 154.Fa np . 155If the 156.Fa share 157argument is non-zero, then 158.Fa np 159shares the 160.Fa struct sigacts 161with the process 162.Fa pp . 163Otherwise, 164.Fa np 165receives a new 166.Fa struct sigacts 167which is copied from 168.Fa pp 169if non-NULL. 170.It void Fn sigactsunshare "struct proc *p" 171.Pp 172This function causes the process 173.Fa p 174to no longer share its 175.Fa struct sigacts 176The current state of the signal actions is maintained in the new copy. 177.It void Fn sigactsfree "struct proc *p" 178.Pp 179This function decrements the reference count on the 180.Fa struct sigacts 181of process 182.Fa p . 183If the reference count reaches zero, the 184.Fa struct sigacts 185is freed. 186.It void Fn execsigs "struct proc *p" 187.Pp 188This function is used to reset the signal state of the process 189.Fa p 190to the system defaults when the process execs a new program image. 191.It int Fn sigaction1 "struct proc *p" "int signum" \ 192 "const struct sigaction *nsa" "struct sigaction *osa" \ 193 "void *tramp" "int vers" 194.Pp 195This function implements the 196.Xr sigaction 2 197system call. The 198.Fa tramp 199and 200.Fa vers 201arguments provide support for userspace signal trampolines. 202Trampoline version 0 is reserved for the legacy kernel-provided 203signal trampoline; 204.Fa tramp 205must be NULL in this case. Otherwise, 206.Fa vers 207specifies the ABI of the trampoline specified by 208.Fa tramp . 209The signal trampoline ABI is machine-dependent, and must be coordinated 210with the 211.Fn sendsig 212function. 213.It int Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \ 214 "sigset_t *oss" 215.Pp 216This function implements the 217.Xr sigprocmask 2 218system call. 219.It void Fn sigpending1 "struct proc *p" "sigset_t *ss" 220.Pp 221This function implements the 222.Xr sigpending 2 223system call. 224.It int Fn sigsuspend1 "struct proc *p" "const sigset_t *ss" 225.Pp 226This function implements the 227.Xr sigsuspend 2 228system call. 229.It int Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \ 230 "struct sigaltstack *oss" 231.Pp 232This function implements the 233.Xr sigaltstack 2 234system call. 235.It void Fn gsignal "int pgid" "int signum" 236.Pp 237Schedule the signal 238.Fa signum 239to be delivered to all members of the process group specified by 240.Fa pgid . 241See 242.Fn psignal 243below for a complete description of the signal scheduling semantics. 244.It void Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" 245.Pp 246Schedule the signal 247.Fa signum 248to be delivered to all members of the process group 249.Fa pgrp . 250If 251.Fa checkctty 252is non-zero, the signal is only sent to processes which have a 253controlling terminal. See 254.Fn psignal 255below for a complete description of the signal scheduling semantics. 256.It void Fn trapsignal "struct proc *p" "int signum" "u_long code" 257.Pp 258Sends the signal 259.Fa signum 260with code 261.Fa code 262caused by a hardware trap to the process 263.Fa p . 264This function is meant to be called by machine-dependent trap handling 265code. 266.It void Fn psignal "struct proc *p" "int signum" 267.Pp 268Schedule the signal 269.Fa signum 270to be delivered to the process 271.Fa p . 272With a few exceptions noted below, the target process signal disposition is 273updated and is marked as runnable, so further handling of the signal is done 274in the context of the target process after a context switch; see 275.Fn issignal 276below. 277Note that 278.Fn psignal 279does not by itself cause a context switch to happen. 280.Pp 281The target process is not marked as runnable in the following cases: 282.Bl -bullet -offset indent 283.It 284The target process is sleeping uninterruptibly. The signal will be 285noticed when the process returns from the system call or trap. 286.It 287The target process is currently ignoring the signal. 288.It 289If a stop signal is sent to a sleeping process that takes the 290default action 291.Pq see Xr sigaction 2 , 292the process is stopped without awakening it. 293.It 294SIGCONT 295restarts a stopped process 296.Pq or puts them back to sleep 297regardless of the signal action 298.Pq e.g., blocked or ignored . 299.El 300.Pp 301If the target process is being traced, 302.Fn psignal 303behaves as if the target process were taking the default action for 304.Fa signum . 305This allows the tracing process to be notified of the signal. 306.It void Fn sched_psignal "struct proc *p" "int signum" 307.Pp 308An alternate version of 309.Fn psignal 310which is intended for use by code which holds the scheduler lock. 311.It int Fn issignal "struct proc *p" 312.Pp 313This function determines which signal, if any, is to be posted to 314the process 315.Fa p . 316A signal is to be posted if: 317.Bl -bullet -offset indent 318.It 319The signal has a handler provided by the program image. 320.It 321The signal should cause the process to dump core and/or terminate. 322.It 323The signal should interrupt the current system call. 324.El 325.Pp 326Signals which cause the process to be stopped are handled within 327.Fn issignal 328directly. 329.Pp 330.Fn issignal 331should be called by machine-dependent code when returning to 332userspace from a system call or other trap or interrupt by 333using the following code: 334.Bd -literal -offset indent 335while (signum = CURSIG(curproc)) 336 postsig(signum); 337.Ed 338.Pp 339.It void Fn postsig "int signum" 340.Pp 341The 342.Fn postsig 343function is used to invoke the action for the signal 344.Fa signum 345in the current process. If the default action of a signal 346is to terminate the process, and the signal does not have 347a registered handler, the process exits using 348.Fn sigexit , 349dumping a core image if necessary. 350.It void Fn killproc "struct proc *p" "const char *why" 351.Pp 352This function sends a SIGKILL signal to the specified process. The 353message provided by 354.Fa why 355is sent to the system log and is also displayed on the process's 356controlling terminal. 357.It void Fn sigexit "struct proc *p" "int signum" 358.Pp 359This function forces the process 360.Fa p 361to exit with the signal 362.Fa signum , 363generating a core file if appropriate. No checks are made for masked 364or caught signals; the process always exits. 365.It int Fn sigmasked "struct proc *p" "int signum" 366.Pp 367This function returns non-zero if the signal specified by 368.Fa signum 369is ignored or masked for process 370.Fa p . 371.It void Fn sendsig "int sig" "sigset_t *mask" "u_long code" 372.Pp 373This function is provided by machine-dependent code, and is used to 374invoke a signal handler for the current process. 375.Fn sendsig 376must prepare the registers and stack of the current process to 377invoke the signal handler stored in the process's 378.Fa struct sigacts . 379This may include switching to an alternate signal 380stack specified by the process. The previous register, stack, 381and signal state are stored in a 382.Fa struct sigcontext , 383which is then copied out to the user's stack. 384.Pp 385The registers and stack must be set up to invoke the signal handler as 386follows: 387.Bd -literal -offset indent 388(*handler)(signum, code, scp) 389.Ed 390.Pp 391where 392.Fa signum 393is the signal number, 394.Fa code 395is a signal-specific code, and 396.Fa scp 397is the pointer to the 398.Fa struct sigcontext 399on the user's stack. The registers and stack must also 400arrange for the signal handler to return to the signal trampoline. 401The trampoline is then used to return to the code which was executing 402when the signal was delivered using the 403.Xr sigreturn 2 404system call. 405.Pp 406For performance reasons, it is recommended that 407.Fn sendsig 408arrange for the signal handler to be invoked directly on architectures 409where it is convenient to do so. In this case, the trampoline is used 410only for the signal return path. If it is not feasible to directly 411invoke the signal handler, the trampoline is also used to invoke the 412handler, performing any final set up that was not possible for 413.Fn sendsig 414to perform. 415.Pp 416.Fn sendsig 417must invoke the signal trampoline with the correct ABI. The ABI of 418the signal trampoline is specified on a per-signal basis in the 419.Fn sigacts 420structure for the process. Trampoline version 0 is reserved for the 421legacy kernel-provided, on-stack signal trampoline. All other trampoline 422versions indicate a specific trampoline ABI. This ABI is coordinated 423with machine-dependent code in the system C library. 424.El 425.Ss SIGNAL TRAMPOLINE 426The signal trampoline is a special piece of code which provides 427support for invoking the signal handlers for a process. The trampoline 428is used to return from the signal handler back to the code which was 429executing when the signal was delivered, and is also used to invoke the 430handler itself on architectures where it is not feasible to have the 431kernel invoke the handler directly. 432.Pp 433In traditional 434.Ux 435systems, the signal trampoline, also referred to as the 436.Dq sigcode , 437is provided by the kernel and copied to the top of the user's 438stack when a new process is created or a new program image is 439exec'd. Starting in 440.Nx 2.0 , 441the signal trampoline is provided by the system C library. This 442allows for more flexibility when the signal facility is extended, 443makes dealing with signals easier in debuggers, such as 444.Xr gdb 1 , 445and may also enhance system security by allowing the kernel to 446disallow execution of code on the stack. 447.Pp 448The signal trampoline is specified on a per-signal basis. The 449correct trampoline is selected automatically by the C library 450when a signal handler is registered by a process. 451.Pp 452Signal trampolines have a special naming convention which enables 453debuggers to determine the characteristics of the signal handler 454and its arguments. Trampoline functions are named like so: 455.Bd -literal -offset indent 456__sigtramp_\*[Lt]flavor\*[Gt]_\*[Lt]version\*[Gt] 457.Ed 458.Pp 459where: 460.Bl -tag -width versionXX 461.It \*[Lt]flavor\*[Gt] 462The flavor of the signal handler. The following flavors are valid: 463.Bl -tag -width sigcontextXX 464.It sigcontext 465Specifies a traditional BSD-style signal handler with the following 466signature: 467.Bd -literal 468void (*handler)(int signum, 469 int code, 470 struct sigcontext *scp); 471.Ed 472.It siginfo 473Specifies a POSIX-style signal handler with the following signature: 474.Bd -literal 475void (*handler)(int signum, 476 struct siginfo *si, 477 void *uc); 478.Ed 479.Pp 480Note: support for POSIX-style signal 481handlers is not yet implemented in the 482.Nx 483kernel. 484.El 485.It \*[Lt]version\*[Gt] 486Specifies the ABI version of the signal trampoline. The trampoline 487ABI is coordinated with the machine-dependent kernel 488.Fn sendsig 489function. 490.El 491.Pp 492The following is an example if a signal trampoline name which indicates 493that the trampoline is used for traditional BSD-style signal handlers 494and implements version 1 of the signal trampoline ABI: 495.Bd -literal -offset indent 496__sigtramp_sigcontext_1 497.Ed 498.Sh SEE ALSO 499.Xr sigaction 2 , 500.Xr signal 7 , 501.Xr tsleep 9 502