@node Signal Handling, Process Startup, Non-Local Exits, Top@chapter Signal Handling@cindex signalA @dfn{signal} is a software interrupt delivered to a process.  Theoperating system uses signals to report exceptional situations to anexecuting program.  Some signals report errors such as references toinvalid memory addresses; others report asynchronous events, such asdisconnection of a phone line.The GNU C library defines a variety of signal types, each for aparticular kind of event.  Some kinds of events make it inadvisable orimpossible for the program to proceed as usual, and the correspondingsignals normally abort the program.  Other kinds of signals that reportharmless events are ignored by default.If you anticipate an event that causes signals, you can define a handlerfunction and tell the operating system to run it when that particulartype of signal arrives.Finally, one process can send a signal to another process; this allows aparent process to abort a child, or two related processes to communicateand synchronize.@menu* Concepts of Signals::         Introduction to the signal facilities.* Standard Signals::            Particular kinds of signals with                                 standard names and meanings.* Signal Actions::              Specifying what happens when a                                 particular signal is delivered.* Defining Handlers::           How to write a signal handler function.* Interrupted Primitives::	Signal handlers affect use of @code{open},				 @code{read}, @code{write} and other functions.* Generating Signals::          How to send a signal to a process.* Blocking Signals::            Making the system hold signals temporarily.* Waiting for a Signal::        Suspending your program until a signal                                 arrives. * Signal Stack::                Using a Separate Signal Stack.* BSD Signal Handling::         Additional functions for backward			         compatibility with BSD.@end menu@node Concepts of Signals@section Basic Concepts of SignalsThis section explains basic concepts of how signals are generated, whathappens after a signal is delivered, and how programs can handlesignals.@menu* Kinds of Signals::            Some examples of what can cause a signal.* Signal Generation::           Concepts of why and how signals occur.* Delivery of Signal::          Concepts of what a signal does to the                                 process. @end menu@node Kinds of Signals@subsection Some Kinds of Signals A signal reports the occurrence of an exceptional event.  These are someof the events that can cause (or @dfn{generate}, or @dfn{raise}) asignal:@itemize @bullet@itemA program error such as dividing by zero or issuing an address outsidethe valid range.@itemA user request to interrupt or terminate the program.  Most environmentsare set up to let a user suspend the program by typing @kbd{C-z}, orterminate it with @kbd{C-c}.  Whatever key sequence is used, theoperating system sends the proper signal to interrupt the process.@itemThe termination of a child process.@itemExpiration of a timer or alarm.@itemA call to @code{kill} or @code{raise} by the same process.@itemA call to @code{kill} from another process.  Signals are a limited butuseful form of interprocess communication.@itemAn attempt to perform an I/O operation that cannot be done.  Examplesare reading from a pipe that has no writer (@pxref{Pipes and FIFOs}),and reading or writing to a terminal in certain situations (@pxref{JobControl}).@end itemizeEach of these kinds of events (excepting explicit calls to @code{kill}and @code{raise}) generates its own particular kind of signal.  Thevarious kinds of signals are listed and described in detail in@ref{Standard Signals}.@node Signal Generation@subsection Concepts of Signal Generation@cindex generation of signalsIn general, the events that generate signals fall into three majorcategories: errors, external events, and explicit requests.An error means that a program has done something invalid and cannotcontinue execution.  But not all kinds of errors generate signals---infact, most do not.  For example, opening a nonexistent file is an error,but it does not raise a signal; instead, @code{open} returns @code{-1}.In general, errors that are necessarily associated with certain libraryfunctions are reported by returning a value that indicates an error.The errors which raise signals are those which can happen anywhere inthe program, not just in library calls.  These include division by zeroand invalid memory addresses.An external event generally has to do with I/O or other processes.These include the arrival of input, the expiration of a timer, and thetermination of a child process.An explicit request means the use of a library function such as@code{kill} whose purpose is specifically to generate a signal.Signals may be generated @dfn{synchronously} or @dfn{asynchronously}.  Asynchronous signal pertains to a specific action in the program, and isdelivered (unless blocked) during that action.  Most errors generatesignals synchronously, and so do explicit requests by a process togenerate a signal for that same process.  On some machines, certainkinds of hardware errors (usually floating-point exceptions) are notreported completely synchronously, but may arrive a few instructionslater.Asynchronous signals are generated by events outside the control of theprocess that receives them.  These signals arrive at unpredictable timesduring execution.  External events generate signals asynchronously, andso do explicit requests that apply to some other process.A given type of signal is either typically synchrous or typicallyasynchronous.  For example, signals for errors are typically synchronousbecause errors generate signals synchronously.  But any type of signalcan be generated synchronously or asynchronously with an explicitrequest.@node Delivery of Signal@subsection How Signals Are Delivered@cindex delivery of signals@cindex pending signals@cindex blocked signalsWhen a signal is generated, it becomes @dfn{pending}.  Normally itremains pending for just a short period of time and then is@dfn{delivered} to the process that was signaled.  However, if that kindof signal is currently @dfn{blocked}, it may remain pendingindefinitely---until signals of that kind are @dfn{unblocked}.  Onceunblocked, it will be delivered immediately.  @xref{Blocking Signals}.@cindex specified action (for a signal)@cindex default action (for a signal)@cindex signal action@cindex catching signalsWhen the signal is delivered, whether right away or after a long delay,the @dfn{specified action} for that signal is taken.  For certainsignals, such as @code{SIGKILL} and @code{SIGSTOP}, the action is fixed,but for most signals, the program has a choice: ignore the signal,specify a @dfn{handler function}, or accept the @dfn{default action} forthat kind of signal.  The program specifies its choice using functionssuch as @code{signal} or @code{sigaction} (@pxref{Signal Actions}).  Wesometimes say that a handler @dfn{catches} the signal.  While thehandler is running, that particular signal is normally blocked.If the specified action for a kind of signal is to ignore it, then anysuch signal which is generated is discarded immediately.  This happenseven if the signal is also blocked at the time.  A signal discarded inthis way will never be delivered, not even if the program subsequentlyspecifies a different action for that kind of signal and then unblocksit.If a signal arrives which the program has neither handled nor ignored,its @dfn{default action} takes place.  Each kind of signal has its owndefault action, documented below (@pxref{Standard Signals}).  For most kindsof signals, the default action is to terminate the process.  For certainkinds of signals that represent ``harmless'' events, the default actionis to do nothing.When a signal terminates a process, its parent process can determine thecause of termination by examining the termination status code reportedby the @code{wait} or @code{waitpid} functions.  (This is discussed inmore detail in @ref{Process Completion}.)  The information it can getincludes the fact that termination was due to a signal, and the kind ofsignal involved.  If a program you run from a shell is terminated by asignal, the shell typically prints some kind of error message.The signals that normally represent program errors have a specialproperty: when one of these signals terminates the process, it alsowrites a @dfn{core dump file} which records the state of the process atthe time of termination.  You can examine the core dump with a debuggerto investigate what caused the error.If you raise a ``program error'' signal by explicit request, and thisterminates the process, it makes a core dump file just as if the signalhad been due directly to an error.@node Standard Signals@section Standard Signals@cindex signal names@cindex names of signals@pindex signal.h@cindex signal numberThis section lists the names for various standard kinds of signals anddescribes what kind of event they mean.  Each signal name is a macrowhich stands for a positive integer---the @dfn{signal number} for thatkind of signal.  Your programs should never make assumptions about thenumeric code for a particular kind of signal, but rather refer to themalways by the names defined here.  This is because the number for agiven kind of signal can vary from system to system, but the meanings ofthe names are standardized and fairly uniform.The signal names are defined in the header file @file{signal.h}.@comment signal.h@comment BSD@deftypevr Macro int NSIGThe value of this symbolic constant is the total number of signalsdefined.  Since the signal numbers are allocated consecutively,@code{NSIG} is also one greater than the largest defined signal number.@end deftypevr@menu* Program Error Signals::       Used to report serious program errors.* Termination Signals::         Used to interrupt and/or terminate the                                 program. * Alarm Signals::               Used to indicate expiration of timers.* Asynchronous I/O Signals::    Used to indicate input is available.* Job Control Signals::         Signals used to support job control.* Operation Error Signals::     Used to report operational system errors.* Miscellaneous Signals::       Miscellaneous Signals.* Signal Messages::             Printing a message describing a signal.@end menu@node Program Error Signals@subsection Program Error Signals@cindex program error signalsThe following signals are generated when a serious program error isdetected by the operating system or the computer itself.  In general,all of these signals are indications that your program is seriouslybroken in some way, and there's usually no way to continue thecomputation which encountered the error.Some programs handle program error signals in order to tidy up beforeterminating; for example, programs that turn off echoing of terminalinput should handle program error signals in order to turn echoing backon.  The handler should end by specifying the default action for thesignal that happened and then reraising it; this will cause the programto terminate with that signal, as if it had not had a handler.(@xref{Termination in Handler}.)Termination is the sensible ultimate outcome from a program error inmost programs.  However, programming systems such as Lisp that can loadcompiled user programs might need to keep executing even if a userprogram incurs an error.  These programs have handlers which use@code{longjmp} to return control to the command level.The default action for all of these signals is to cause the process toterminate.  If you block or ignore these signals or establish handlersfor them that return normally, your program will probably break horriblywhen such signals happen, unless they are generated by @code{raise} or@code{kill} instead of a real error.@vindex COREFILEWhen one of these program error signals terminates a process, it alsowrites a @dfn{core dump file} which records the state of the process atthe time of termination.  The core dump file is named @file{core} and iswritten in whichever directory is current in the process at the time.(On the GNU system, you can specify the file name for core dumps withthe environment variable @code{COREFILE}.)  The purpose of core dumpfiles is so that you can examine them with a debugger to investigatewhat caused the error.@comment signal.h@comment ANSI@deftypevr Macro int SIGFPEThe @code{SIGFPE} signal reports a fatal arithmetic error.  Although thename is derived from ``floating-point exception'', this signal actuallycovers all arithmetic errors, including division by zero and overflow.If a program stores integer data in a location which is then used in afloating-point operation, this often causes an ``invalid operation''exception, because the processor cannot recognize the data as afloating-point number.@cindex exception@cindex floating-point exceptionActual floating-point exceptions are a complicated subject because thereare many types of exceptions with subtly different meanings, and the@code{SIGFPE} signal doesn't distinguish between them.  The @cite{IEEEStandard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)}defines various floating-point exceptions and requires conformingcomputer systems to report their occurrences.  However, this standarddoes not specify how the exceptions are reported, or what kinds ofhandling and control the operating system can offer to the programmer.@end deftypevrBSD systems provide the @code{SIGFPE} handler with an extra argumentthat distinguishes various causes of the exception.  In order to accessthis argument, you must define the handler to accept two arguments,which means you must cast it to a one-argument function type in order toestablish the handler.  The GNU library does provide this extraargument, but the value is meaningful only on operating systems thatprovide the information (BSD systems and GNU systems).@table @code@comment signal.h@comment BSD@item FPE_INTOVF_TRAP@vindex FPE_INTOVF_TRAPInteger overflow (impossible in a C program unless you enable overflowtrapping in a hardware-specific fashion).@comment signal.h@comment BSD@item FPE_INTDIV_TRAP@vindex FPE_INTDIV_TRAPInteger division by zero.@comment signal.h@comment BSD@item FPE_SUBRNG_TRAP@vindex FPE_SUBRNG_TRAPSubscript-range (something that C programs never check for).@comment signal.h@comment BSD@item FPE_FLTOVF_TRAP@vindex FPE_FLTOVF_TRAPFloating overflow trap.@comment signal.h@comment BSD@item FPE_FLTDIV_TRAP@vindex FPE_FLTDIV_TRAPFloating/decimal division by zero.@comment signal.h@comment BSD@item FPE_FLTUND_TRAP@vindex FPE_FLTUND_TRAP