lib/libc/sys/sigaction.2

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  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, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)sigaction.2   8.2 (Berkeley) 4/3/94
  33 .\" $FreeBSD: src/lib/libc/sys/sigaction.2,v 1.22.2.10 2002/12/29 16:35:34 schweikh Exp $
  34 .\"
  35 .Dd April 3, 1994
  36 .Dt SIGACTION 2
  37 .Os
  38 .Sh NAME
  39 .Nm sigaction
  40 .Nd software signal facilities
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In signal.h
  45 .Bd -literal
  46 struct sigaction {
  47         /*
  48          * Signal handler function if flag SA_SIGINFO is not used and for
  49          * SIG_DFL and SIG_IGN.
  50          */
  51         void     (*sa_handler)(int);
  52
  53         /* Signal handler function if flag SA_SIGINFO is used */
  54         void     (*sa_sigaction)(int, siginfo_t *, void *);
  55
  56         sigset_t sa_mask;            /* signal mask to apply */
  57         int      sa_flags;           /* see signal options below */
  58 };
  59 .Ed
  60 .Ft int
  61 .Fn sigaction "int sig" "const struct sigaction *act" "struct sigaction *oact"
  62 .Sh DESCRIPTION
  63 The system defines a set of signals that may be delivered to a process.
  64 Signal delivery resembles the occurrence of a hardware interrupt:
  65 the signal is normally blocked from further occurrence, the current process
  66 context is saved, and a new one is built.  A process may specify a
  67 .Em handler
  68 to which a signal is delivered, or specify that a signal is to be
  69 .Em ignored .
  70 A process may also specify that a default action is to be taken
  71 by the system when a signal occurs.
  72 A signal may also be
  73 .Em blocked ,
  74 in which case its delivery is postponed until it is
  75 .Em unblocked .
  76 The action to be taken on delivery is determined at the time
  77 of delivery.
  78 Normally, signal handlers execute on the current stack
  79 of the process.  This may be changed, on a per-handler basis,
  80 so that signals are taken on a special
  81 .Em "signal stack" .
  82 .Pp
  83 Signal routines normally execute with the signal that caused their
  84 invocation
  85 .Em blocked ,
  86 but other signals may yet occur.
  87 A global
  88 .Em "signal mask"
  89 defines the set of signals currently blocked from delivery
  90 to a process.  The signal mask for a process is initialized
  91 from that of its parent (normally empty).  It
  92 may be changed with a
  93 .Xr sigprocmask 2
  94 call, or when a signal is delivered to the process.
  95 .Pp
  96 When a signal
  97 condition arises for a process, the signal is added to a set of
  98 signals pending for the process.
  99 If the signal is not currently
 100 .Em blocked
 101 by the process then it is delivered to the process.
 102 Signals may be delivered any time a process enters the operating system
 103 (e.g., during a system call, page fault or trap, or clock interrupt).
 104 If multiple signals are ready to be delivered at the same time,
 105 any signals that could be caused by traps are delivered first.
 106 Additional signals may be processed at the same time, with each
 107 appearing to interrupt the handlers for the previous signals
 108 before their first instructions.
 109 The set of pending signals is returned by the
 110 .Xr sigpending 2
 111 function.
 112 When a caught signal
 113 is delivered, the current state of the process is saved,
 114 a new signal mask is calculated (as described below),
 115 and the signal handler is invoked.  The call to the handler
 116 is arranged so that if the signal handling routine returns
 117 normally the process will resume execution in the context
 118 from before the signal's delivery.
 119 If the process wishes to resume in a different context, then it
 120 must arrange to restore the previous context itself.
 121 .Pp
 122 When a signal is delivered to a process a new signal mask is
 123 installed for the duration of the process' signal handler
 124 (or until a
 125 .Xr sigprocmask
 126 call is made).
 127 This mask is formed by taking the union of the current signal mask set,
 128 the signal to be delivered, and
 129 the signal mask associated with the handler to be invoked.
 130 .Pp
 131 .Fn Sigaction
 132 assigns an action for a signal specified by
 133 .Fa sig .
 134 If
 135 .Fa act
 136 is non-zero, it
 137 specifies an action
 138 .Pf ( Dv SIG_DFL ,
 139 .Dv SIG_IGN ,
 140 or a handler routine) and mask
 141 to be used when delivering the specified signal.
 142 If
 143 .Fa oact
 144 is non-zero, the previous handling information for the signal
 145 is returned to the user.
 146 .Pp
 147 Once a signal handler is installed, it normally remains installed
 148 until another
 149 .Fn sigaction
 150 call is made, or an
 151 .Xr execve 2
 152 is performed.
 153 A signal-specific default action may be reset by
 154 setting
 155 .Fa sa_handler
 156 to
 157 .Dv SIG_DFL .
 158 The defaults are process termination, possibly with core dump;
 159 no action; stopping the process; or continuing the process.
 160 See the signal list below for each signal's default action.
 161 If
 162 .Fa sa_handler
 163 is
 164 .Dv SIG_DFL ,
 165 the default action for the signal is to discard the signal,
 166 and if a signal is pending,
 167 the pending signal is discarded even if the signal is masked.
 168 If
 169 .Fa sa_handler
 170 is set to
 171 .Dv SIG_IGN
 172 current and pending instances
 173 of the signal are ignored and discarded.
 174 .Pp
 175 Options may be specified by setting
 176 .Em sa_flags .
 177 The meaning of the various bits is as follows:
 178 .Bl -tag -offset indent -width SA_RESETHANDXX
 179 .It Dv SA_NOCLDSTOP
 180 If this bit is set when installing a catching function
 181 for the
 182 .Dv SIGCHLD
 183 signal,
 184 the
 185 .Dv SIGCHLD
 186 signal will be generated only when a child process exits,
 187 not when a child process stops.
 188 .It Dv SA_NOCLDWAIT
 189 If this bit is set when calling
 190 .Fn sigaction
 191 for the
 192 .Dv SIGCHLD
 193 signal, the system will not create zombie processes when children of
 194 the calling process exit.  If the calling process subsequently issues
 195 a
 196 .Xr wait 2
 197 (or equivalent), it blocks until all of the calling process's child
 198 processes terminate, and then returns a value of -1 with errno set to
 199 .Er ECHILD .
 200 .It Dv SA_ONSTACK
 201 If this bit is set, the system will deliver the signal to the process
 202 on a
 203 .Em "signal stack" ,
 204 specified with
 205 .Xr sigaltstack 2 .
 206 .It Dv SA_NODEFER
 207 If this bit is set, further occurrences of the delivered signal are
 208 not masked during the execution of the handler.
 209 .It Dv SA_RESETHAND
 210 If this bit is set, the handler is reset back to
 211 .Dv SIG_DFL
 212 at the moment the signal is delivered.
 213 .It Dv SA_SIGINFO
 214 If this bit is set, the handler function is assumed to be pointed to by the
 215 .Dv sa_sigaction
 216 member of struct sigaction and should match the prototype shown above or as
 217 below in
 218 .Sx EXAMPLES .
 219 This bit should not be set when assigning
 220 .Dv SIG_DFL
 221 or
 222 .Dv SIG_IGN .
 223 .El
 224 .Pp
 225 If a signal is caught during the system calls listed below,
 226 the call may be forced to terminate
 227 with the error
 228 .Er EINTR ,
 229 the call may return with a data transfer shorter than requested,
 230 or the call may be restarted.
 231 Restart of pending calls is requested
 232 by setting the
 233 .Dv SA_RESTART
 234 bit in
 235 .Ar sa_flags .
 236 The affected system calls include
 237 .Xr open 2 ,
 238 .Xr read 2 ,
 239 .Xr write 2 ,
 240 .Xr sendto 2 ,
 241 .Xr recvfrom 2 ,
 242 .Xr sendmsg 2
 243 and
 244 .Xr recvmsg 2
 245 on a communications channel or a slow device (such as a terminal,
 246 but not a regular file)
 247 and during a
 248 .Xr wait 2
 249 or
 250 .Xr ioctl 2 .
 251 However, calls that have already committed are not restarted,
 252 but instead return a partial success (for example, a short read count).
 253 .Pp
 254 After a
 255 .Xr fork 2
 256 or
 257 .Xr vfork 2
 258 all signals, the signal mask, the signal stack,
 259 and the restart/interrupt flags are inherited by the child.
 260 .Pp
 261 .Xr Execve 2
 262 reinstates the default
 263 action for all signals which were caught and
 264 resets all signals to be caught on the user stack.
 265 Ignored signals remain ignored;
 266 the signal mask remains the same;
 267 signals that restart pending system calls continue to do so.
 268 .Pp
 269 The following is a list of all signals
 270 with names as in the include file
 271 .Aq Pa signal.h :
 272 .Bl -column SIGVTALARMXX "create core imagexxx"
 273 .It Sy "NAME    Default Action  Description"
 274 .It Dv SIGHUP No "      terminate process" "    terminal line hangup"
 275 .It Dv SIGINT No "      terminate process" "    interrupt program"
 276 .It Dv SIGQUIT No "     create core image" "    quit program"
 277 .It Dv SIGILL No "      create core image" "    illegal instruction"
 278 .It Dv SIGTRAP No "     create core image" "    trace trap"
 279 .It Dv SIGABRT No "     create core image" Ta Xr abort 3
 280 call (formerly
 281 .Dv SIGIOT )
 282 .It Dv SIGEMT No "      create core image" "    emulate instruction executed"
 283 .It Dv SIGFPE No "      create core image" "    floating-point exception"
 284 .It Dv SIGKILL No "     terminate process" "    kill program"
 285 .It Dv SIGBUS No "      create core image" "    bus error"
 286 .It Dv SIGSEGV No "     create core image" "    segmentation violation"
 287 .It Dv SIGSYS No "      create core image" "    non-existent system call invoked"
 288 .It Dv SIGPIPE No "     terminate process" "    write on a pipe with no reader"
 289 .It Dv SIGALRM No "     terminate process" "    real-time timer expired"
 290 .It Dv SIGTERM No "     terminate process" "    software termination signal"
 291 .It Dv SIGURG No "      discard signal" "       urgent condition present on socket"
 292 .It Dv SIGSTOP No "     stop process" " stop (cannot be caught or ignored)"
 293 .It Dv SIGTSTP No "     stop process" " stop signal generated from keyboard"
 294 .It Dv SIGCONT No "     discard signal" "       continue after stop"
 295 .It Dv SIGCHLD No "     discard signal" "       child status has changed"
 296 .It Dv SIGTTIN No "     stop process" " background read attempted from control terminal"
 297 .It Dv SIGTTOU No "     stop process" " background write attempted to control terminal"
 298 .It Dv SIGIO No "       discard signal" Tn "    I/O"
 299 is possible on a descriptor (see
 300 .Xr fcntl 2 )
 301 .It Dv SIGXCPU No "     terminate process" "    cpu time limit exceeded (see"
 302 .Xr setrlimit 2 )
 303 .It Dv SIGXFSZ No "     terminate process" "    file size limit exceeded (see"
 304 .Xr setrlimit 2 )
 305 .It Dv SIGVTALRM No "   terminate process" "    virtual time alarm (see"
 306 .Xr setitimer 2 )
 307 .It Dv SIGPROF No "     terminate process" "    profiling timer alarm (see"
 308 .Xr setitimer 2 )
 309 .It Dv SIGWINCH No "    discard signal" "       Window size change"
 310 .It Dv SIGINFO No "     discard signal" "       status request from keyboard"
 311 .It Dv SIGUSR1 No "     terminate process" "    User defined signal 1"
 312 .It Dv SIGUSR2 No "     terminate process" "    User defined signal 2"
 313 .El
 314 .Sh NOTE
 315 The
 316 .Fa sa_mask
 317 field specified in
 318 .Fa act
 319 is not allowed to block
 320 .Dv SIGKILL
 321 or
 322 .Dv SIGSTOP .
 323 Any attempt to do so will be silently ignored.
 324 .Pp
 325 The following functions are either reentrant or not interruptible
 326 by signals and are async-signal safe.
 327 Therefore applications may
 328 invoke them, without restriction, from signal-catching functions:
 329 .Pp
 330 Base Interfaces:
 331 .Pp
 332 .Fn _exit ,
 333 .Fn access ,
 334 .Fn alarm ,
 335 .Fn cfgetispeed ,
 336 .Fn cfgetospeed ,
 337 .Fn cfsetispeed ,
 338 .Fn cfsetospeed ,
 339 .Fn chdir ,
 340 .Fn chmod ,
 341 .Fn chown ,
 342 .Fn close ,
 343 .Fn creat ,
 344 .Fn dup ,
 345 .Fn dup2 ,
 346 .Fn execle ,
 347 .Fn execve ,
 348 .Fn fcntl ,
 349 .Fn fork ,
 350 .Fn fpathconf ,
 351 .Fn fstat ,
 352 .Fn fsync ,
 353 .Fn getegid ,
 354 .Fn geteuid ,
 355 .Fn getgid ,
 356 .Fn getgroups ,
 357 .Fn getpgrp ,
 358 .Fn getpid ,
 359 .Fn getppid ,
 360 .Fn getuid ,
 361 .Fn kill ,
 362 .Fn link ,
 363 .Fn lseek ,
 364 .Fn mkdir ,
 365 .Fn mkfifo ,
 366 .Fn open ,
 367 .Fn pathconf ,
 368 .Fn pause ,
 369 .Fn pipe ,
 370 .Fn raise ,
 371 .Fn read ,
 372 .Fn rename ,
 373 .Fn rmdir ,
 374 .Fn setgid ,
 375 .Fn setpgid ,
 376 .Fn setsid ,
 377 .Fn setuid ,
 378 .Fn sigaction ,
 379 .Fn sigaddset ,
 380 .Fn sigdelset ,
 381 .Fn sigemptyset ,
 382 .Fn sigfillset  ,
 383 .Fn sigismember ,
 384 .Fn signal ,
 385 .Fn sigpending ,
 386 .Fn sigprocmask ,
 387 .Fn sigsuspend ,
 388 .Fn sleep ,
 389 .Fn stat ,
 390 .Fn sysconf ,
 391 .Fn tcdrain ,
 392 .Fn tcflow ,
 393 .Fn tcflush ,
 394 .Fn tcgetattr ,
 395 .Fn tcgetpgrp ,
 396 .Fn tcsendbreak ,
 397 .Fn tcsetattr ,
 398 .Fn tcsetpgrp ,
 399 .Fn time ,
 400 .Fn times ,
 401 .Fn umask ,
 402 .Fn uname ,
 403 .Fn unlink ,
 404 .Fn utime ,
 405 .Fn wait ,
 406 .Fn waitpid ,
 407 .Fn write .
 408 .Pp
 409 Realtime Interfaces:
 410 .Pp
 411 .Fn aio_error ,
 412 .Fn clock_gettime ,
 413 .Fn sigpause ,
 414 .Fn timer_getoverrun ,
 415 .Fn aio_return ,
 416 .Fn fdatasync ,
 417 .Fn sigqueue ,
 418 .Fn timer_gettime ,
 419 .Fn aio_suspend ,
 420 .Fn sem_post ,
 421 .Fn sigset ,
 422 .Fn timer_settime .
 423 .Pp
 424 All functions not in the above lists are considered to be unsafe
 425 with respect to signals.  That is to say, the behaviour of such
 426 functions when called from a signal handler is undefined.
 427 .Sh RETURN VALUES
 428 .Rv -std sigaction
 429 .Sh EXAMPLES
 430 There are three possible prototypes the handler may match:
 431 .Bl -tag -offset indent -width short
 432 .It ANSI C:
 433 .Ft void
 434 .Fn handler int ;
 435 .It Traditional BSD style:
 436 .Ft void
 437 .Fn handler int "int code" "struct sigcontext *scp" ;
 438 .It POSIX SA_SIGINFO:
 439 .Ft void
 440 .Fn handler int "siginfo_t *info" "ucontext_t *uap" ;
 441 .El
 442 .Pp
 443 The handler function should match the SA_SIGINFO prototype if the
 444 SA_SIGINFO bit is set in flags.
 445 It then should be pointed to by the
 446 .Dv sa_sigaction
 447 member of
 448 .Dv struct sigaction .
 449 Note that you should not assign SIG_DFL or SIG_IGN this way.
 450 .Pp
 451 If the SA_SIGINFO flag is not set, the handler function should match
 452 either the ANSI C or traditional
 453 .Bx
 454 prototype and be pointed to by
 455 the
 456 .Dv sa_handler
 457 member of
 458 .Dv struct sigaction .
 459 In practice,
 460 .Fx
 461 always sends the three arguments of the latter and since the ANSI C
 462 prototype is a subset, both will work.
 463 The
 464 .Dv sa_handler
 465 member declaration in
 466 .Fx
 467 include files is that of ANSI C (as required by POSIX),
 468 so a function pointer of a
 469 .Bx Ns -style
 470 function needs to be casted to
 471 compile without warning.
 472 The traditional
 473 .Bx
 474 style is not portable and since its capabilities
 475 are a full subset of a SA_SIGINFO handler,
 476 its use is deprecated.
 477 .Pp
 478 The
 479 .Fa sig
 480 argument is the signal number, one of the
 481 .Dv SIG...
 482 values from <signal.h>.
 483 .Pp
 484 The
 485 .Fa code
 486 argument of the
 487 .Bx Ns -style
 488 handler and the
 489 .Dv si_code
 490 member of the
 491 .Dv info
 492 argument to a SA_SIGINFO handler contain a numeric code explaining the
 493 cause of the signal, usually one of the
 494 .Dv SI_...
 495 values from
 496 <sys/signal.h> or codes specific to a signal, i.e. one of the
 497 .Dv FPE_...
 498 values for SIGFPE.
 499 .Pp
 500 The
 501 .Fa scp
 502 argument to a
 503 .Bx Ns -style
 504 handler points to an instance of struct
 505 sigcontext.
 506 .Pp
 507 The
 508 .Fa uap
 509 argument to a POSIX SA_SIGINFO handler points to an instance of
 510 ucontext_t.
 511 .Sh ERRORS
 512 .Fn Sigaction
 513 will fail and no new signal handler will be installed if one
 514 of the following occurs:
 515 .Bl -tag -width Er
 516 .It Bq Er EFAULT
 517 Either
 518 .Fa act
 519 or
 520 .Fa oact
 521 points to memory that is not a valid part of the process
 522 address space.
 523 .It Bq Er EINVAL
 524 .Fa Sig
 525 is not a valid signal number.
 526 .It Bq Er EINVAL
 527 An attempt is made to ignore or supply a handler for
 528 .Dv SIGKILL
 529 or
 530 .Dv SIGSTOP .
 531 .El
 532 .Sh STANDARDS
 533 The
 534 .Fn sigaction
 535 function call is expected to conform to
 536 .St -p1003.1-90 .
 537 The
 538 .Dv SA_ONSTACK
 539 and
 540 .Dv SA_RESTART
 541 flags are Berkeley extensions,
 542 as are the signals,
 543 .Dv SIGTRAP ,
 544 .Dv SIGEMT ,
 545 .Dv SIGBUS ,
 546 .Dv SIGSYS ,
 547 .Dv SIGURG ,
 548 .Dv SIGIO ,
 549 .Dv SIGXCPU ,
 550 .Dv SIGXFSZ ,
 551 .Dv SIGVTALRM ,
 552 .Dv SIGPROF ,
 553 .Dv SIGWINCH ,
 554 and
 555 .Dv SIGINFO .
 556 Those signals are available on most
 557 .Bx Ns \-derived
 558 systems.
 559 The
 560 .Dv SA_NODEFER
 561 and
 562 .Dv SA_RESETHAND
 563 flags are intended for backwards compatibility with other operating
 564 systems.  The
 565 .Dv SA_NOCLDSTOP ,
 566 and
 567 .Dv SA_NOCLDWAIT
 568 .\" and
 569 .\" SA_SIGINFO
 570 flags are featuring options commonly found in other operating systems.
 571 .Sh SEE ALSO
 572 .Xr kill 1 ,
 573 .Xr kill 2 ,
 574 .Xr ptrace 2 ,
 575 .Xr sigaltstack 2 ,
 576 .Xr sigblock 2 ,
 577 .Xr sigpause 2 ,
 578 .Xr sigpending 2 ,
 579 .Xr sigprocmask 2 ,
 580 .Xr sigsetmask 2 ,
 581 .Xr sigsuspend 2 ,
 582 .Xr sigvec 2 ,
 583 .Xr wait 2 ,
 584 .Xr fpsetmask 3 ,
 585 .Xr setjmp 3 ,
 586 .Xr siginterrupt 3 ,
 587 .Xr sigsetops 3 ,
 588 .Xr ucontext 3 ,
 589 .Xr tty 4