1.\" $NetBSD: signal.9,v 1.19 2009/05/04 19:42:40 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 20, 2005 31.Dt SIGNAL 9 32.Os 33.Sh NAME 34.Nm signal , 35.Nm siginit , 36.Nm sigactsinit , 37.Nm sigactsunshare , 38.Nm sigactsfree , 39.Nm execsigs , 40.Nm sigaction1 , 41.Nm sigprocmask1 , 42.Nm sigpending1 , 43.Nm sigsuspend1 , 44.Nm sigaltstack1 , 45.Nm gsignal , 46.Nm pgsignal , 47.Nm psignal , 48.Nm sched_psignal , 49.Nm issignal , 50.Nm postsig , 51.Nm killproc , 52.Nm sigexit , 53.Nm sigmasked , 54.Nm trapsignal , 55.Nm sendsig , 56.Nm sigcode , 57.Nm sigtramp 58.Nd software signal facilities 59.Sh SYNOPSIS 60.In sys/signal.h 61.In sys/signalvar.h 62.Ft void 63.Fn siginit "struct proc *p" 64.Ft void 65.Fn sigactsinit "struct proc *np" "struct proc *pp" "int share" 66.Ft void 67.Fn sigactsunshare "struct proc *p" 68.Ft void 69.Fn sigactsfree "struct proc *p" 70.Ft void 71.Fn execsigs "struct proc *p" 72.Ft int 73.Fn sigaction1 "struct proc *p" "int signum" "const struct sigaction *nsa" \ 74 "struct sigaction *osa" "void *tramp" "int vers" 75.Ft int 76.Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \ 77 "sigset_t *oss" 78.Ft void 79.Fn sigpending1 "struct proc *p" "sigset_t *ss" 80.Ft int 81.Fn sigsuspend1 "struct proc *p" "const sigset_t *ss" 82.Ft int 83.Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \ 84 "struct sigaltstack *oss" 85.Ft void 86.Fn gsignal "int pgid" "int signum" 87.Ft void 88.Fn kgsignal "int pgid" "ksiginfo_t *ks" "void *data" 89.Ft void 90.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" 91.Ft void 92.Fn kpgsignal "struct pgrp *pgrp" "ksiginfo_t *ks" "void *data" "int checkctty" 93.Ft void 94.Fn psignal "struct proc *p" "int signum" 95.Ft void 96.Fn kpsignal "struct proc *p" "ksiginfo_t *ks" "void *data" 97.Ft void 98.Fn sched_psignal "struct proc *p" "int signum" 99.Ft int 100.Fn issignal "struct lwp *l" 101.Ft void 102.Fn postsig "int signum" 103.Ft void 104.Fn killproc "struct proc *p" "const char *why" 105.Ft void 106.Fn sigexit "struct proc *p" "int signum" 107.Ft int 108.Fn sigmasked "struct proc *p" "int signum" 109.Ft void 110.Fn trapsignal "struct proc *p" "const ksiginfo_t *ks" 111.Ft void 112.Fn sendsig "const ksiginfo_t *ks" "const sigset_t *mask" 113.Sh DESCRIPTION 114The system defines a set of signals that may be delivered to a process. 115These functions implement the kernel portion of the signal facility. 116.Pp 117Signal numbers used throughout the kernel signal facilities should 118always be within the range of 119.Bq 1- Ns NSIG . 120.Pp 121Most of the kernel's signal infrastructure is implemented in 122machine-independent code. 123Machine-dependent code provides support for invoking a process's 124signal handler, restoring context when the signal handler returns, 125generating signals when hardware traps occur, triggering the delivery 126of signals when a process is about to return from the kernel to userspace. 127.Pp 128The signal state for a process is contained in 129.Fa struct sigctx . 130This includes the list of signals with delivery pending, 131information about the signal handler stack, the signal mask, and the 132address of the signal trampoline. 133.Pp 134The registered signal handlers for a process are recorded in 135.Fa struct sigacts . 136This structure may be shared by multiple processes. 137.Pp 138The kernel's signal facilities are implemented by the following 139functions: 140.Bl -tag -width XXXXX 141.It void Fn siginit "struct proc *p" 142.Pp 143This function initializes the signal state of 144.Va proc0 145to the system default. 146This 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 170.No non- Ns Dv 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 208.Dv NULL 209in this case. 210Otherwise, 211.Fa vers 212specifies the ABI of the trampoline specified by 213.Fa tramp . 214The signal trampoline ABI is machine-dependent, and must be coordinated 215with the 216.Fn sendsig 217function. 218.It int Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \ 219 "sigset_t *oss" 220.Pp 221This function implements the 222.Xr sigprocmask 2 223system call. 224.It void Fn sigpending1 "struct proc *p" "sigset_t *ss" 225.Pp 226This function implements the 227.Xr sigpending 2 228system call. 229.It int Fn sigsuspend1 "struct proc *p" "const sigset_t *ss" 230.Pp 231This function implements the 232.Xr sigsuspend 2 233system call. 234.It int Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \ 235 "struct sigaltstack *oss" 236.Pp 237This function implements the 238.Xr sigaltstack 2 239system call. 240.It void Fn gsignal "int pgid" "int signum" 241.Pp 242This is a wrapper function for 243.Fn kgsignal 244which is described below. 245.It void Fn kgsignal "int pgid" "ksiginfo_t *ks" "void *data" 246.Pp 247Schedule the signal 248.Fa ks-\*[Gt]ksi_signo 249to be delivered to all members of the process group specified by 250.Fa pgid . 251The 252.Fa data 253argument and the complete signal scheduling semantics are described in the 254.Fn kpsignal 255function below. 256below for a complete description of the signal scheduling semantics. 257.It void Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" 258.Pp 259This is a wrapper function for 260.Fn kpgsignal 261which is described below. 262.It void Fn kpgsignal "struct pgrp *pgrp" "ksiginfo_t *ks" "void *data" "int checkctty" 263.Pp 264Schedule the signal 265.Fa ks-\*[Gt]ksi_signo 266to be delivered to all members of the process group 267.Fa pgrp . 268If 269.Fa checkctty 270is non-zero, the signal is only sent to processes which have a 271controlling terminal. 272The 273.Fa data 274argument and the complete signal scheduling semantics are described in the 275.Fn kpsignal 276function below. 277.It void Fn trapsignal "struct proc *p" "const ksiginfo_t *ks" 278.Pp 279Sends the signal 280.Fa ks-\*[Gt]ksi_signo 281caused by a hardware trap to the process 282.Fa p . 283This function is meant to be called by machine-dependent trap handling 284code, through the 285.Dv p-\*[Gt]p_emul-\*[Gt]e_trapsignal 286function pointer because some emulations define their own trapsignal 287functions that remap the signal information to what the emulation 288expects. 289.It void Fn psignal "struct proc *p" "int signum" 290.Pp 291This is a wrapper function for 292.Fn kpsignal 293which is described below. 294.It void Fn kpsignal "struct proc *p" "ksiginfo_t *ks" "void *data" 295.Pp 296Schedule the signal 297.Fa ks-\*[Gt]ksi_signo 298to be delivered to the process 299.Fa p . 300The 301.Fa data 302argument, if not 303.Dv NULL , 304points to the file descriptor data that caused the 305signal to be generated in the 306.Li SIGIO 307case. 308.Pp 309With a few exceptions noted below, the target process signal disposition is 310updated and is marked as runnable, so further handling of the signal is done 311in the context of the target process after a context switch; see 312.Fn issignal 313below. 314Note that 315.Fn kpsignal 316does not by itself cause a context switch to happen. 317.Pp 318The target process is not marked as runnable in the following cases: 319.Bl -bullet -offset indent 320.It 321The target process is sleeping uninterruptibly. 322The signal will be noticed when the process returns from the system 323call or trap. 324.It 325The target process is currently ignoring the signal. 326.It 327If a stop signal is sent to a sleeping process that takes the 328default action 329.Pq see Xr sigaction 2 , 330the process is stopped without awakening it. 331.It 332SIGCONT 333restarts a stopped process 334.Pq or puts them back to sleep 335regardless of the signal action 336.Pq e.g., blocked or ignored . 337.El 338.Pp 339If the target process is being traced, 340.Fn kpsignal 341behaves as if the target process were taking the default action for 342.Fa signum . 343This allows the tracing process to be notified of the signal. 344.It void Fn sched_psignal "struct proc *p" "int signum" 345.Pp 346An alternate version of 347.Fn kpsignal 348which is intended for use by code which holds the scheduler lock. 349.It int Fn issignal "struct lwp *l" 350.Pp 351This function determines which signal, if any, is to be posted to 352the process 353.Fa p . 354A signal is to be posted if: 355.Bl -bullet -offset indent 356.It 357The signal has a handler provided by the program image. 358.It 359The signal should cause the process to dump core and/or terminate. 360.It 361The signal should interrupt the current system call. 362.El 363.Pp 364Signals which cause the process to be stopped are handled within 365.Fn issignal 366directly. 367.Pp 368.Fn issignal 369should be called by machine-dependent code when returning to 370userspace from a system call or other trap or interrupt by 371using the following code: 372.Bd -literal -offset indent 373while (signum = CURSIG(curproc)) 374 postsig(signum); 375.Ed 376.Pp 377.It void Fn postsig "int signum" 378.Pp 379The 380.Fn postsig 381function is used to invoke the action for the signal 382.Fa signum 383in the current process. 384If the default action of a signal is to terminate the process, and the 385signal does not have a registered handler, the process exits using 386.Fn sigexit , 387dumping a core image if necessary. 388.It void Fn killproc "struct proc *p" "const char *why" 389.Pp 390This function sends a SIGKILL signal to the specified process. 391The message provided by 392.Fa why 393is sent to the system log and is also displayed on the process's 394controlling terminal. 395.It void Fn sigexit "struct proc *p" "int signum" 396.Pp 397This function forces the process 398.Fa p 399to exit with the signal 400.Fa signum , 401generating a core file if appropriate. 402No checks are made for masked or caught signals; the process always exits. 403.It int Fn sigmasked "struct proc *p" "int signum" 404.Pp 405This function returns non-zero if the signal specified by 406.Fa signum 407is ignored or masked for process 408.Fa p . 409.It void Fn sendsig "const ksiginfo_t *ks" "const sigset_t *mask" 410.Pp 411This function is provided by machine-dependent code, and is used to 412invoke a signal handler for the current process. 413.Fn sendsig 414must prepare the registers and stack of the current process to 415invoke the signal handler stored in the process's 416.Fa struct sigacts . 417This may include switching to an alternate signal 418stack specified by the process. 419The previous register, stack, and signal state are stored in a 420.Fa ucontext_t , 421which is then copied out to the user's stack. 422.Pp 423The registers and stack must be set up to invoke the signal handler as 424follows: 425.Bd -literal -offset indent 426(*handler)(int signum, siginfo_t *info, void *ctx) 427.Ed 428.Pp 429where 430.Fa signum 431is the signal number, 432.Fa info 433contains additional signal specific information when 434.Li SA_SIGINFO 435is specified when setting up the signal handler. 436.Fa ctx 437is the pointer to 438.Fa ucontext_t 439on the user's stack. 440The registers and stack must also arrange for the signal handler to 441return to the signal trampoline. 442The trampoline is then used to return to the code which was executing 443when the signal was delivered using the 444.Xr setcontext 2 445system call. 446.Pp 447For performance reasons, it is recommended that 448.Fn sendsig 449arrange for the signal handler to be invoked directly on architectures 450where it is convenient to do so. 451In this case, the trampoline is used only for the signal return path. 452If it is not feasible to directly invoke the signal handler, the 453trampoline is also used to invoke the handler, performing any final 454set up that was not possible for 455.Fn sendsig 456to perform. 457.Pp 458.Fn sendsig 459must invoke the signal trampoline with the correct ABI. 460The ABI of the signal trampoline is specified on a per-signal basis in the 461.Fn sigacts 462structure for the process. 463Trampoline version 0 is reserved for the legacy kernel-provided, 464on-stack signal trampoline. 465All other trampoline versions indicate a specific trampoline ABI. 466This ABI is coordinated with machine-dependent code in the system 467C library. 468.El 469.Ss SIGNAL TRAMPOLINE 470The signal trampoline is a special piece of code which provides 471support for invoking the signal handlers for a process. 472The trampoline is used to return from the signal handler back to the 473code which was executing when the signal was delivered, and is also used 474to invoke the handler itself on architectures where it is not feasible to 475have the kernel invoke the handler directly. 476.Pp 477In traditional 478.Ux 479systems, the signal trampoline, also referred to as the 480.Dq sigcode , 481is provided by the kernel and copied to the top of the user's 482stack when a new process is created or a new program image is 483exec'd. 484Starting in 485.Nx 2.0 , 486the signal trampoline is provided by the system C library. 487This allows for more flexibility when the signal facility is extended, 488makes dealing with signals easier in debuggers, such as 489.Xr gdb 1 , 490and may also enhance system security by allowing the kernel to 491disallow execution of code on the stack. 492.Pp 493The signal trampoline is specified on a per-signal basis. 494The correct trampoline is selected automatically by the C library 495when a signal handler is registered by a process. 496.Pp 497Signal trampolines have a special naming convention which enables 498debuggers to determine the characteristics of the signal handler 499and its arguments. 500Trampoline functions are named like so: 501.Bd -literal -offset indent 502__sigtramp_\*[Lt]flavor\*[Gt]_\*[Lt]version\*[Gt] 503.Ed 504.Pp 505where: 506.Bl -tag -width versionXX 507.It Aq flavor 508The flavor of the signal handler. 509The following flavors are valid: 510.Bl -tag -width sigcontextXX 511.It sigcontext 512Specifies a traditional BSD-style (deprecated) signal handler with the 513following signature: 514.Bd -literal 515void (*handler)(int signum, 516 int code, 517 struct sigcontext *scp); 518.Ed 519.It siginfo 520Specifies a POSIX-style signal handler with the following signature: 521.Bd -literal 522void (*handler)(int signum, 523 siginfo_t *si, 524 void *uc); 525.Ed 526.Pp 527Note: sigcontext style signal handlers are deprecated, and retained only 528for compatibility with older binaries. 529.El 530.It Aq version 531Specifies the ABI version of the signal trampoline. 532The trampoline ABI is coordinated with the machine-dependent kernel 533.Fn sendsig 534function. 535The trampoline version needs to be unique even across different trampoline 536flavors, in order to simplify trampoline selection in the kernel. 537.El 538.Pp 539The following is an example if a signal trampoline name which indicates 540that the trampoline is used for traditional BSD-style signal handlers 541and implements version 1 of the signal trampoline ABI: 542.Bd -literal -offset indent 543__sigtramp_sigcontext_1 544.Ed 545.Pp 546The current signal trampoline is: 547.Bd -literal -offset indent 548__sigtramp_siginfo_2 549.Ed 550.Sh SEE ALSO 551.Xr sigaction 2 , 552.Xr signal 7 , 553.Xr condvar 9 554