1.\" $NetBSD: signal.9,v 1.24 2017/07/03 21:28:48 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 April 29, 2010 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 pgsignal , 46.Nm kpgsignal , 47.Nm psignal , 48.Nm kpsignal , 49.Nm issignal , 50.Nm postsig , 51.Nm killproc , 52.Nm sigexit , 53.Nm trapsignal , 54.Nm sendsig , 55.Nm sigcode , 56.Nm sigtramp 57.Nd software signal facilities 58.Sh SYNOPSIS 59.In sys/signal.h 60.In sys/signalvar.h 61.Ft void 62.Fn siginit "struct proc *p" 63.Ft void 64.Fn sigactsinit "struct proc *pp" "int share" 65.Ft void 66.Fn sigactsunshare "struct proc *p" 67.Ft void 68.Fn sigactsfree "struct proc *p" 69.Ft void 70.Fn execsigs "struct proc *p" 71.Ft int 72.Fn sigaction1 "struct lwp *l" "int signum" "const struct sigaction *nsa" \ 73 "struct sigaction *osa" "void *tramp" "int vers" 74.Ft int 75.Fn sigprocmask1 "struct lwp *l" "int how" "const sigset_t *nss" \ 76 "sigset_t *oss" 77.Ft void 78.Fn sigpending1 "struct lwp *l" "sigset_t *ss" 79.Ft int 80.Fn sigsuspend1 "struct lwp *l" "const sigset_t *ss" 81.Ft int 82.Fn sigaltstack1 "struct lwp *l" "const struct sigaltstack *nss" \ 83 "struct sigaltstack *oss" 84.Ft void 85.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" 86.Ft void 87.Fn kpgsignal "struct pgrp *pgrp" "ksiginfo_t *ks" "void *data" "int checkctty" 88.Ft void 89.Fn psignal "struct proc *p" "int signum" 90.Ft void 91.Fn kpsignal "struct proc *p" "ksiginfo_t *ks" "void *data" 92.Ft int 93.Fn issignal "struct lwp *l" 94.Ft void 95.Fn postsig "int signum" 96.Ft void 97.Fn killproc "struct proc *p" "const char *why" 98.Ft void 99.Fn sigexit "struct lwp *l" "int signum" 100.Ft void 101.Fn trapsignal "struct lwp *l" "const ksiginfo_t *ks" 102.Ft void 103.Fn sendsig "const ksiginfo_t *ks" "const sigset_t *mask" 104.Sh DESCRIPTION 105The system defines a set of signals that may be delivered to a process. 106These functions implement the kernel portion of the signal facility. 107.Pp 108Signal numbers used throughout the kernel signal facilities should 109always be within the range of 110.Bq 1- Ns NSIG . 111.Pp 112Most of the kernel's signal infrastructure is implemented in 113machine-independent code. 114Machine-dependent code provides support for invoking a process's 115signal handler, restoring context when the signal handler returns, 116generating signals when hardware traps occur, triggering the delivery 117of signals when a process is about to return from the kernel to userspace. 118.Pp 119The signal state for a process is contained in 120.Fa struct sigctx . 121This includes the list of signals with delivery pending, 122information about the signal handler stack, the signal mask, and the 123address of the signal trampoline. 124.Pp 125The registered signal handlers for a process are recorded in 126.Fa struct sigacts . 127This structure may be shared by multiple processes. 128.Pp 129The kernel's signal facilities are implemented by the following 130functions: 131.Bl -tag -width XXXXX 132.It Fn siginit "p" 133.Pp 134This function initializes the signal state of 135.Va proc0 136to the system default. 137This signal state is then inherited by 138.Xr init 8 139when it is started by the kernel. 140.It Fn sigactsinit "pp" "share" 141.Pp 142This function creates an initial 143.Fa struct sigacts 144for the process 145.Fa pp . 146If the 147.Fa share 148argument is non-zero, then 149.Fa pp 150shares the 151.Fa struct sigacts 152by holding a reference. 153Otherwise, 154.Fa pp 155receives a new 156.Fa struct sigacts 157which is copied from the parent. 158.It Fn sigactsunshare "p" 159.Pp 160This function causes the process 161.Fa p 162to no longer share its 163.Fa struct sigacts 164The current state of the signal actions is maintained in the new copy. 165.It Fn sigactsfree "p" 166.Pp 167This function decrements the reference count on the 168.Fa struct sigacts 169of process 170.Fa p . 171If the reference count reaches zero, the 172.Fa struct sigacts 173is freed. 174.It Fn execsigs "p" 175.Pp 176This function is used to reset the signal state of the process 177.Fa p 178to the system defaults when the process execs a new program image. 179.It Fn sigaction1 "l" "signum" "nsa" "osa" "tramp" "vers" 180.Pp 181This function implements the 182.Xr sigaction 2 183system call. 184The 185.Fa tramp 186and 187.Fa vers 188arguments provide support for userspace signal trampolines. 189Trampoline version 0 is reserved for the legacy kernel-provided 190signal trampoline; 191.Fa tramp 192must be 193.Dv NULL 194in this case. 195Otherwise, 196.Fa vers 197specifies the ABI of the trampoline specified by 198.Fa tramp . 199The signal trampoline ABI is machine-dependent, and must be coordinated 200with the 201.Fn sendsig 202function. 203.It Fn sigprocmask1 "l" "how" "nss" "oss" 204.Pp 205This function implements the 206.Xr sigprocmask 2 207system call. 208.It Fn sigpending1 "l" "ss" 209.Pp 210This function implements the 211.Xr sigpending 2 212system call. 213.It Fn sigsuspend1 "l" "ss" 214.Pp 215This function implements the 216.Xr sigsuspend 2 217system call. 218.It Fn sigaltstack1 "l" "nss" "oss" 219.Pp 220This function implements the 221.Xr sigaltstack 2 222system call. 223.It Fn pgsignal "pgrp" "signum" "checkctty" 224.Pp 225This is a wrapper function for 226.Fn kpgsignal 227which is described below. 228.It Fn kpgsignal "pgrp" "ks" "data" "checkctty" 229.Pp 230Schedule the signal 231.Fa ks->ksi_signo 232to be delivered to all members of the process group 233.Fa pgrp . 234If 235.Fa checkctty 236is non-zero, the signal is only sent to processes which have a 237controlling terminal. 238The 239.Fa data 240argument and the complete signal scheduling semantics are described in the 241.Fn kpsignal 242function below. 243.It Fn trapsignal "l" "ks" 244.Pp 245Sends the signal 246.Fa ks->ksi_signo 247caused by a hardware trap to the current process. 248.\" 249.\" XXX: Check for reality in 2010. 250.\" 251.\" This function is meant to be called by machine-dependent trap handling 252.\" code, through the 253.\" .Dv p->p_emul->e_trapsignal 254.\" function pointer because some emulations define their own trapsignal 255.\" functions that remap the signal information to what the emulation 256.\" expects. 257.It Fn psignal "p" "signum" 258.Pp 259This is a wrapper function for 260.Fn kpsignal 261which is described below. 262.It Fn kpsignal "p" "ks" "data" 263.Pp 264Schedule the signal 265.Fa ks->ksi_signo 266to be delivered to the process 267.Fa p . 268The 269.Fa data 270argument, if not 271.Dv NULL , 272points to the file descriptor data that caused the 273signal to be generated in the 274.Li SIGIO 275case. 276.Pp 277With a few exceptions noted below, the target process signal disposition is 278updated and is marked as runnable, so further handling of the signal is done 279in the context of the target process after a context switch; see 280.Fn issignal 281below. 282Note that 283.Fn kpsignal 284does not by itself cause a context switch to happen. 285.Pp 286The target process is not marked as runnable in the following cases: 287.Bl -bullet -offset indent 288.It 289The target process is sleeping uninterruptibly. 290The signal will be noticed when the process returns from the system 291call or trap. 292.It 293The target process is currently ignoring the signal. 294.It 295If a stop signal is sent to a sleeping process that takes the 296default action 297.Pq see Xr sigaction 2 , 298the process is stopped without awakening it. 299.It 300SIGCONT 301restarts a stopped process 302.Pq or puts them back to sleep 303regardless of the signal action 304.Pq e.g., blocked or ignored . 305.El 306.Pp 307If the target process is being traced, 308.Fn kpsignal 309behaves as if the target process were taking the default action for 310.Fa signum . 311This allows the tracing process to be notified of the signal. 312.It Fn issignal "l" 313.Pp 314This function determines which signal, if any, 315is to be posted to the current process. 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 Fn postsig "signum" 340.Pp 341The 342.Fn postsig 343function is used to invoke the action for the signal 344.Fa signum 345in the current process. 346If the default action of a signal is to terminate the process, and the 347signal does not have a registered handler, the process exits using 348.Fn sigexit , 349dumping a core image if necessary. 350.It Fn killproc "p" "why" 351.Pp 352This function sends a SIGKILL signal to the specified process. 353The message provided by 354.Fa why 355is sent to the system log and is also displayed on the process's 356controlling terminal. 357.It Fn sigexit "l" "signum" 358.Pp 359This function forces the current process to exit with the signal 360.Fa signum , 361generating a core file if appropriate. 362No checks are made for masked or caught signals; the process always exits. 363.It Fn sendsig "ks" "mask" 364.Pp 365This function is provided by machine-dependent code, and is used to 366invoke a signal handler for the current process. 367.Fn sendsig 368must prepare the registers and stack of the current process to 369invoke the signal handler stored in the process's 370.Fa struct sigacts . 371This may include switching to an alternate signal 372stack specified by the process. 373The previous register, stack, and signal state are stored in a 374.Fa ucontext_t , 375which is then copied out to the user's stack. 376.Pp 377The registers and stack must be set up to invoke the signal handler as 378follows: 379.Bd -literal -offset indent 380(*handler)(int signum, siginfo_t *info, void *ctx) 381.Ed 382.Pp 383where 384.Fa signum 385is the signal number, 386.Fa info 387contains additional signal specific information when 388.Li SA_SIGINFO 389is specified when setting up the signal handler. 390.Fa ctx 391is the pointer to 392.Fa ucontext_t 393on the user's stack. 394The registers and stack must also arrange for the signal handler to 395return to the signal trampoline. 396The trampoline is then used to return to the code which was executing 397when the signal was delivered using the 398.Xr setcontext 2 399system call. 400.Pp 401For performance reasons, it is recommended that 402.Fn sendsig 403arrange for the signal handler to be invoked directly on architectures 404where it is convenient to do so. 405In this case, the trampoline is used only for the signal return path. 406If it is not feasible to directly invoke the signal handler, the 407trampoline is also used to invoke the handler, performing any final 408set up that was not possible for 409.Fn sendsig 410to perform. 411.Pp 412.Fn sendsig 413must invoke the signal trampoline with the correct ABI. 414The ABI of the signal trampoline is specified on a per-signal basis in the 415.Fn sigacts 416structure for the process. 417Trampoline version 0 is reserved for the legacy kernel-provided, 418on-stack signal trampoline. 419All other trampoline versions indicate a specific trampoline ABI. 420This ABI is coordinated with machine-dependent code in the system 421C library. 422.El 423.Ss SIGNAL TRAMPOLINE 424The signal trampoline is a special piece of code which provides 425support for invoking the signal handlers for a process. 426The trampoline is used to return from the signal handler back to the 427code which was executing when the signal was delivered, and is also used 428to invoke the handler itself on architectures where it is not feasible to 429have the kernel invoke the handler directly. 430.Pp 431In traditional 432.Ux 433systems, the signal trampoline, also referred to as the 434.Dq sigcode , 435is provided by the kernel and copied to the top of the user's 436stack when a new process is created or a new program image is 437exec'd. 438Starting in 439.Nx 2.0 , 440the signal trampoline is provided by the system C library. 441This allows for more flexibility when the signal facility is extended, 442makes dealing with signals easier in debuggers, such as 443.Xr gdb 1 , 444and may also enhance system security by allowing the kernel to 445disallow execution of code on the stack. 446.Pp 447The signal trampoline is specified on a per-signal basis. 448The correct trampoline is selected automatically by the C library 449when a signal handler is registered by a process. 450.Pp 451Signal trampolines have a special naming convention which enables 452debuggers to determine the characteristics of the signal handler 453and its arguments. 454Trampoline functions are named like so: 455.Bd -literal -offset indent 456__sigtramp_<flavor>_<version> 457.Ed 458.Pp 459where: 460.Bl -tag -width versionXX 461.It Aq flavor 462The flavor of the signal handler. 463The following flavors are valid: 464.Bl -tag -width sigcontextXX 465.It sigcontext 466Specifies a traditional BSD-style (deprecated) signal handler with the 467following signature: 468.Bd -literal 469void (*handler)(int signum, 470 int code, 471 struct sigcontext *scp); 472.Ed 473.It siginfo 474Specifies a POSIX-style signal handler with the following signature: 475.Bd -literal 476void (*handler)(int signum, 477 siginfo_t *si, 478 void *uc); 479.Ed 480.Pp 481Note: sigcontext style signal handlers are deprecated, and retained only 482for compatibility with older binaries. 483.El 484.It Aq version 485Specifies the ABI version of the signal trampoline. 486The trampoline ABI is coordinated with the machine-dependent kernel 487.Fn sendsig 488function. 489The trampoline version needs to be unique even across different trampoline 490flavors, in order to simplify trampoline selection in the kernel. 491.El 492.Pp 493The following is an example if a signal trampoline name which indicates 494that the trampoline is used for traditional BSD-style signal handlers 495and implements version 1 of the signal trampoline ABI: 496.Bd -literal -offset indent 497__sigtramp_sigcontext_1 498.Ed 499.Pp 500The current signal trampoline is: 501.Bd -literal -offset indent 502__sigtramp_siginfo_2 503.Ed 504.Sh SEE ALSO 505.Xr sigaction 2 , 506.Xr signal 7 , 507.Xr condvar 9 508