lib/libc/gen/signal.3

   1 .\" Copyright (c) 1980, 1991, 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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)signal.3    8.3 (Berkeley) 4/19/94
  29 .\" $FreeBSD: src/lib/libc/gen/signal.3,v 1.17.2.9 2003/03/13 18:05:37 trhodes Exp $
  30 .\"
  31 .Dd April 19, 1994
  32 .Dt SIGNAL 3
  33 .Os
  34 .Sh NAME
  35 .Nm signal
  36 .Nd simplified software signal facilities
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In signal.h
  41 .\" The following is Quite Ugly, but syntactically correct.  Don't try to
  42 .\" fix it.
  43 .Ft void
  44 .Fn (*signal "int sig" "void (*func)(int)))(int"
  45 .Pp
  46 or in
  47 .Dx Ns 's
  48 equivalent but easier to read typedef'd version:
  49 .Ft typedef "void (*sig_t) (int)" ;
  50 .Ft sig_t
  51 .Fn signal "int sig" "sig_t func"
  52 .Sh DESCRIPTION
  53 This
  54 .Fn signal
  55 facility
  56 is a simplified interface to the more general
  57 .Xr sigaction 2
  58 facility.
  59 .Pp
  60 Signals allow the manipulation of a process from outside its
  61 domain as well as allowing the process to manipulate itself or
  62 copies of itself (children).
  63 There are two general types of signals:
  64 those that cause termination of a process and those that do not.
  65 Signals which cause termination of a program might result from
  66 an irrecoverable error or might be the result of a user at a terminal
  67 typing the `interrupt' character.
  68 Signals are used when a process is stopped because it wishes to access
  69 its control terminal while in the background (see
  70 .Xr tty 4 ) .
  71 Signals are optionally generated
  72 when a process resumes after being stopped,
  73 when the status of child processes changes,
  74 or when input is ready at the control terminal.
  75 Most signals result in the termination of the process receiving them
  76 if no action
  77 is taken; some signals instead cause the process receiving them
  78 to be stopped, or are simply discarded if the process has not
  79 requested otherwise.
  80 Except for the
  81 .Dv SIGKILL
  82 and
  83 .Dv SIGSTOP
  84 signals, the
  85 .Fn signal
  86 function allows for a signal to be caught, to be ignored, or to generate
  87 an interrupt.
  88 These signals are defined in the file
  89 .In signal.h :
  90 .Bl -column SIGCKPTEXITXX "create core imagexxx"
  91 .It Sy NAME Ta Sy Default Action Ta Sy Description
  92 .It Dv SIGHUP Ta terminate process Ta terminal line hangup
  93 .It Dv SIGINT Ta terminate process Ta interrupt program
  94 .It Dv SIGQUIT Ta create core image Ta quit program
  95 .It Dv SIGILL Ta create core image Ta illegal instruction
  96 .It Dv SIGTRAP Ta create core image Ta trace trap
  97 .It Dv SIGABRT Ta create core image Ta abort program (formerly Dv SIGIOT )
  98 .It Dv SIGEMT Ta create core image Ta emulate instruction executed
  99 .It Dv SIGFPE Ta create core image Ta floating-point exception
 100 .It Dv SIGKILL Ta terminate process Ta kill program
 101 .It Dv SIGBUS Ta create core image Ta bus error
 102 .It Dv SIGSEGV Ta create core image Ta segmentation violation
 103 .It Dv SIGSYS Ta create core image Ta non-existent system call invoked
 104 .It Dv SIGPIPE Ta terminate process Ta write on a pipe with no reader
 105 .It Dv SIGALRM Ta terminate process Ta real-time timer expired
 106 .It Dv SIGTERM Ta terminate process Ta software termination signal
 107 .It Dv SIGURG Ta discard signal Ta urgent condition present on socket
 108 .It Dv SIGSTOP Ta stop process Ta stop (cannot be caught or ignored)
 109 .It Dv SIGTSTP Ta stop process Ta stop signal generated from keyboard
 110 .It Dv SIGCONT Ta discard signal Ta continue after stop
 111 .It Dv SIGCHLD Ta discard signal Ta child status has changed
 112 .It Dv SIGTTIN Ta stop process Ta background read attempted from control terminal
 113 .It Dv SIGTTOU Ta stop process Ta background write attempted to control terminal
 114 .It Dv SIGIO Ta discard signal Ta I/O is possible on a descriptor (see Xr fcntl 2 )
 115 .It Dv SIGXCPU Ta terminate process Ta cpu time limit exceeded (see Xr setrlimit 2 )
 116 .It Dv SIGXFSZ Ta terminate process Ta file size limit exceeded (see Xr setrlimit 2 )
 117 .It Dv SIGVTALRM Ta terminate process Ta virtual time alarm (see Xr setitimer 2 )
 118 .It Dv SIGPROF Ta terminate process Ta profiling timer alarm (see Xr setitimer 2 )
 119 .It Dv SIGWINCH Ta discard signal Ta window size change
 120 .It Dv SIGINFO Ta discard signal Ta status request from keyboard
 121 .It Dv SIGUSR1 Ta terminate process Ta user defined signal 1
 122 .It Dv SIGUSR2 Ta terminate process Ta user defined signal 2
 123 .It Dv SIGCKPT Ta checkpoint process Ta checkpoint
 124 .It Dv SIGCKPTEXIT Ta terminate process Ta checkpoint and exit
 125 .El
 126 .Pp
 127 The
 128 .Fa sig
 129 argument specifies which signal was received.
 130 The
 131 .Fa func
 132 procedure allows a user to choose the action upon receipt of a signal.
 133 To set the default action of the signal to occur as listed above,
 134 .Fa func
 135 should be
 136 .Dv SIG_DFL .
 137 A
 138 .Dv SIG_DFL
 139 resets the default action.
 140 To ignore the signal
 141 .Fa func
 142 should be
 143 .Dv SIG_IGN .
 144 This will cause subsequent instances of the signal to be ignored
 145 and pending instances to be discarded.
 146 If
 147 .Dv SIG_IGN
 148 is not used,
 149 further occurrences of the signal are
 150 automatically blocked and
 151 .Fa func
 152 is called.
 153 .Pp
 154 The handled signal is unblocked when the
 155 function returns and
 156 the process continues from where it left off when the signal occurred.
 157 .Bf -symbolic
 158 Unlike previous signal facilities, the handler
 159 func() remains installed after a signal has been delivered.
 160 .Ef
 161 .Pp
 162 For some system calls, if a signal is caught while the call is
 163 executing and the call is prematurely terminated,
 164 the call is automatically restarted.
 165 (The handler is installed using the
 166 .Dv SA_RESTART
 167 flag with
 168 .Xr sigaction 2 . )
 169 The affected system calls include
 170 .Xr read 2 ,
 171 .Xr write 2 ,
 172 .Xr sendto 2 ,
 173 .Xr recvfrom 2 ,
 174 .Xr sendmsg 2
 175 and
 176 .Xr recvmsg 2
 177 on a communications channel or a low speed device
 178 and during a
 179 .Xr ioctl 2
 180 or
 181 .Xr wait 2 .
 182 However, calls that have already committed are not restarted,
 183 but instead return a partial success (for example, a short read count).
 184 These semantics could be changed with
 185 .Xr siginterrupt 3 .
 186 .Pp
 187 When a process which has installed signal handlers forks,
 188 the child process inherits the signals.
 189 All caught signals may be reset to their default action by a call
 190 to the
 191 .Xr execve 2
 192 function;
 193 ignored signals remain ignored.
 194 .Pp
 195 See
 196 .Xr sigaction 2
 197 for a list of functions
 198 that are considered safe for use in signal handlers.
 199 .Sh RETURN VALUES
 200 The previous action is returned on a successful call.
 201 Otherwise,
 202 .Dv SIG_ERR
 203 is returned and  the global variable
 204 .Va errno
 205 is set to indicate the error.
 206 .Sh ERRORS
 207 The
 208 .Fn signal
 209 function
 210 will fail and no action will take place if one of the
 211 following occur:
 212 .Bl -tag -width Er
 213 .It Bq Er EINVAL
 214 The
 215 .Fa sig
 216 argument
 217 is not a valid signal number.
 218 .It Bq Er EINVAL
 219 An attempt is made to ignore or supply a handler for
 220 .Dv SIGKILL
 221 or
 222 .Dv SIGSTOP .
 223 .El
 224 .Sh SEE ALSO
 225 .Xr kill 1 ,
 226 .Xr kill 2 ,
 227 .Xr ptrace 2 ,
 228 .Xr sigaction 2 ,
 229 .Xr sigaltstack 2 ,
 230 .Xr sigprocmask 2 ,
 231 .Xr sigsuspend 2 ,
 232 .Xr fpsetmask 3 ,
 233 .Xr setjmp 3 ,
 234 .Xr siginterrupt 3 ,
 235 .Xr tty 4
 236 .Sh HISTORY
 237 This
 238 .Fn signal
 239 facility appeared in
 240 .Bx 4.0 .