initial import

1 files changed, 3316 insertions, 0 deletions

diff --git a/manual/signal.texi b/manual/signal.texi
new file mode 100644
index 0000000000..bca02c528b
--- /dev/null
+++ b/manual/signal.texi
@@ -0,0 +1,3316 @@
+@node Signal Handling, Process Startup, Non-Local Exits, Top
+@chapter Signal Handling
+
+@cindex signal
+A @dfn{signal} is a software interrupt delivered to a process.  The
+operating system uses signals to report exceptional situations to an
+executing program.  Some signals report errors such as references to
+invalid memory addresses; others report asynchronous events, such as
+disconnection of a phone line.
+
+The GNU C library defines a variety of signal types, each for a
+particular kind of event.  Some kinds of events make it inadvisable or
+impossible for the program to proceed as usual, and the corresponding
+signals normally abort the program.  Other kinds of signals that report
+harmless events are ignored by default.
+
+If you anticipate an event that causes signals, you can define a handler
+function and tell the operating system to run it when that particular
+type of signal arrives.
+
+Finally, one process can send a signal to another process; this allows a
+parent process to abort a child, or two related processes to communicate
+and 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 Signals
+
+This section explains basic concepts of how signals are generated, what
+happens after a signal is delivered, and how programs can handle
+signals.
+
+@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 some
+of the events that can cause (or @dfn{generate}, or @dfn{raise}) a
+signal:
+
+@itemize @bullet
+@item
+A program error such as dividing by zero or issuing an address outside
+the valid range.
+
+@item
+A user request to interrupt or terminate the program.  Most environments
+are set up to let a user suspend the program by typing @kbd{C-z}, or
+terminate it with @kbd{C-c}.  Whatever key sequence is used, the
+operating system sends the proper signal to interrupt the process.
+
+@item
+The termination of a child process.
+
+@item
+Expiration of a timer or alarm.
+
+@item
+A call to @code{kill} or @code{raise} by the same process.
+
+@item
+A call to @code{kill} from another process.  Signals are a limited but
+useful form of interprocess communication.
+
+@item
+An attempt to perform an I/O operation that cannot be done.  Examples
+are reading from a pipe that has no writer (@pxref{Pipes and FIFOs}),
+and reading or writing to a terminal in certain situations (@pxref{Job
+Control}).
+@end itemize
+
+Each of these kinds of events (excepting explicit calls to @code{kill}
+and @code{raise}) generates its own particular kind of signal.  The
+various kinds of signals are listed and described in detail in
+@ref{Standard Signals}.
+
+@node Signal Generation
+@subsection Concepts of Signal Generation
+@cindex generation of signals
+
+In general, the events that generate signals fall into three major
+categories: errors, external events, and explicit requests.
+
+An error means that a program has done something invalid and cannot
+continue execution.  But not all kinds of errors generate signals---in
+fact, 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 library
+functions are reported by returning a value that indicates an error.
+The errors which raise signals are those which can happen anywhere in
+the program, not just in library calls.  These include division by zero
+and 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 the
+termination 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}.  A
+synchronous signal pertains to a specific action in the program, and is
+delivered (unless blocked) during that action.  Most errors generate
+signals synchronously, and so do explicit requests by a process to
+generate a signal for that same process.  On some machines, certain
+kinds of hardware errors (usually floating-point exceptions) are not
+reported completely synchronously, but may arrive a few instructions
+later.
+
+Asynchronous signals are generated by events outside the control of the
+process that receives them.  These signals arrive at unpredictable times
+during execution.  External events generate signals asynchronously, and
+so do explicit requests that apply to some other process.
+
+A given type of signal is either typically synchrous or typically
+asynchronous.  For example, signals for errors are typically synchronous
+because errors generate signals synchronously.  But any type of signal
+can be generated synchronously or asynchronously with an explicit
+request.
+
+@node Delivery of Signal
+@subsection How Signals Are Delivered
+@cindex delivery of signals
+@cindex pending signals
+@cindex blocked signals
+
+When a signal is generated, it becomes @dfn{pending}.  Normally it
+remains pending for just a short period of time and then is
+@dfn{delivered} to the process that was signaled.  However, if that kind
+of signal is currently @dfn{blocked}, it may remain pending
+indefinitely---until signals of that kind are @dfn{unblocked}.  Once
+unblocked, 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 signals
+When the signal is delivered, whether right away or after a long delay,
+the @dfn{specified action} for that signal is taken.  For certain
+signals, 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} for
+that kind of signal.  The program specifies its choice using functions
+such as @code{signal} or @code{sigaction} (@pxref{Signal Actions}).  We
+sometimes say that a handler @dfn{catches} the signal.  While the
+handler is running, that particular signal is normally blocked.
+
+If the specified action for a kind of signal is to ignore it, then any
+such signal which is generated is discarded immediately.  This happens
+even if the signal is also blocked at the time.  A signal discarded in
+this way will never be delivered, not even if the program subsequently
+specifies a different action for that kind of signal and then unblocks
+it.
+
+If a signal arrives which the program has neither handled nor ignored,
+its @dfn{default action} takes place.  Each kind of signal has its own
+default action, documented below (@pxref{Standard Signals}).  For most kinds
+of signals, the default action is to terminate the process.  For certain
+kinds of signals that represent ``harmless'' events, the default action
+is to do nothing.
+
+When a signal terminates a process, its parent process can determine the
+cause of termination by examining the termination status code reported
+by the @code{wait} or @code{waitpid} functions.  (This is discussed in
+more detail in @ref{Process Completion}.)  The information it can get
+includes the fact that termination was due to a signal, and the kind of
+signal involved.  If a program you run from a shell is terminated by a
+signal, the shell typically prints some kind of error message.
+
+The signals that normally represent program errors have a special
+property: when one of these signals terminates the process, it also
+writes a @dfn{core dump file} which records the state of the process at
+the time of termination.  You can examine the core dump with a debugger
+to investigate what caused the error.
+
+If you raise a ``program error'' signal by explicit request, and this
+terminates the process, it makes a core dump file just as if the signal
+had been due directly to an error.
+
+@node Standard Signals
+@section Standard Signals
+@cindex signal names
+@cindex names of signals
+
+@pindex signal.h
+@cindex signal number
+This section lists the names for various standard kinds of signals and
+describes what kind of event they mean.  Each signal name is a macro
+which stands for a positive integer---the @dfn{signal number} for that
+kind of signal.  Your programs should never make assumptions about the
+numeric code for a particular kind of signal, but rather refer to them
+always by the names defined here.  This is because the number for a
+given kind of signal can vary from system to system, but the meanings of
+the 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 NSIG
+The value of this symbolic constant is the total number of signals
+defined.  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 signals
+
+The following signals are generated when a serious program error is
+detected by the operating system or the computer itself.  In general,
+all of these signals are indications that your program is seriously
+broken in some way, and there's usually no way to continue the
+computation which encountered the error.
+
+Some programs handle program error signals in order to tidy up before
+terminating; for example, programs that turn off echoing of terminal
+input should handle program error signals in order to turn echoing back
+on.  The handler should end by specifying the default action for the
+signal that happened and then reraising it; this will cause the program
+to 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 in
+most programs.  However, programming systems such as Lisp that can load
+compiled user programs might need to keep executing even if a user
+program 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 to
+terminate.  If you block or ignore these signals or establish handlers
+for them that return normally, your program will probably break horribly
+when such signals happen, unless they are generated by @code{raise} or
+@code{kill} instead of a real error.
+
+@vindex COREFILE
+When one of these program error signals terminates a process, it also
+writes a @dfn{core dump file} which records the state of the process at
+the time of termination.  The core dump file is named @file{core} and is
+written in whichever directory is current in the process at the time.
+(On the GNU system, you can specify the file name for core dumps with
+the environment variable @code{COREFILE}.)  The purpose of core dump
+files is so that you can examine them with a debugger to investigate
+what caused the error.
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro int SIGFPE
+The @code{SIGFPE} signal reports a fatal arithmetic error.  Although the
+name is derived from ``floating-point exception'', this signal actually
+covers all arithmetic errors, including division by zero and overflow.
+If a program stores integer data in a location which is then used in a
+floating-point operation, this often causes an ``invalid operation''
+exception, because the processor cannot recognize the data as a
+floating-point number.
+@cindex exception
+@cindex floating-point exception
+
+Actual floating-point exceptions are a complicated subject because there
+are many types of exceptions with subtly different meanings, and the
+@code{SIGFPE} signal doesn't distinguish between them.  The @cite{IEEE
+Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)}
+defines various floating-point exceptions and requires conforming
+computer systems to report their occurrences.  However, this standard
+does not specify how the exceptions are reported, or what kinds of
+handling and control the operating system can offer to the programmer.
+@end deftypevr
+
+BSD systems provide the @code{SIGFPE} handler with an extra argument
+that distinguishes various causes of the exception.  In order to access
+this argument, you must define the handler to accept two arguments,
+which means you must cast it to a one-argument function type in order to
+establish the handler.  The GNU library does provide this extra
+argument, but the value is meaningful only on operating systems that
+provide the information (BSD systems and GNU systems).
+
+@table @code
+@comment signal.h
+@comment BSD
+@item FPE_INTOVF_TRAP
+@vindex FPE_INTOVF_TRAP
+Integer overflow (impossible in a C program unless you enable overflow
+trapping in a hardware-specific fashion).
+@comment signal.h
+@comment BSD
+@item FPE_INTDIV_TRAP
+@vindex FPE_INTDIV_TRAP
+Integer division by zero.
+@comment signal.h
+@comment BSD
+@item FPE_SUBRNG_TRAP
+@vindex FPE_SUBRNG_TRAP
+Subscript-range (something that C programs never check for).
+@comment signal.h
+@comment BSD
+@item FPE_FLTOVF_TRAP
+@vindex FPE_FLTOVF_TRAP
+Floating overflow trap.
+@comment signal.h
+@comment BSD
+@item FPE_FLTDIV_TRAP
+@vindex FPE_FLTDIV_TRAP
+Floating/decimal division by zero.
+@comment signal.h
+@comment BSD
+@item FPE_FLTUND_TRAP
+@vindex FPE_FLTUND_TRAP
+Floating underflow trap.  (Trapping on floating underflow is not
+normally enabled.)
+@comment signal.h
+@comment BSD
+@item FPE_DECOVF_TRAP
+@vindex FPE_DECOVF_TRAP
+Decimal overflow trap.  (Only a few machines have decimal arithmetic and
+C never uses it.)
+@ignore @c These seem redundant
+@comment signal.h
+@comment BSD
+@item FPE_FLTOVF_FAULT
+@vindex FPE_FLTOVF_FAULT
+Floating overflow fault.
+@comment signal.h
+@comment BSD
+@item FPE_FLTDIV_FAULT
+@vindex FPE_FLTDIV_FAULT
+Floating divide by zero fault.
+@comment signal.h
+@comment BSD
+@item FPE_FLTUND_FAULT
+@vindex FPE_FLTUND_FAULT
+Floating underflow fault.
+@end ignore
+@end table
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro int SIGILL
+The name of this signal is derived from ``illegal instruction''; it
+usually means your program is trying to execute garbage or a privileged
+instruction.  Since the C compiler generates only valid instructions,
+@code{SIGILL} typically indicates that the executable file is corrupted,
+or that you are trying to execute data.  Some common ways of getting
+into the latter situation are by passing an invalid object where a
+pointer to a function was expected, or by writing past the end of an
+automatic array (or similar problems with pointers to automatic
+variables) and corrupting other data on the stack such as the return
+address of a stack frame.
+
+@code{SIGILL} can also be generated when the stack overflows, or when
+the system has trouble running the handler for a signal.
+@end deftypevr
+@cindex illegal instruction
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro int SIGSEGV
+@cindex segmentation violation
+This signal is generated when a program tries to read or write outside
+the memory that is allocated for it, or to write memory that can only be
+read.  (Actually, the signals only occur when the program goes far
+enough outside to be detected by the system's memory protection
+mechanism.)  The name is an abbreviation for ``segmentation violation''.
+
+Common ways of getting a @code{SIGSEGV} condition include dereferencing
+a null or uninitialized pointer, or when you use a pointer to step
+through an array, but fail to check for the end of the array.  It varies
+among systems whether dereferencing a null pointer generates
+@code{SIGSEGV} or @code{SIGBUS}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGBUS
+This signal is generated when an invalid pointer is dereferenced.  Like
+@code{SIGSEGV}, this signal is typically the result of dereferencing an
+uninitialized pointer.  The difference between the two is that
+@code{SIGSEGV} indicates an invalid access to valid memory, while
+@code{SIGBUS} indicates an access to an invalid address.  In particular,
+@code{SIGBUS} signals often result from dereferencing a misaligned
+pointer, such as referring to a four-word integer at an address not
+divisible by four.  (Each kind of computer has its own requirements for
+address alignment.)
+
+The name of this signal is an abbreviation for ``bus error''.
+@end deftypevr
+@cindex bus error
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro int SIGABRT
+@cindex abort signal
+This signal indicates an error detected by the program itself and
+reported by calling @code{abort}.  @xref{Aborting a Program}.
+@end deftypevr
+
+@comment signal.h
+@comment Unix
+@deftypevr Macro int SIGIOT
+Generated by the PDP-11 ``iot'' instruction.  On most machines, this is
+just another name for @code{SIGABRT}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGTRAP
+Generated by the machine's breakpoint instruction, and possibly other
+trap instructions.  This signal is used by debuggers.  Your program will
+probably only see @code{SIGTRAP} if it is somehow executing bad
+instructions.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int  SIGEMT
+Emulator trap; this results from certain unimplemented instructions
+which might be emulated in software, or the operating system's
+failure to properly emulate them.
+@end deftypevr
+
+@comment signal.h
+@comment Unix
+@deftypevr Macro int  SIGSYS
+Bad system call; that is to say, the instruction to trap to the
+operating system was executed, but the code number for the system call
+to perform was invalid.
+@end deftypevr
+
+@node Termination Signals
+@subsection Termination Signals
+@cindex program termination signals
+
+These signals are all used to tell a process to terminate, in one way
+or another.  They have different names because they're used for slightly
+different purposes, and programs might want to handle them differently.
+
+The reason for handling these signals is usually so your program can
+tidy up as appropriate before actually terminating.  For example, you
+might want to save state information, delete temporary files, or restore
+the previous terminal modes.  Such a handler should end by specifying
+the default action for the signal that happened and then reraising it;
+this will cause the program to terminate with that signal, as if it had
+not had a handler.  (@xref{Termination in Handler}.)
+
+The (obvious) default action for all of these signals is to cause the
+process to terminate.
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro int SIGTERM
+@cindex termination signal
+The @code{SIGTERM} signal is a generic signal used to cause program
+termination.  Unlike @code{SIGKILL}, this signal can be blocked,
+handled, and ignored.  It is the normal way to politely ask a program to
+terminate.
+
+The shell command @code{kill} generates @code{SIGTERM} by default.
+@pindex kill
+@end deftypevr
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro int SIGINT
+@cindex interrupt signal
+The @code{SIGINT} (``program interrupt'') signal is sent when the user
+types the INTR character (normally @kbd{C-c}).  @xref{Special
+Characters}, for information about terminal driver support for
+@kbd{C-c}.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGQUIT
+@cindex quit signal
+@cindex quit signal
+The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's
+controlled by a different key---the QUIT character, usually
+@kbd{C-\}---and produces a core dump when it terminates the process,
+just like a program error signal.  You can think of this as a
+program error condition ``detected'' by the user.
+
+@xref{Program Error Signals}, for information about core dumps.
+@xref{Special Characters}, for information about terminal driver
+support.
+
+Certain kinds of cleanups are best omitted in handling @code{SIGQUIT}.
+For example, if the program creates temporary files, it should handle
+the other termination requests by deleting the temporary files.  But it
+is better for @code{SIGQUIT} not to delete them, so that the user can
+examine them in conjunction with the core dump.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGKILL
+The @code{SIGKILL} signal is used to cause immediate program termination.
+It cannot be handled or ignored, and is therefore always fatal.  It is
+also not possible to block this signal.
+
+This signal is usually generated only by explicit request.  Since it
+cannot be handled, you should generate it only as a last resort, after
+first trying a less drastic method such as @kbd{C-c} or @code{SIGTERM}.
+If a process does not respond to any other termination signals, sending
+it a @code{SIGKILL} signal will almost always cause it to go away.
+
+In fact, if @code{SIGKILL} fails to terminate a process, that by itself
+constitutes an operating system bug which you should report.
+
+The system will generate @code{SIGKILL} for a process itself under some
+unusual conditions where the program cannot possible continue to run
+(even to run a signal handler).
+@end deftypevr
+@cindex kill signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGHUP
+@cindex hangup signal
+The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
+terminal is disconnected, perhaps because a network or telephone
+connection was broken.  For more information about this, see @ref{Control
+Modes}.
+
+This signal is also used to report the termination of the controlling
+process on a terminal to jobs associated with that session; this
+termination effectively disconnects all processes in the session from
+the controlling terminal.  For more information, see @ref{Termination
+Internals}.
+@end deftypevr
+
+@node Alarm Signals
+@subsection Alarm Signals
+
+These signals are used to indicate the expiration of timers.
+@xref{Setting an Alarm}, for information about functions that cause
+these signals to be sent.
+
+The default behavior for these signals is to cause program termination.
+This default is rarely useful, but no other default would be useful;
+most of the ways of using these signals would require handler functions
+in any case.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGALRM
+This signal typically indicates expiration of a timer that measures real
+or clock time.  It is used by the @code{alarm} function, for example.
+@end deftypevr
+@cindex alarm signal
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGVTALRM
+This signal typically indicates expiration of a timer that measures CPU
+time used by the current process.  The name is an abbreviation for
+``virtual time alarm''.
+@end deftypevr
+@cindex virtual time alarm signal
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGPROF
+This signal is typically indicates expiration of a timer that measures
+both CPU time used by the current process, and CPU time expended on 
+behalf of the process by the system.  Such a timer is used to implement
+code profiling facilities, hence the name of this signal.
+@end deftypevr
+@cindex profiling alarm signal
+
+
+@node Asynchronous I/O Signals
+@subsection Asynchronous I/O Signals
+
+The signals listed in this section are used in conjunction with
+asynchronous I/O facilities.  You have to take explicit action by
+calling @code{fcntl} to enable a particular file descriptior to generate
+these signals (@pxref{Interrupt Input}).  The default action for these
+signals is to ignore them.
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGIO
+@cindex input available signal
+@cindex output possible signal
+This signal is sent when a file descriptor is ready to perform input
+or output.
+
+On most operating systems, terminals and sockets are the only kinds of
+files that can generate @code{SIGIO}; other kinds, including ordinary
+files, never generate @code{SIGIO} even if you ask them to.
+
+In the GNU system @code{SIGIO} will always be generated properly 
+if you successfully set asynchronous mode with @code{fcntl}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGURG
+@cindex urgent data signal
+This signal is sent when ``urgent'' or out-of-band data arrives on a
+socket.  @xref{Out-of-Band Data}.
+@end deftypevr
+
+@comment signal.h
+@comment SVID
+@deftypevr Macro int SIGPOLL
+This is a System V signal name, more or less similar to @code{SIGIO}.
+It is defined only for compatibility.
+@end deftypevr
+
+@node Job Control Signals
+@subsection Job Control Signals
+@cindex job control signals
+
+These signals are used to support job control.  If your system
+doesn't support job control, then these macros are defined but the
+signals themselves can't be raised or handled.
+
+You should generally leave these signals alone unless you really
+understand how job control works.  @xref{Job Control}.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGCHLD
+@cindex child process signal
+This signal is sent to a parent process whenever one of its child
+processes terminates or stops.
+
+The default action for this signal is to ignore it.  If you establish a
+handler for this signal while there are child processes that have
+terminated but not reported their status via @code{wait} or
+@code{waitpid} (@pxref{Process Completion}), whether your new handler
+applies to those processes or not depends on the particular operating
+system.
+@end deftypevr
+
+@comment signal.h
+@comment SVID
+@deftypevr Macro int SIGCLD
+This is an obsolete name for @code{SIGCHLD}.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGCONT
+@cindex continue signal
+You can send a @code{SIGCONT} signal to a process to make it continue.
+This signal is special---it always makes the process continue if it is
+stopped, before the signal is delivered.  The default behavior is to do
+nothing else.  You cannot block this signal.  You can set a handler, but
+@code{SIGCONT} always makes the process continue regardless.
+
+Most programs have no reason to handle @code{SIGCONT}; they simply
+resume execution without realizing they were ever stopped.  You can use
+a handler for @code{SIGCONT} to make a program do something special when
+it is stopped and continued---for example, to reprint a prompt when it
+is suspended while waiting for input.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGSTOP
+The @code{SIGSTOP} signal stops the process.  It cannot be handled,
+ignored, or blocked.
+@end deftypevr
+@cindex stop signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGTSTP
+The @code{SIGTSTP} signal is an interactive stop signal.  Unlike
+@code{SIGSTOP}, this signal can be handled and ignored.  
+
+Your program should handle this signal if you have a special need to
+leave files or system tables in a secure state when a process is
+stopped.  For example, programs that turn off echoing should handle
+@code{SIGTSTP} so they can turn echoing back on before stopping.
+
+This signal is generated when the user types the SUSP character
+(normally @kbd{C-z}).  For more information about terminal driver
+support, see @ref{Special Characters}.
+@end deftypevr
+@cindex interactive stop signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGTTIN
+A process cannot read from the the user's terminal while it is running 
+as a background job.  When any process in a background job tries to
+read from the terminal, all of the processes in the job are sent a
+@code{SIGTTIN} signal.  The default action for this signal is to
+stop the process.  For more information about how this interacts with
+the terminal driver, see @ref{Access to the Terminal}.
+@end deftypevr
+@cindex terminal input signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGTTOU
+This is similar to @code{SIGTTIN}, but is generated when a process in a
+background job attempts to write to the terminal or set its modes.
+Again, the default action is to stop the process.  @code{SIGTTOU} is
+only generated for an attempt to write to the terminal if the
+@code{TOSTOP} output mode is set; @pxref{Output Modes}.
+@end deftypevr
+@cindex terminal output signal
+
+While a process is stopped, no more signals can be delivered to it until
+it is continued, except @code{SIGKILL} signals and (obviously)
+@code{SIGCONT} signals.  The signals are marked as pending, but not
+delivered until the process is continued.  The @code{SIGKILL} signal
+always causes termination of the process and can't be blocked, handled
+or ignored.  You can ignore @code{SIGCONT}, but it always causes the
+process to be continued anyway if it is stopped.  Sending a
+@code{SIGCONT} signal to a process causes any pending stop signals for
+that process to be discarded.  Likewise, any pending @code{SIGCONT}
+signals for a process are discarded when it receives a stop signal.
+
+When a process in an orphaned process group (@pxref{Orphaned Process
+Groups}) receives a @code{SIGTSTP}, @code{SIGTTIN}, or @code{SIGTTOU}
+signal and does not handle it, the process does not stop.  Stopping the
+process would probably not be very useful, since there is no shell
+program that will notice it stop and allow the user to continue it.
+What happens instead depends on the operating system you are using.
+Some systems may do nothing; others may deliver another signal instead,
+such as @code{SIGKILL} or @code{SIGHUP}.  In the GNU system, the process
+dies with @code{SIGKILL}; this avoids the problem of many stopped,
+orphaned processes lying around the system.
+
+@ignore
+On the GNU system, it is possible to reattach to the orphaned process
+group and continue it, so stop signals do stop the process as usual on
+a GNU system unless you have requested POSIX compatibility ``till it
+hurts.''
+@end ignore
+
+@node Operation Error Signals
+@subsection Operation Error Signals
+
+These signals are used to report various errors generated by an
+operation done by the program.  They do not necessarily indicate a
+programming error in the program, but an error that prevents an
+operating system call from completing.  The default action for all of
+them is to cause the process to terminate.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGPIPE
+@cindex pipe signal
+@cindex broken pipe signal
+Broken pipe.  If you use pipes or FIFOs, you have to design your
+application so that one process opens the pipe for reading before
+another starts writing.  If the reading process never starts, or
+terminates unexpectedly, writing to the pipe or FIFO raises a
+@code{SIGPIPE} signal.  If @code{SIGPIPE} is blocked, handled or
+ignored, the offending call fails with @code{EPIPE} instead.
+
+Pipes and FIFO special files are discussed in more detail in @ref{Pipes
+and FIFOs}.
+
+Another cause of @code{SIGPIPE} is when you try to output to a socket
+that isn't connected.  @xref{Sending Data}.
+@end deftypevr
+
+@comment signal.h
+@comment GNU
+@deftypevr Macro int SIGLOST
+@cindex lost resource signal
+Resource lost.  This signal is generated when you have an advisory lock
+on an NFS file, and the NFS server reboots and forgets about your lock.
+
+In the GNU system, @code{SIGLOST} is generated when any server program
+dies unexpectedly.  It is usually fine to ignore the signal; whatever
+call was made to the server that died just returns an error.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGXCPU
+CPU time limit exceeded.  This signal is generated when the process
+exceeds its soft resource limit on CPU time.  @xref{Limits on Resources}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGXFSZ
+File size limit exceeded.  This signal is generated when the process
+attempts to extend a file so it exceeds the process's soft resource
+limit on file size.  @xref{Limits on Resources}.
+@end deftypevr
+
+@node Miscellaneous Signals
+@subsection Miscellaneous Signals
+
+These signals are used for various other purposes.  In general, they
+will not affect your program unless it explicitly uses them for something.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGUSR1
+@end deftypevr
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGUSR2
+@cindex user signals
+The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to
+use any way you want.  They're useful for simple interprocess
+communication, if you write a signal handler for them in the program
+that receives the signal.
+
+There is an example showing the use of @code{SIGUSR1} and @code{SIGUSR2}
+in @ref{Signaling Another Process}.
+
+The default action is to terminate the process.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGWINCH
+Window size change.  This is generated on some systems (including GNU)
+when the terminal driver's record of the number of rows and columns on
+the screen is changed.  The default action is to ignore it.
+
+If a program does full-screen display, it should handle @code{SIGWINCH}.
+When the signal arrives, it should fetch the new screen size and
+reformat its display accordingly.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGINFO
+Information request.  In 4.4 BSD and the GNU system, this signal is sent
+to all the processes in the foreground process group of the controlling
+terminal when the user types the STATUS character in canonical mode;
+@pxref{Signal Characters}.
+
+If the process is the leader of the process group, the default action is
+to print some status information about the system and what the process
+is doing.  Otherwise the default is to do nothing.
+@end deftypevr
+
+@node Signal Messages
+@subsection Signal Messages
+@cindex signal messages
+
+We mentioned above that the shell prints a message describing the signal
+that terminated a child process.  The clean way to print a message
+describing a signal is to use the functions @code{strsignal} and
+@code{psignal}.  These functions use a signal number to specify which
+kind of signal to describe.  The signal number may come from the
+termination status of a child process (@pxref{Process Completion}) or it
+may come from a signal handler in the same process.
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strsignal (int @var{signum})
+This function returns a pointer to a statically-allocated string
+containing a message describing the signal @var{signum}.  You
+should not modify the contents of this string; and, since it can be
+rewritten on subsequent calls, you should save a copy of it if you need
+to reference it later.
+
+@pindex string.h
+This function is a GNU extension, declared in the header file
+@file{string.h}.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun void psignal (int @var{signum}, const char *@var{message})
+This function prints a message describing the signal @var{signum} to the
+standard error output stream @code{stderr}; see @ref{Standard Streams}.
+
+If you call @code{psignal} with a @var{message} that is either a null
+pointer or an empty string, @code{psignal} just prints the message 
+corresponding to @var{signum}, adding a trailing newline.
+
+If you supply a non-null @var{message} argument, then @code{psignal}
+prefixes its output with this string.  It adds a colon and a space 
+character to separate the @var{message} from the string corresponding
+to @var{signum}.
+
+@pindex stdio.h
+This function is a BSD feature, declared in the header file @file{signal.h}.
+@end deftypefun
+
+@vindex sys_siglist
+There is also an array @code{sys_siglist} which contains the messages
+for the various signal codes.  This array exists on BSD systems, unlike
+@code{strsignal}.
+
+@node Signal Actions
+@section Specifying Signal Actions
+@cindex signal actions
+@cindex establishing a handler
+
+The simplest way to change the action for a signal is to use the
+@code{signal} function.  You can specify a built-in action (such as to
+ignore the signal), or you can @dfn{establish a handler}.
+
+The GNU library also implements the more versatile @code{sigaction}
+facility.  This section describes both facilities and gives suggestions
+on which to use when.
+
+@menu
+* Basic Signal Handling::       The simple @code{signal} function.
+* Advanced Signal Handling::    The more powerful @code{sigaction} function.
+* Signal and Sigaction::        How those two functions interact.
+* Sigaction Function Example::  An example of using the sigaction function.
+* Flags for Sigaction::         Specifying options for signal handling.
+* Initial Signal Actions::      How programs inherit signal actions.
+@end menu
+
+@node Basic Signal Handling
+@subsection Basic Signal Handling
+@cindex @code{signal} function
+
+The @code{signal} function provides a simple interface for establishing
+an action for a particular signal.  The function and associated macros
+are declared in the header file @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment GNU
+@deftp {Data Type} sighandler_t
+This is the type of signal handler functions.  Signal handlers take one
+integer argument specifying the signal number, and have return type
+@code{void}.  So, you should define handler functions like this:
+
+@smallexample
+void @var{handler} (int @code{signum}) @{ @dots{} @}
+@end smallexample
+
+The name @code{sighandler_t} for this data type is a GNU extension.
+@end deftp
+
+@comment signal.h
+@comment ANSI
+@deftypefun sighandler_t signal (int @var{signum}, sighandler_t @var{action})
+The @code{signal} function establishes @var{action} as the action for
+the signal @var{signum}.
+
+The first argument, @var{signum}, identifies the signal whose behavior
+you want to control, and should be a signal number.  The proper way to
+specify a signal number is with one of the symbolic signal names
+described in @ref{Standard Signals}---don't use an explicit number, because
+the numerical code for a given kind of signal may vary from operating
+system to operating system.
+
+The second argument, @var{action}, specifies the action to use for the
+signal @var{signum}.  This can be one of the following:
+
+@table @code
+@item SIG_DFL
+@vindex SIG_DFL
+@cindex default action for a signal
+@code{SIG_DFL} specifies the default action for the particular signal.
+The default actions for various kinds of signals are stated in
+@ref{Standard Signals}.
+
+@item SIG_IGN
+@vindex SIG_IGN
+@cindex ignore action for a signal
+@code{SIG_IGN} specifies that the signal should be ignored.
+
+Your program generally should not ignore signals that represent serious
+events or that are normally used to request termination.  You cannot
+ignore the @code{SIGKILL} or @code{SIGSTOP} signals at all.  You can
+ignore program error signals like @code{SIGSEGV}, but ignoring the error
+won't enable the program to continue executing meaningfully.  Ignoring
+user requests such as @code{SIGINT}, @code{SIGQUIT}, and @code{SIGTSTP}
+is unfriendly.
+
+When you do not wish signals to be delivered during a certain part of
+the program, the thing to do is to block them, not ignore them.
+@xref{Blocking Signals}.
+
+@item @var{handler}
+Supply the address of a handler function in your program, to specify
+running this handler as the way to deliver the signal.
+
+For more information about defining signal handler functions,
+see @ref{Defining Handlers}.
+@end table
+
+If you set the action for a signal to @code{SIG_IGN}, or if you set it
+to @code{SIG_DFL} and the default action is to ignore that signal, then
+any pending signals of that type are discarded (even if they are
+blocked).  Discarding the pending signals means that they will never be
+delivered, not even if you subsequently specify another action and
+unblock this kind of signal.
+
+The @code{signal} function returns the action that was previously in
+effect for the specified @var{signum}.  You can save this value and
+restore it later by calling @code{signal} again.
+
+If @code{signal} can't honor the request, it returns @code{SIG_ERR}
+instead.  The following @code{errno} error conditions are defined for
+this function:
+
+@table @code
+@item EINVAL
+You specified an invalid @var{signum}; or you tried to ignore or provide
+a handler for @code{SIGKILL} or @code{SIGSTOP}.
+@end table
+@end deftypefun
+
+Here is a simple example of setting up a handler to delete temporary
+files when certain fatal signals happen:
+
+@smallexample
+#include <signal.h>
+
+void
+termination_handler (int signum)
+@{
+  struct temp_file *p;
+
+  for (p = temp_file_list; p; p = p->next)
+    unlink (p->name);
+@}
+
+int
+main (void)
+@{
+  @dots{}
+  if (signal (SIGINT, termination_handler) == SIG_IGN)
+    signal (SIGINT, SIG_IGN);
+  if (signal (SIGHUP, termination_handler) == SIG_IGN)
+    signal (SIGHUP, SIG_IGN);
+  if (signal (SIGTERM, termination_handler) == SIG_IGN)
+    signal (SIGTERM, SIG_IGN);
+  @dots{}
+@}
+@end smallexample
+
+@noindent
+Note how if a given signal was previously set to be ignored, this code
+avoids altering that setting.  This is because non-job-control shells
+often ignore certain signals when starting children, and it is important
+for the children to respect this.
+
+We do not handle @code{SIGQUIT} or the program error signals in this
+example because these are designed to provide information for debugging
+(a core dump), and the temporary files may give useful information.
+
+@comment signal.h
+@comment SVID
+@deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action})
+The @code{ssignal} function does the same thing as @code{signal}; it is
+provided only for compatibility with SVID.
+@end deftypefun
+
+@comment signal.h
+@comment ANSI
+@deftypevr Macro sighandler_t SIG_ERR
+The value of this macro is used as the return value from @code{signal}
+to indicate an error.
+@end deftypevr
+
+@ignore
+@comment RMS says that ``we don't do this''.
+Implementations might define additional macros for built-in signal
+actions that are suitable as a @var{action} argument to @code{signal},
+besides @code{SIG_IGN} and @code{SIG_DFL}.  Identifiers whose names
+begin with @samp{SIG_} followed by an uppercase letter are reserved for
+this purpose.
+@end ignore
+
+
+@node Advanced Signal Handling
+@subsection Advanced Signal Handling
+@cindex @code{sigaction} function
+
+The @code{sigaction} function has the same basic effect as
+@code{signal}: to specify how a signal should be handled by the process.
+However, @code{sigaction} offers more control, at the expense of more
+complexity.  In particular, @code{sigaction} allows you to specify
+additional flags to control when the signal is generated and how the
+handler is invoked.
+
+The @code{sigaction} function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftp {Data Type} {struct sigaction}
+Structures of type @code{struct sigaction} are used in the
+@code{sigaction} function to specify all the information about how to
+handle a particular signal.  This structure contains at least the
+following members:
+
+@table @code
+@item sighandler_t sa_handler
+This is used in the same way as the @var{action} argument to the
+@code{signal} function.  The value can be @code{SIG_DFL},
+@code{SIG_IGN}, or a function pointer.  @xref{Basic Signal Handling}.
+
+@item sigset_t sa_mask
+This specifies a set of signals to be blocked while the handler runs.
+Blocking is explained in @ref{Blocking for Handler}.  Note that the
+signal that was delivered is automatically blocked by default before its
+handler is started; this is true regardless of the value in
+@code{sa_mask}.  If you want that signal not to be blocked within its
+handler, you must write code in the handler to unblock it.
+
+@item int sa_flags
+This specifies various flags which can affect the behavior of 
+the signal.  These are described in more detail in @ref{Flags for Sigaction}.
+@end table
+@end deftp
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigaction (int @var{signum}, const struct sigaction *@var{action}, struct sigaction *@var{old-action})
+The @var{action} argument is used to set up a new action for the signal
+@var{signum}, while the @var{old-action} argument is used to return
+information about the action previously associated with this symbol.
+(In other words, @var{old-action} has the same purpose as the
+@code{signal} function's return value---you can check to see what the
+old action in effect for the signal was, and restore it later if you
+want.)
+
+Either @var{action} or @var{old-action} can be a null pointer.  If
+@var{old-action} is a null pointer, this simply suppresses the return
+of information about the old action.  If @var{action} is a null pointer,
+the action associated with the signal @var{signum} is unchanged; this
+allows you to inquire about how a signal is being handled without changing
+that handling.
+
+The return value from @code{sigaction} is zero if it succeeds, and
+@code{-1} on failure.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument is not valid, or you are trying to
+trap or ignore @code{SIGKILL} or @code{SIGSTOP}.
+@end table
+@end deftypefun
+
+@node Signal and Sigaction
+@subsection Interaction of @code{signal} and @code{sigaction}
+
+It's possible to use both the @code{signal} and @code{sigaction}
+functions within a single program, but you have to be careful because
+they can interact in slightly strange ways.
+
+The @code{sigaction} function specifies more information than the
+@code{signal} function, so the return value from @code{signal} cannot
+express the full range of @code{sigaction} possibilities.  Therefore, if
+you use @code{signal} to save and later reestablish an action, it may
+not be able to reestablish properly a handler that was established with
+@code{sigaction}.
+
+To avoid having problems as a result, always use @code{sigaction} to
+save and restore a handler if your program uses @code{sigaction} at all.
+Since @code{sigaction} is more general, it can properly save and
+reestablish any action, regardless of whether it was established
+originally with @code{signal} or @code{sigaction}.
+
+On some systems if you establish an action with @code{signal} and then
+examine it with @code{sigaction}, the handler address that you get may
+not be the same as what you specified with @code{signal}.  It may not
+even be suitable for use as an action argument with @code{signal}.  But
+you can rely on using it as an argument to @code{sigaction}.  This
+problem never happens on the GNU system.
+
+So, you're better off using one or the other of the mechanisms
+consistently within a single program.  
+
+@strong{Portability Note:} The basic @code{signal} function is a feature
+of ANSI C, while @code{sigaction} is part of the POSIX.1 standard.  If
+you are concerned about portability to non-POSIX systems, then you
+should use the @code{signal} function instead.
+
+@node Sigaction Function Example
+@subsection @code{sigaction} Function Example
+
+In @ref{Basic Signal Handling}, we gave an example of establishing a
+simple handler for termination signals using @code{signal}.  Here is an
+equivalent example using @code{sigaction}:
+
+@smallexample
+#include <signal.h>
+
+void
+termination_handler (int signum)
+@{
+  struct temp_file *p;
+
+  for (p = temp_file_list; p; p = p->next)
+    unlink (p->name);
+@}
+
+int
+main (void)
+@{
+  @dots{}
+  struct sigaction new_action, old_action;
+
+  /* @r{Set up the structure to specify the new action.} */
+  new_action.sa_handler = termination_handler;
+  sigemptyset (&new_action.sa_mask);
+  new_action.sa_flags = 0;
+
+  sigaction (SIGINT, NULL, &old_action);
+  if (old_action.sa_handler != SIG_IGN)
+    sigaction (SIGINT, &new_action, NULL);
+  sigaction (SIGHUP, NULL, &old_action);
+  if (old_action.sa_handler != SIG_IGN)
+    sigaction (SIGHUP, &new_action, NULL);
+  sigaction (SIGTERM, NULL, &old_action);
+  if (old_action.sa_handler != SIG_IGN)
+    sigaction (SIGTERM, &new_action, NULL);
+  @dots{}
+@}
+@end smallexample
+
+The program just loads the @code{new_action} structure with the desired
+parameters and passes it in the @code{sigaction} call.  The usage of
+@code{sigemptyset} is described later; see @ref{Blocking Signals}.
+
+As in the example using @code{signal}, we avoid handling signals
+previously set to be ignored.  Here we can avoid altering the signal
+handler even momentarily, by using the feature of @code{sigaction} that
+lets us examine the current action without specifying a new one.
+
+Here is another example.  It retrieves information about the current
+action for @code{SIGINT} without changing that action.
+
+@smallexample
+struct sigaction query_action;
+
+if (sigaction (SIGINT, NULL, &query_action) < 0)
+  /* @r{@code{sigaction} returns -1 in case of error.} */ 
+else if (query_action.sa_handler == SIG_DFL)
+  /* @r{@code{SIGINT} is handled in the default, fatal manner.} */
+else if (query_action.sa_handler == SIG_IGN)
+  /* @r{@code{SIGINT} is ignored.} */
+else
+  /* @r{A programmer-defined signal handler is in effect.} */
+@end smallexample
+
+@node Flags for Sigaction
+@subsection Flags for @code{sigaction}
+@cindex signal flags
+@cindex flags for @code{sigaction}
+@cindex @code{sigaction} flags
+
+The @code{sa_flags} member of the @code{sigaction} structure is a
+catch-all for special features.  Most of the time, @code{SA_RESTART} is
+a good value to use for this field.
+
+The value of @code{sa_flags} is interpreted as a bit mask.  Thus, you
+should choose the flags you want to set, @sc{or} those flags together,
+and store the result in the @code{sa_flags} member of your
+@code{sigaction} structure.
+
+Each signal number has its own set of flags.  Each call to
+@code{sigaction} affects one particular signal number, and the flags
+that you specify apply only to that particular signal.
+
+In the GNU C library, establishing a handler with @code{signal} sets all
+the flags to zero except for @code{SA_RESTART}, whose value depends on
+the settings you have made with @code{siginterrupt}.  @xref{Interrupted
+Primitives}, to see what this is about.
+
+@pindex signal.h
+These macros are defined in the header file @file{signal.h}.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SA_NOCLDSTOP
+This flag is meaningful only for the @code{SIGCHLD} signal.  When the
+flag is set, the system delivers the signal for a terminated child
+process but not for one that is stopped.  By default, @code{SIGCHLD} is
+delivered for both terminated children and stopped children.
+
+Setting this flag for a signal other than @code{SIGCHLD} has no effect.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SA_ONSTACK
+If this flag is set for a particular signal number, the system uses the
+signal stack when delivering that kind of signal.  @xref{Signal Stack}.
+If a signal with this flag arrives and you have not set a signal stack,
+the system terminates the program with @code{SIGILL}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SA_RESTART
+This flag controls what happens when a signal is delivered during
+certain primitives (such as @code{open}, @code{read} or @code{write}),
+and the signal handler returns normally.  There are two alternatives:
+the library function can resume, or it can return failure with error
+code @code{EINTR}.
+
+The choice is controlled by the @code{SA_RESTART} flag for the
+particular kind of signal that was delivered.  If the flag is set,
+returning from a handler resumes the library function.  If the flag is
+clear, returning from a handler makes the function fail.
+@xref{Interrupted Primitives}.
+@end deftypevr
+
+@node Initial Signal Actions
+@subsection Initial Signal Actions
+@cindex initial signal actions
+
+When a new process is created (@pxref{Creating a Process}), it inherits
+handling of signals from its parent process.  However, when you load a
+new process image using the @code{exec} function (@pxref{Executing a
+File}), any signals that you've defined your own handlers for revert to
+their @code{SIG_DFL} handling.  (If you think about it a little, this
+makes sense; the handler functions from the old program are specific to
+that program, and aren't even present in the address space of the new
+program image.)  Of course, the new program can establish its own
+handlers.
+
+When a program is run by a shell, the shell normally sets the initial
+actions for the child process to @code{SIG_DFL} or @code{SIG_IGN}, as
+appropriate.  It's a good idea to check to make sure that the shell has
+not set up an initial action of @code{SIG_IGN} before you establish your
+own signal handlers.
+
+Here is an example of how to establish a handler for @code{SIGHUP}, but
+not if @code{SIGHUP} is currently ignored:
+
+@smallexample
+@group
+@dots{}
+struct sigaction temp;
+
+sigaction (SIGHUP, NULL, &temp);
+
+if (temp.sa_handler != SIG_IGN)
+  @{
+    temp.sa_handler = handle_sighup;
+    sigemptyset (&temp.sa_mask);
+    sigaction (SIGHUP, &temp, NULL);
+  @}
+@end group
+@end smallexample
+
+@node Defining Handlers
+@section Defining Signal Handlers
+@cindex signal handler function
+
+This section describes how to write a signal handler function that can
+be established with the @code{signal} or @code{sigaction} functions.
+
+A signal handler is just a function that you compile together with the
+rest of the program.  Instead of directly invoking the function, you use
+@code{signal} or @code{sigaction} to tell the operating system to call
+it when a signal arrives.  This is known as @dfn{establishing} the
+handler.  @xref{Signal Actions}.
+
+There are two basic strategies you can use in signal handler functions:
+
+@itemize @bullet
+@item
+You can have the handler function note that the signal arrived by
+tweaking some global data structures, and then return normally.
+
+@item
+You can have the handler function terminate the program or transfer
+control to a point where it can recover from the situation that caused
+the signal.
+@end itemize
+
+You need to take special care in writing handler functions because they
+can be called asynchronously.  That is, a handler might be called at any
+point in the program, unpredictably.  If two signals arrive during a
+very short interval, one handler can run within another.  This section
+describes what your handler should do, and what you should avoid.
+
+@menu
+* Handler Returns::             Handlers that return normally, and what
+                                 this means. 
+* Termination in Handler::      How handler functions terminate a program.
+* Longjmp in Handler::          Nonlocal transfer of control out of a
+                                 signal handler.
+* Signals in Handler::          What happens when signals arrive while
+                                 the handler is already occupied.
+* Merged Signals::		When a second signal arrives before the
+				 first is handled.
+* Nonreentrancy::               Do not call any functions unless you know they
+                                 are reentrant with respect to signals. 
+* Atomic Data Access::          A single handler can run in the middle of
+                                 reading or writing a single object. 
+@end menu
+
+@node Handler Returns
+@subsection Signal Handlers that Return
+
+Handlers which return normally are usually used for signals such as
+@code{SIGALRM} and the I/O and interprocess communication signals.  But
+a handler for @code{SIGINT} might also return normally after setting a
+flag that tells the program to exit at a convenient time.
+
+It is not safe to return normally from the handler for a program error
+signal, because the behavior of the program when the handler function
+returns is not defined after a program error.  @xref{Program Error
+Signals}.
+
+Handlers that return normally must modify some global variable in order
+to have any effect.  Typically, the variable is one that is examined
+periodically by the program during normal operation.  Its data type
+should be @code{sig_atomic_t} for reasons described in @ref{Atomic
+Data Access}.
+
+Here is a simple example of such a program.  It executes the body of
+the loop until it has noticed that a @code{SIGALRM} signal has arrived.
+This technique is useful because it allows the iteration in progress
+when the signal arrives to complete before the loop exits.
+
+@smallexample
+@include sigh1.c.texi
+@end smallexample
+
+@node Termination in Handler
+@subsection Handlers That Terminate the Process
+
+Handler functions that terminate the program are typically used to cause
+orderly cleanup or recovery from program error signals and interactive
+interrupts.
+
+The cleanest way for a handler to terminate the process is to raise the
+same signal that ran the handler in the first place.  Here is how to do
+this:
+
+@smallexample
+volatile sig_atomic_t fatal_error_in_progress = 0;
+
+void
+fatal_error_signal (int sig)
+@{
+@group
+  /* @r{Since this handler is established for more than one kind of signal, }
+     @r{it might still get invoked recursively by delivery of some other kind}
+     @r{of signal.  Use a static variable to keep track of that.} */
+  if (fatal_error_in_progress)
+    raise (sig);
+  fatal_error_in_progress = 1;
+@end group
+
+@group
+  /* @r{Now do the clean up actions:}
+     @r{- reset terminal modes}
+     @r{- kill child processes}
+     @r{- remove lock files} */
+  @dots{}
+@end group
+
+@group
+  /* @r{Now reraise the signal.  Since the signal is blocked,}
+     @r{it will receive its default handling, which is}
+     @r{to terminate the process.  We could just call}
+     @r{@code{exit} or @code{abort}, but reraising the signal}
+     @r{sets the return status from the process correctly.} */
+  raise (sig);
+@}
+@end group
+@end smallexample
+
+@node Longjmp in Handler
+@subsection Nonlocal Control Transfer in Handlers
+@cindex non-local exit, from signal handler
+
+You can do a nonlocal transfer of control out of a signal handler using
+the @code{setjmp} and @code{longjmp} facilities (@pxref{Non-Local
+Exits}).
+
+When the handler does a nonlocal control transfer, the part of the
+program that was running will not continue.  If this part of the program
+was in the middle of updating an important data structure, the data
+structure will remain inconsistent.  Since the program does not
+terminate, the inconsistency is likely to be noticed later on.
+
+There are two ways to avoid this problem.  One is to block the signal
+for the parts of the program that update important data structures.
+Blocking the signal delays its delivery until it is unblocked, once the
+critical updating is finished.  @xref{Blocking Signals}.
+
+The other way to re-initialize the crucial data structures in the signal
+handler, or make their values consistent.
+
+Here is a rather schematic example showing the reinitialization of one
+global variable.
+
+@smallexample
+@group
+#include <signal.h>
+#include <setjmp.h>
+
+jmp_buf return_to_top_level;
+
+volatile sig_atomic_t waiting_for_input;
+
+void
+handle_sigint (int signum)
+@{
+  /* @r{We may have been waiting for input when the signal arrived,}
+     @r{but we are no longer waiting once we transfer control.} */
+  waiting_for_input = 0;
+  longjmp (return_to_top_level, 1);
+@}
+@end group
+
+@group
+int
+main (void)
+@{
+  @dots{}
+  signal (SIGINT, sigint_handler);
+  @dots{}
+  while (1) @{
+    prepare_for_command ();
+    if (setjmp (return_to_top_level) == 0)
+      read_and_execute_command ();
+  @}
+@}
+@end group
+
+@group
+/* @r{Imagine this is a subroutine used by various commands.} */
+char *
+read_data ()
+@{
+  if (input_from_terminal) @{
+    waiting_for_input = 1;
+    @dots{}
+    waiting_for_input = 0;
+  @} else @{ 
+    @dots{}
+  @}
+@}
+@end group
+@end smallexample
+
+
+@node Signals in Handler
+@subsection Signals Arriving While a Handler Runs
+@cindex race conditions, relating to signals
+
+What happens if another signal arrives while your signal handler
+function is running?
+
+When the handler for a particular signal is invoked, that signal is
+automatically blocked until the handler returns.  That means that if two
+signals of the same kind arrive close together, the second one will be
+held until the first has been handled.  (The handler can explicitly
+unblock the signal using @code{sigprocmask}, if you want to allow more
+signals of this type to arrive; see @ref{Process Signal Mask}.)
+
+However, your handler can still be interrupted by delivery of another
+kind of signal.  To avoid this, you can use the @code{sa_mask} member of
+the action structure passed to @code{sigaction} to explicitly specify
+which signals should be blocked while the signal handler runs.  These
+signals are in addition to the signal for which the handler was invoked,
+and any other signals that are normally blocked by the process.
+@xref{Blocking for Handler}.
+
+When the handler returns, the set of blocked signals is restored to the
+value it had before the handler ran.  So using @code{sigprocmask} inside
+the handler only affects what signals can arrive during the execution of
+the handler itself, not what signals can arrive once the handler returns.
+
+@strong{Portability Note:} Always use @code{sigaction} to establish a
+handler for a signal that you expect to receive asynchronously, if you
+want your program to work properly on System V Unix.  On this system,
+the handling of a signal whose handler was established with
+@code{signal} automatically sets the signal's action back to
+@code{SIG_DFL}, and the handler must re-establish itself each time it
+runs.  This practice, while inconvenient, does work when signals cannot
+arrive in succession.  However, if another signal can arrive right away,
+it may arrive before the handler can re-establish itself.  Then the
+second signal would receive the default handling, which could terminate
+the process.
+
+@node Merged Signals
+@subsection Signals Close Together Merge into One
+@cindex handling multiple signals
+@cindex successive signals
+@cindex merging of signals
+
+If multiple signals of the same type are delivered to your process
+before your signal handler has a chance to be invoked at all, the
+handler may only be invoked once, as if only a single signal had
+arrived.  In effect, the signals merge into one.  This situation can
+arise when the signal is blocked, or in a multiprocessing environment
+where the system is busy running some other processes while the signals
+are delivered.  This means, for example, that you cannot reliably use a
+signal handler to count signals.  The only distinction you can reliably
+make is whether at least one signal has arrived since a given time in
+the past.
+
+Here is an example of a handler for @code{SIGCHLD} that compensates for
+the fact that the number of signals recieved may not equal the number of
+child processes generate them.  It assumes that the program keeps track
+of all the child processes with a chain of structures as follows:
+
+@smallexample
+struct process
+@{
+  struct process *next;
+  /* @r{The process ID of this child.}  */
+  int pid;
+  /* @r{The descriptor of the pipe or pseudo terminal}
+     @r{on which output comes from this child.}  */
+  int input_descriptor;
+  /* @r{Nonzero if this process has stopped or terminated.}  */
+  sig_atomic_t have_status;
+  /* @r{The status of this child; 0 if running,}
+     @r{otherwise a status value from @code{waitpid}.}  */
+  int status;
+@};
+
+struct process *process_list;
+@end smallexample
+
+This example also uses a flag to indicate whether signals have arrived
+since some time in the past---whenever the program last cleared it to
+zero.
+
+@smallexample
+/* @r{Nonzero means some child's status has changed}
+   @r{so look at @code{process_list} for the details.}  */
+int process_status_change;
+@end smallexample
+
+Here is the handler itself:
+
+@smallexample
+void
+sigchld_handler (int signo)
+@{
+  int old_errno = errno;
+
+  while (1) @{
+    register int pid;
+    int w;
+    struct process *p;
+
+    /* @r{Keep asking for a status until we get a definitive result.}  */
+    do 
+      @{
+        errno = 0;
+        pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
+      @}
+    while (pid <= 0 && errno == EINTR);
+
+    if (pid <= 0) @{
+      /* @r{A real failure means there are no more}
+         @r{stopped or terminated child processes, so return.}  */
+      errno = old_errno;
+      return;
+    @}
+
+    /* @r{Find the process that signaled us, and record its status.}  */
+
+    for (p = process_list; p; p = p->next)
+      if (p->pid == pid) @{
+        p->status = w;
+        /* @r{Indicate that the @code{status} field}
+           @r{has data to look at.  We do this only after storing it.}  */
+        p->have_status = 1;
+
+        /* @r{If process has terminated, stop waiting for its output.}  */
+        if (WIFSIGNALED (w) || WIFEXITED (w))
+          if (p->input_descriptor)
+            FD_CLR (p->input_descriptor, &input_wait_mask);
+
+        /* @r{The program should check this flag from time to time}
+           @r{to see if there is any news in @code{process_list}.}  */
+        ++process_status_change;
+      @}
+
+    /* @r{Loop around to handle all the processes}
+       @r{that have something to tell us.}  */
+  @}
+@}
+@end smallexample
+
+Here is the proper way to check the flag @code{process_status_change}:
+
+@smallexample
+if (process_status_change) @{
+  struct process *p;
+  process_status_change = 0;
+  for (p = process_list; p; p = p->next)
+    if (p->have_status) @{
+      @dots{} @r{Examine @code{p->status}} @dots{}
+    @}
+@}
+@end smallexample
+
+@noindent
+It is vital to clear the flag before examining the list; otherwise, if a
+signal were delivered just before the clearing of the flag, and after
+the appropriate element of the process list had been checked, the status
+change would go unnoticed until the next signal arrived to set the flag
+again.  You could, of course, avoid this problem by blocking the signal
+while scanning the list, but it is much more elegant to guarantee
+correctness by doing things in the right order.
+
+The loop which checks process status avoids examining @code{p->status}
+until it sees that status has been validly stored.  This is to make sure
+that the status cannot change in the middle of accessing it.  Once
+@code{p->have_status} is set, it means that the child process is stopped
+or terminated, and in either case, it cannot stop or terminate again
+until the program has taken notice.  @xref{Atomic Usage}, for more
+information about coping with interruptions during accessings of a
+variable.
+
+Here is another way you can test whether the handler has run since the
+last time you checked.  This technique uses a counter which is never
+changed outside the handler.  Instead of clearing the count, the program
+remembers the previous value and sees whether it has changed since the
+previous check.  The advantage of this method is that different parts of
+the program can check independently, each part checking whether there
+has been a signal since that part last checked.
+
+@smallexample
+sig_atomic_t process_status_change;
+
+sig_atomic_t last_process_status_change;
+
+@dots{}
+@{
+  sig_atomic_t prev = last_process_status_change;
+  last_process_status_change = process_status_change;
+  if (last_process_status_change != prev) @{
+    struct process *p;
+    for (p = process_list; p; p = p->next)
+      if (p->have_status) @{
+        @dots{} @r{Examine @code{p->status}} @dots{}
+      @}
+  @}
+@}
+@end smallexample
+
+@node Nonreentrancy
+@subsection Signal Handling and Nonreentrant Functions 
+@cindex restrictions on signal handler functions
+
+Handler functions usually don't do very much.  The best practice is to
+write a handler that does nothing but set an external variable that the
+program checks regularly, and leave all serious work to the program.
+This is best because the handler can be called at asynchronously, at
+unpredictable times---perhaps in the middle of a primitive function, or
+even between the beginning and the end of a C operator that requires
+multiple instructions.  The data structures being manipulated might
+therefore be in an inconsistent state when the handler function is
+invoked.  Even copying one @code{int} variable into another can take two
+instructions on most machines.
+
+This means you have to be very careful about what you do in a signal
+handler.
+
+@itemize @bullet
+@item
+@cindex @code{volatile} declarations
+If your handler needs to access any global variables from your program,
+declare those variables @code{volatile}.  This tells the compiler that
+the value of the variable might change asynchronously, and inhibits
+certain optimizations that would be invalidated by such modifications.
+
+@item
+@cindex reentrant functions
+If you call a function in the handler, make sure it is @dfn{reentrant}
+with respect to signals, or else make sure that the signal cannot
+interrupt a call to a related function.
+@end itemize
+
+A function can be non-reentrant if it uses memory that is not on the
+stack.
+
+@itemize @bullet
+@item
+If a function uses a static variable or a global variable, or a
+dynamically-allocated object that it finds for itself, then it is
+non-reentrant and any two calls to the function can interfere.
+
+For example, suppose that the signal handler uses @code{gethostbyname}.
+This function returns its value in a static object, reusing the same
+object each time.  If the signal happens to arrive during a call to
+@code{gethostbyname}, or even after one (while the program is still
+using the value), it will clobber the value that the program asked for.
+
+However, if the program does not use @code{gethostbyname} or any other
+function that returns information in the same object, or if it always
+blocks signals around each use, then you are safe.
+
+There are a large number of library functions that return values in a
+fixed object, always reusing the same object in this fashion, and all of
+them cause the same problem.  The description of a function in this
+manual always mentions this behavior.
+
+@item
+If a function uses and modifies an object that you supply, then it is
+potentially non-reentrant; two calls can interfere if they use the same
+object.
+
+This case arises when you do I/O using streams.  Suppose that the
+signal handler prints a message with @code{fprintf}.  Suppose that the
+program was in the middle of an @code{fprintf} call using the same
+stream when the signal was delivered.  Both the signal handler's message
+and the program's data could be corrupted, because both calls operate on
+the same data structure---the stream itself.
+
+However, if you know that the stream that the handler uses cannot
+possibly be used by the program at a time when signals can arrive, then
+you are safe.  It is no problem if the program uses some other stream.
+
+@item
+On most systems, @code{malloc} and @code{free} are not reentrant,
+because they use a static data structure which records what memory
+blocks are free.  As a result, no library functions that allocate or
+free memory are reentrant.  This includes functions that allocate space
+to store a result.
+
+The best way to avoid the need to allocate memory in a handler is to
+allocate in advance space for signal handlers to use.
+
+The best way to avoid freeing memory in a handler is to flag or record
+the objects to be freed, and have the program check from time to time
+whether anything is waiting to be freed.  But this must be done with
+care, because placing an object on a chain is not atomic, and if it is
+interrupted by another signal handler that does the same thing, you
+could ``lose'' one of the objects.
+
+@ignore
+!!! not true
+On the GNU system, @code{malloc} and @code{free} are safe to use in
+signal handlers because they block signals.  As a result, the library
+functions that allocate space for a result are also safe in signal
+handlers.  The obstack allocation functions are safe as long as you
+don't use the same obstack both inside and outside of a signal handler.
+@end ignore
+
+The relocating allocation functions (@pxref{Relocating Allocator})
+are certainly not safe to use in a signal handler.
+
+@item
+Any function that modifies @code{errno} is non-reentrant, but you can
+correct for this: in the handler, save the original value of
+@code{errno} and restore it before returning normally.  This prevents
+errors that occur within the signal handler from being confused with
+errors from system calls at the point the program is interrupted to run
+the handler.
+
+This technique is generally applicable; if you want to call in a handler
+a function that modifies a particular object in memory, you can make
+this safe by saving and restoring that object.
+
+@item
+Merely reading from a memory object is safe provided that you can deal
+with any of the values that might appear in the object at a time when
+the signal can be delivered.  Keep in mind that assignment to some data
+types requires more than one instruction, which means that the handler
+could run ``in the middle of'' an assignment to the variable if its type
+is not atomic.  @xref{Atomic Data Access}.
+
+@item
+Merely writing into a memory object is safe as long as a sudden change
+in the value, at any time when the handler might run, will not disturb
+anything.
+@end itemize
+
+@node Atomic Data Access
+@subsection Atomic Data Access and Signal Handling
+
+Whether the data in your application concerns atoms, or mere text, you
+have to be careful about the fact that access to a single datum is not
+necessarily @dfn{atomic}.  This means that it can take more than one
+instruction to read or write a single object.  In such cases, a signal
+handler might in the middle of reading or writing the object.
+
+There are three ways you can cope with this problem.  You can use data
+types that are always accessed atomically; you can carefully arrange
+that nothing untoward happens if an access is interrupted, or you can
+block all signals around any access that had better not be interrupted
+(@pxref{Blocking Signals}).
+
+@menu
+* Non-atomic Example::		A program illustrating interrupted access.
+* Types: Atomic Types.		Data types that guarantee no interruption.
+* Usage: Atomic Usage.		Proving that interruption is harmless.
+@end menu
+
+@node Non-atomic Example
+@subsubsection Problems with Non-Atomic Access
+
+Here is an example which shows what can happen if a signal handler runs
+in the middle of modifying a variable.  (Interrupting the reading of a
+variable can also lead to paradoxical results, but here we only show
+writing.)
+
+@smallexample
+#include <signal.h>
+#include <stdio.h>
+
+struct two_words @{ int a, b; @} memory;
+
+void
+handler(int signum)
+@{
+   printf ("%d,%d\n", memory.a, memory.b);
+   alarm (1);
+@}
+
+@group
+int
+main (void)
+@{
+   static struct two_words zeros = @{ 0, 0 @}, ones = @{ 1, 1 @};
+   signal (SIGALRM, handler);
+   memory = zeros;
+   alarm (1);
+   while (1)
+     @{
+       memory = zeros;
+       memory = ones;
+     @}
+@}
+@end group
+@end smallexample
+
+This program fills @code{memory} with zeros, ones, zeros, ones,
+alternating forever; meanwhile, once per second, the alarm signal handler
+prints the current contents.  (Calling @code{printf} in the handler is
+safe in this program because it is certainly not being called outside
+the handler when the signal happens.)
+
+Clearly, this program can print a pair of zeros or a pair of ones.  But
+that's not all it can do!  On most machines, it takes several
+instructions to store a new value in @code{memory}, and the value is
+stored one word at a time.  If the signal is delivered in between these
+instructions, the handler might find that @code{memory.a} is zero and
+@code{memory.b} is one (or vice versa).
+
+On some machines it may be possible to store a new value in
+@code{memory} with just one instruction that cannot be interrupted.  On
+these machines, the handler will always print two zeros or two ones.
+
+@node Atomic Types
+@subsubsection Atomic Types
+
+To avoid uncertainty about interrupting access to a variable, you can
+use a particular data type for which access is always atomic:
+@code{sig_atomic_t}.  Reading and writing this data type is guaranteed
+to happen in a single instruction, so there's no way for a handler to
+run ``in the middle'' of an access.
+
+The type @code{sig_atomic_t} is always an integer data type, but which
+one it is, and how many bits it contains, may vary from machine to
+machine.
+
+@comment signal.h
+@comment ANSI
+@deftp {Data Type} sig_atomic_t
+This is an integer data type.  Objects of this type are always accessed
+atomically.
+@end deftp
+
+In practice, you can assume that @code{int} and other integer types no
+longer than @code{int} are atomic.  You can also assume that pointer
+types are atomic; that is very convenient.  Both of these are true on
+all of the machines that the GNU C library supports, and on all POSIX
+systems we know of.
+@c ??? This might fail on a 386 that uses 64-bit pointers.
+
+@node Atomic Usage
+@subsubsection Atomic Usage Patterns
+
+Certain patterns of access avoid any problem even if an access is
+interrupted.  For example, a flag which is set by the handler, and
+tested and cleared by the main program from time to time, is always safe
+even if access actually requires two instructions.  To show that this is
+so, we must consider each access that could be interrupted, and show
+that there is no problem if it is interrupted.
+
+An interrupt in the middle of testing the flag is safe because either it's
+recognized to be nonzero, in which case the precise value doesn't
+matter, or it will be seen to be nonzero the next time it's tested.
+
+An interrupt in the middle of clearing the flag is no problem because
+either the value ends up zero, which is what happens if a signal comes
+in just before the flag is cleared, or the value ends up nonzero, and
+subsequent events occur as if the signal had come in just after the flag
+was cleared.  As long as the code handles both of these cases properly,
+it can also handle a signal in the middle of clearing the flag.  (This
+is an example of the sort of reasoning you need to do to figure out
+whether non-atomic usage is safe.)
+
+Sometimes you can insure uninterrupted access to one object by
+protecting its use with another object, perhaps one whose type
+guarantees atomicity.  @xref{Merged Signals}, for an example.
+
+@node Interrupted Primitives
+@section Primitives Interrupted by Signals
+
+A signal can arrive and be handled while an I/O primitive such as
+@code{open} or @code{read} is waiting for an I/O device.  If the signal
+handler returns, the system faces the question: what should happen next?
+
+POSIX specifies one approach: make the primitive fail right away.  The
+error code for this kind of failure is @code{EINTR}.  This is flexible,
+but usually inconvenient.  Typically, POSIX applications that use signal
+handlers must check for @code{EINTR} after each library function that
+can return it, in order to try the call again.  Often programmers forget
+to check, which is a common source of error.
+
+The GNU library provides a convenient way to retry a call after a
+temporary failure, with the macro @code{TEMP_FAILURE_RETRY}:
+
+@comment unistd.h
+@comment GNU
+@defmac TEMP_FAILURE_RETRY (@var{expression})
+This macro evaluates @var{expression} once.  If it fails and reports
+error code @code{EINTR}, @code{TEMP_FAILURE_RETRY} evaluates it again,
+and over and over until the result is not a temporary failure.
+
+The value returned by @code{TEMP_FAILURE_RETRY} is whatever value
+@var{expression} produced.
+@end defmac
+
+BSD avoids @code{EINTR} entirely and provides a more convenient
+approach: to restart the interrupted primitive, instead of making it
+fail.  If you choose this approach, you need not be concerned with
+@code{EINTR}.
+
+You can choose either approach with the GNU library.  If you use
+@code{sigaction} to establish a signal handler, you can specify how that
+handler should behave.  If you specify the @code{SA_RESTART} flag,
+return from that handler will resume a primitive; otherwise, return from
+that handler will cause @code{EINTR}.  @xref{Flags for Sigaction}.
+
+Another way to specify the choice is with the @code{siginterrupt}
+function.  @xref{BSD Handler}.
+
+@c !!! not true now about _BSD_SOURCE
+When you don't specify with @code{sigaction} or @code{siginterrupt} what
+a particular handler should do, it uses a default choice.  The default
+choice in the GNU library depends on the feature test macros you have
+defined.  If you define @code{_BSD_SOURCE} or @code{_GNU_SOURCE} before
+calling @code{signal}, the default is to resume primitives; otherwise,
+the default is to make them fail with @code{EINTR}.  (The library
+contains alternate versions of the @code{signal} function, and the
+feature test macros determine which one you really call.)  @xref{Feature
+Test Macros}.
+@cindex EINTR, and restarting interrupted primitives
+@cindex restarting interrupted primitives
+@cindex interrupting primitives
+@cindex primitives, interrupting
+@c !!! want to have @cindex system calls @i{see} primitives [no page #]
+
+The description of each primitive affected by this issue
+lists @code{EINTR} among the error codes it can return.
+
+There is one situation where resumption never happens no matter which
+choice you make: when a data-transfer function such as @code{read} or
+@code{write} is interrupted by a signal after transferring part of the
+data.  In this case, the function returns the number of bytes already
+transferred, indicating partial success.
+
+This might at first appear to cause unreliable behavior on
+record-oriented devices (including datagram sockets; @pxref{Datagrams}),
+where splitting one @code{read} or @code{write} into two would read or
+write two records.  Actually, there is no problem, because interruption
+after a partial transfer cannot happen on such devices; they always
+transfer an entire record in one burst, with no waiting once data
+transfer has started.
+
+@node Generating Signals
+@section Generating Signals
+@cindex sending signals
+@cindex raising signals
+@cindex signals, generating
+
+Besides signals that are generated as a result of a hardware trap or
+interrupt, your program can explicitly send signals to itself or to
+another process.
+
+@menu
+* Signaling Yourself::          A process can send a signal to itself.
+* Signaling Another Process::   Send a signal to another process.
+* Permission for kill::         Permission for using @code{kill}.
+* Kill Example::                Using @code{kill} for Communication.
+@end menu
+
+@node Signaling Yourself
+@subsection Signaling Yourself
+
+A process can send itself a signal with the @code{raise} function.  This
+function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment ANSI
+@deftypefun int raise (int @var{signum})
+The @code{raise} function sends the signal @var{signum} to the calling
+process.  It returns zero if successful and a nonzero value if it fails.
+About the only reason for failure would be if the value of @var{signum}
+is invalid.
+@end deftypefun
+
+@comment signal.h
+@comment SVID
+@deftypefun int gsignal (int @var{signum})
+The @code{gsignal} function does the same thing as @code{raise}; it is
+provided only for compatibility with SVID.
+@end deftypefun
+
+One convenient use for @code{raise} is to reproduce the default behavior
+of a signal that you have trapped.  For instance, suppose a user of your
+program types the SUSP character (usually @kbd{C-z}; @pxref{Special
+Characters}) to send it an interactive stop stop signal
+(@code{SIGTSTP}), and you want to clean up some internal data buffers
+before stopping.  You might set this up like this:
+
+@comment RMS suggested getting rid of the handler for SIGCONT in this function.
+@comment But that would require that the handler for SIGTSTP unblock the
+@comment signal before doing the call to raise.  We haven't covered that
+@comment topic yet, and I don't want to distract from the main point of
+@comment the example with a digression to explain what is going on.  As
+@comment the example is written, the signal that is raise'd will be delivered
+@comment as soon as the SIGTSTP handler returns, which is fine.
+
+@smallexample
+#include <signal.h>
+
+/* @r{When a stop signal arrives, set the action back to the default
+   and then resend the signal after doing cleanup actions.} */
+
+void
+tstp_handler (int sig)
+@{
+  signal (SIGTSTP, SIG_DFL);
+  /* @r{Do cleanup actions here.} */
+  @dots{}
+  raise (SIGTSTP);
+@}
+
+/* @r{When the process is continued again, restore the signal handler.} */
+
+void
+cont_handler (int sig)
+@{
+  signal (SIGCONT, cont_handler);
+  signal (SIGTSTP, tstp_handler);
+@}
+
+@group
+/* @r{Enable both handlers during program initialization.} */
+
+int
+main (void)
+@{
+  signal (SIGCONT, cont_handler);
+  signal (SIGTSTP, tstp_handler);
+  @dots{}
+@}
+@end group
+@end smallexample
+
+@strong{Portability note:} @code{raise} was invented by the ANSI C
+committee.  Older systems may not support it, so using @code{kill} may
+be more portable.  @xref{Signaling Another Process}.
+
+@node Signaling Another Process
+@subsection Signaling Another Process
+
+@cindex killing a process
+The @code{kill} function can be used to send a signal to another process.
+In spite of its name, it can be used for a lot of things other than
+causing a process to terminate.  Some examples of situations where you
+might want to send signals between processes are:
+
+@itemize @bullet
+@item
+A parent process starts a child to perform a task---perhaps having the
+child running an infinite loop---and then terminates the child when the
+task is no longer needed.
+
+@item
+A process executes as part of a group, and needs to terminate or notify
+the other processes in the group when an error or other event occurs.
+
+@item
+Two processes need to synchronize while working together.
+@end itemize
+
+This section assumes that you know a little bit about how processes
+work.  For more information on this subject, see @ref{Processes}.
+
+The @code{kill} function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int kill (pid_t @var{pid}, int @var{signum})
+The @code{kill} function sends the signal @var{signum} to the process
+or process group specified by @var{pid}.  Besides the signals listed in
+@ref{Standard Signals}, @var{signum} can also have a value of zero to
+check the validity of the @var{pid}.
+
+The @var{pid} specifies the process or process group to receive the
+signal:
+
+@table @code
+@item @var{pid} > 0
+The process whose identifier is @var{pid}.
+
+@item @var{pid} == 0
+All processes in the same process group as the sender.
+
+@item @var{pid} < -1
+The process group whose identifier is @minus{}@var{pid}.
+
+@item @var{pid} == -1
+If the process is privileged, send the signal to all processes except
+for some special system processes.  Otherwise, send the signal to all
+processes with the same effective user ID.
+@end table
+
+A process can send a signal @var{signum} to itself with a call like
+@w{@code{kill (getpid(), @var{signum})}}.  If @code{kill} is used by a
+process to send a signal to itself, and the signal is not blocked, then
+@code{kill} delivers at least one signal (which might be some other
+pending unblocked signal instead of the signal @var{signum}) to that
+process before it returns.
+
+The return value from @code{kill} is zero if the signal can be sent
+successfully.  Otherwise, no signal is sent, and a value of @code{-1} is
+returned.  If @var{pid} specifies sending a signal to several processes,
+@code{kill} succeeds if it can send the signal to at least one of them.
+There's no way you can tell which of the processes got the signal
+or whether all of them did.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument is an invalid or unsupported number.
+
+@item EPERM
+You do not have the privilege to send a signal to the process or any of
+the processes in the process group named by @var{pid}.
+
+@item ESCRH
+The @var{pid} argument does not refer to an existing process or group.
+@end table
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int killpg (int @var{pgid}, int @var{signum})
+This is similar to @code{kill}, but sends signal @var{signum} to the
+process group @var{pgid}.  This function is provided for compatibility
+with BSD; using @code{kill} to do this is more portable.
+@end deftypefun
+
+As a simple example of @code{kill}, the call @w{@code{kill (getpid (),
+@var{sig})}} has the same effect as @w{@code{raise (@var{sig})}}.
+
+@node Permission for kill
+@subsection Permission for using @code{kill}
+
+There are restrictions that prevent you from using @code{kill} to send
+signals to any random process.  These are intended to prevent antisocial
+behavior such as arbitrarily killing off processes belonging to another
+user.  In typical use, @code{kill} is used to pass signals between
+parent, child, and sibling processes, and in these situations you
+normally do have permission to send signals.  The only common execption
+is when you run a setuid program in a child process; if the program
+changes its real UID as well as its effective UID, you may not have
+permission to send a signal.  The @code{su} program does this.
+
+Whether a process has permission to send a signal to another process
+is determined by the user IDs of the two processes.  This concept is
+discussed in detail in @ref{Process Persona}.
+
+Generally, for a process to be able to send a signal to another process,
+either the sending process must belong to a privileged user (like
+@samp{root}), or the real or effective user ID of the sending process
+must match the real or effective user ID of the receiving process.  If
+the receiving process has changed its effective user ID from the
+set-user-ID mode bit on its process image file, then the owner of the
+process image file is used in place of its current effective user ID.
+In some implementations, a parent process might be able to send signals
+to a child process even if the user ID's don't match, and other
+implementations might enforce other restrictions.
+
+The @code{SIGCONT} signal is a special case.  It can be sent if the
+sender is part of the same session as the receiver, regardless of
+user IDs.
+
+@node Kill Example
+@subsection Using @code{kill} for Communication
+@cindex interprocess communication, with signals
+Here is a longer example showing how signals can be used for
+interprocess communication.  This is what the @code{SIGUSR1} and
+@code{SIGUSR2} signals are provided for.  Since these signals are fatal
+by default, the process that is supposed to receive them must trap them
+through @code{signal} or @code{sigaction}.
+
+In this example, a parent process forks a child process and then waits
+for the child to complete its initialization.  The child process tells
+the parent when it is ready by sending it a @code{SIGUSR1} signal, using
+the @code{kill} function.
+
+@smallexample
+@include sigusr.c.texi
+@end smallexample
+
+This example uses a busy wait, which is bad, because it wastes CPU
+cycles that other programs could otherwise use.  It is better to ask the
+system to wait until the signal arrives.  See the example in
+@ref{Waiting for a Signal}.
+
+@node Blocking Signals
+@section Blocking Signals
+@cindex blocking signals
+
+Blocking a signal means telling the operating system to hold it and
+deliver it later.  Generally, a program does not block signals
+indefinitely---it might as well ignore them by setting their actions to
+@code{SIG_IGN}.  But it is useful to block signals briefly, to prevent
+them from interrupting sensitive operations.  For instance:
+
+@itemize @bullet
+@item
+You can use the @code{sigprocmask} function to block signals while you
+modify global variables that are also modified by the handlers for these 
+signals.
+
+@item
+You can set @code{sa_mask} in your @code{sigaction} call to block
+certain signals while a particular signal handler runs.  This way, the
+signal handler can run without being interrupted itself by signals.
+@end itemize
+
+@menu
+* Why Block::                           The purpose of blocking signals.
+* Signal Sets::                         How to specify which signals to
+                                         block. 
+* Process Signal Mask::                 Blocking delivery of signals to your
+				         process during normal execution.
+* Testing for Delivery::                Blocking to Test for Delivery of
+                                         a Signal. 
+* Blocking for Handler::                Blocking additional signals while a
+				         handler is being run.
+* Checking for Pending Signals::        Checking for Pending Signals
+* Remembering a Signal::                How you can get almost the same
+                                         effect as blocking a signal, by
+                                         handling it and setting a flag
+                                         to be tested later. 
+@end menu
+
+@node Why Block
+@subsection Why Blocking Signals is Useful
+
+Temporary blocking of signals with @code{sigprocmask} gives you a way to
+prevent interrupts during critical parts of your code.  If signals
+arrive in that part of the program, they are delivered later, after you
+unblock them.
+
+One example where this is useful is for sharing data between a signal
+handler and the rest of the program.  If the type of the data is not
+@code{sig_atomic_t} (@pxref{Atomic Data Access}), then the signal
+handler could run when the rest of the program has only half finished
+reading or writing the data.  This would lead to confusing consequences.
+
+To make the program reliable, you can prevent the signal handler from
+running while the rest of the program is examining or modifying that
+data---by blocking the appropriate signal around the parts of the
+program that touch the data.
+
+Blocking signals is also necessary when you want to perform a certain
+action only if a signal has not arrived.  Suppose that the handler for
+the signal sets a flag of type @code{sig_atomic_t}; you would like to
+test the flag and perform the action if the flag is not set.  This is
+unreliable.  Suppose the signal is delivered immediately after you test
+the flag, but before the consequent action: then the program will
+perform the action even though the signal has arrived.
+
+The only way to test reliably for whether a signal has yet arrived is to
+test while the signal is blocked.
+
+@node Signal Sets
+@subsection Signal Sets
+
+All of the signal blocking functions use a data structure called a
+@dfn{signal set} to specify what signals are affected.  Thus, every
+activity involves two stages: creating the signal set, and then passing
+it as an argument to a library function.
+@cindex signal set
+
+These facilities are declared in the header file @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftp {Data Type} sigset_t
+The @code{sigset_t} data type is used to represent a signal set.
+Internally, it may be implemented as either an integer or structure
+type.
+
+For portability, use only the functions described in this section to
+initialize, change, and retrieve information from @code{sigset_t}
+objects---don't try to manipulate them directly.
+@end deftp
+
+There are two ways to initialize a signal set.  You can initially
+specify it to be empty with @code{sigemptyset} and then add specified
+signals individually.  Or you can specify it to be full with
+@code{sigfillset} and then delete specified signals individually.
+
+You must always initialize the signal set with one of these two
+functions before using it in any other way.  Don't try to set all the
+signals explicitly because the @code{sigset_t} object might include some
+other information (like a version field) that needs to be initialized as
+well.  (In addition, it's not wise to put into your program an
+assumption that the system has no signals aside from the ones you know
+about.)
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigemptyset (sigset_t *@var{set})
+This function initializes the signal set @var{set} to exclude all of the
+defined signals.  It always returns @code{0}.
+@end deftypefun
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigfillset (sigset_t *@var{set})
+This function initializes the signal set @var{set} to include
+all of the defined signals.  Again, the return value is @code{0}.
+@end deftypefun
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum})
+This function adds the signal @var{signum} to the signal set @var{set}.
+All @code{sigaddset} does is modify @var{set}; it does not block or
+unblock any signals.
+
+The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument doesn't specify a valid signal.
+@end table
+@end deftypefun
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum})
+This function removes the signal @var{signum} from the signal set
+@var{set}.  All @code{sigdelset} does is modify @var{set}; it does not
+block or unblock any signals.  The return value and error conditions are
+the same as for @code{sigaddset}.
+@end deftypefun
+
+Finally, there is a function to test what signals are in a signal set:
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum})
+The @code{sigismember} function tests whether the signal @var{signum} is
+a member of the signal set @var{set}.  It returns @code{1} if the signal
+is in the set, @code{0} if not, and @code{-1} if there is an error.
+
+The following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument doesn't specify a valid signal.
+@end table
+@end deftypefun
+
+@node Process Signal Mask
+@subsection Process Signal Mask
+@cindex signal mask
+@cindex process signal mask
+
+The collection of signals that are currently blocked is called the
+@dfn{signal mask}.  Each process has its own signal mask.  When you
+create a new process (@pxref{Creating a Process}), it inherits its
+parent's mask.  You can block or unblock signals with total flexibility
+by modifying the signal mask.
+
+The prototype for the @code{sigprocmask} function is in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigprocmask (int @var{how}, const sigset_t *@var{set}, sigset_t *@var{oldset})
+The @code{sigprocmask} function is used to examine or change the calling
+process's signal mask.  The @var{how} argument determines how the signal
+mask is changed, and must be one of the following values:
+
+@table @code
+@comment signal.h
+@comment POSIX.1
+@vindex SIG_BLOCK
+@item SIG_BLOCK
+Block the signals in @code{set}---add them to the existing mask.  In
+other words, the new mask is the union of the existing mask and
+@var{set}.
+
+@comment signal.h
+@comment POSIX.1
+@vindex SIG_UNBLOCK
+@item SIG_UNBLOCK
+Unblock the signals in @var{set}---remove them from the existing mask.
+
+@comment signal.h
+@comment POSIX.1
+@vindex SIG_SETMASK
+@item SIG_SETMASK
+Use @var{set} for the mask; ignore the previous value of the mask.
+@end table
+
+The last argument, @var{oldset}, is used to return information about the
+old process signal mask.  If you just want to change the mask without
+looking at it, pass a null pointer as the @var{oldset} argument.
+Similarly, if you want to know what's in the mask without changing it,
+pass a null pointer for @var{set} (in this case the @var{how} argument
+is not significant).  The @var{oldset} argument is often used to
+remember the previous signal mask in order to restore it later.  (Since
+the signal mask is inherited over @code{fork} and @code{exec} calls, you
+can't predict what its contents are when your program starts running.)
+
+If invoking @code{sigprocmask} causes any pending signals to be
+unblocked, at least one of those signals is delivered to the process
+before @code{sigprocmask} returns.  The order in which pending signals
+are delivered is not specified, but you can control the order explicitly
+by making multiple @code{sigprocmask} calls to unblock various signals
+one at a time.
+
+The @code{sigprocmask} function returns @code{0} if successful, and @code{-1}
+to indicate an error.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EINVAL
+The @var{how} argument is invalid.
+@end table
+
+You can't block the @code{SIGKILL} and @code{SIGSTOP} signals, but
+if the signal set includes these, @code{sigprocmask} just ignores
+them instead of returning an error status.
+
+Remember, too, that blocking program error signals such as @code{SIGFPE}
+leads to undesirable results for signals generated by an actual program
+error (as opposed to signals sent with @code{raise} or @code{kill}).
+This is because your program may be too broken to be able to continue
+executing to a point where the signal is unblocked again.
+@xref{Program Error Signals}.
+@end deftypefun
+
+@node Testing for Delivery
+@subsection Blocking to Test for Delivery of a Signal
+
+Now for a simple example.  Suppose you establish a handler for
+@code{SIGALRM} signals that sets a flag whenever a signal arrives, and
+your main program checks this flag from time to time and then resets it.
+You can prevent additional @code{SIGALRM} signals from arriving in the
+meantime by wrapping the critical part of the code with calls to
+@code{sigprocmask}, like this:
+
+@smallexample
+/* @r{This variable is set by the SIGALRM signal handler.} */
+volatile sig_atomic_t flag = 0;
+
+int
+main (void)
+@{
+  sigset_t block_alarm;
+
+  @dots{}
+
+  /* @r{Initialize the signal mask.} */
+  sigemptyset (&block_alarm);
+  sigaddset (&block_alarm, SIGALRM);
+
+@group
+  while (1)
+    @{
+      /* @r{Check if a signal has arrived; if so, reset the flag.} */
+      sigprocmask (SIG_BLOCK, &block_alarm, NULL);
+      if (flag)
+        @{
+          @var{actions-if-not-arrived}
+          flag = 0;
+        @}
+      sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
+
+      @dots{}
+    @}
+@}
+@end group
+@end smallexample
+
+@node Blocking for Handler
+@subsection Blocking Signals for a Handler
+@cindex blocking signals, in a handler
+
+When a signal handler is invoked, you usually want it to be able to
+finish without being interrupted by another signal.  From the moment the
+handler starts until the moment it finishes, you must block signals that
+might confuse it or corrupt its data.
+
+When a handler function is invoked on a signal, that signal is
+automatically blocked (in addition to any other signals that are already
+in the process's signal mask) during the time the handler is running.
+If you set up a handler for @code{SIGTSTP}, for instance, then the
+arrival of that signal forces further @code{SIGTSTP} signals to wait
+during the execution of the handler.
+
+However, by default, other kinds of signals are not blocked; they can
+arrive during handler execution.
+
+The reliable way to block other kinds of signals during the execution of
+the handler is to use the @code{sa_mask} member of the @code{sigaction}
+structure.
+
+Here is an example:
+
+@smallexample
+#include <signal.h>
+#include <stddef.h>
+
+void catch_stop ();
+
+void
+install_handler (void)
+@{
+  struct sigaction setup_action;
+  sigset_t block_mask;
+
+  sigemptyset (&block_mask);
+  /* @r{Block other terminal-generated signals while handler runs.} */
+  sigaddset (&block_mask, SIGINT);
+  sigaddset (&block_mask, SIGQUIT);
+  setup_action.sa_handler = catch_stop;
+  setup_action.sa_mask = block_mask;
+  setup_action.sa_flags = 0;
+  sigaction (SIGTSTP, &setup_action, NULL);
+@}
+@end smallexample
+
+This is more reliable than blocking the other signals explicitly in the
+code for the handler.  If you block signals explicity in the handler,
+you can't avoid at least a short interval at the beginning of the
+handler where they are not yet blocked.
+
+You cannot remove signals from the process's current mask using this
+mechanism.  However, you can make calls to @code{sigprocmask} within
+your handler to block or unblock signals as you wish.
+
+In any case, when the handler returns, the system restores the mask that
+was in place before the handler was entered.  If any signals that become
+unblocked by this restoration are pending, the process will receive
+those signals immediately, before returning to the code that was
+interrupted.
+
+@node Checking for Pending Signals
+@subsection Checking for Pending Signals
+@cindex pending signals, checking for
+@cindex blocked signals, checking for
+@cindex checking for pending signals
+
+You can find out which signals are pending at any time by calling
+@code{sigpending}.  This function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigpending (sigset_t *@var{set})
+The @code{sigpending} function stores information about pending signals
+in @var{set}.  If there is a pending signal that is blocked from
+delivery, then that signal is a member of the returned set.  (You can
+test whether a particular signal is a member of this set using
+@code{sigismember}; see @ref{Signal Sets}.)
+
+The return value is @code{0} if successful, and @code{-1} on failure.
+@end deftypefun
+
+Testing whether a signal is pending is not often useful.  Testing when
+that signal is not blocked is almost certainly bad design.
+
+Here is an example.
+
+@smallexample
+#include <signal.h>
+#include <stddef.h>
+
+sigset_t base_mask, waiting_mask;
+
+sigemptyset (&base_mask);
+sigaddset (&base_mask, SIGINT);
+sigaddset (&base_mask, SIGTSTP);
+
+/* @r{Block user interrupts while doing other processing.} */
+sigprocmask (SIG_SETMASK, &base_mask, NULL); 
+@dots{}
+
+/* @r{After a while, check to see whether any signals are pending.} */
+sigpending (&waiting_mask);
+if (sigismember (&waiting_mask, SIGINT)) @{
+  /* @r{User has tried to kill the process.} */
+@}
+else if (sigismember (&waiting_mask, SIGTSTP)) @{
+  /* @r{User has tried to stop the process.} */
+@}
+@end smallexample
+
+Remember that if there is a particular signal pending for your process,
+additional signals of that same type that arrive in the meantime might
+be discarded.  For example, if a @code{SIGINT} signal is pending when
+another @code{SIGINT} signal arrives, your program will probably only
+see one of them when you unblock this signal.
+
+@strong{Portability Note:} The @code{sigpending} function is new in
+POSIX.1.  Older systems have no equivalent facility.
+
+@node Remembering a Signal
+@subsection Remembering a Signal to Act On Later
+
+Instead of blocking a signal using the library facilities, you can get
+almost the same results by making the handler set a flag to be tested
+later, when you ``unblock''.  Here is an example:
+
+@smallexample
+/* @r{If this flag is nonzero, don't handle the signal right away.} */
+volatile sig_atomic_t signal_pending;
+
+/* @r{This is nonzero if a signal arrived and was not handled.} */
+volatile sig_atomic_t defer_signal;
+
+void
+handler (int signum)
+@{
+  if (defer_signal)
+    signal_pending = signum;
+  else
+    @dots{} /* @r{``Really'' handle the signal.} */
+@}
+
+@dots{}
+
+void
+update_mumble (int frob)
+@{
+  /* @r{Prevent signals from having immediate effect.} */
+  defer_signal++;
+  /* @r{Now update @code{mumble}, without worrying about interruption.} */
+  mumble.a = 1;
+  mumble.b = hack ();
+  mumble.c = frob;
+  /* @r{We have updated @code{mumble}.  Handle any signal that came in.} */
+  defer_signal--;
+  if (defer_signal == 0 && signal_pending != 0)
+    raise (signal_pending);
+@}
+@end smallexample
+
+Note how the particular signal that arrives is stored in
+@code{signal_pending}.  That way, we can handle several types of
+inconvenient signals with the same mechanism.
+
+We increment and decrement @code{defer_signal} so that nested critical
+sections will work properly; thus, if @code{update_mumble} were called
+with @code{signal_pending} already nonzero, signals would be deferred
+not only within @code{update_mumble}, but also within the caller.  This
+is also why we do not check @code{signal_pending} if @code{defer_signal}
+is still nonzero.
+
+The incrementing and decrementing of @code{defer_signal} require more
+than one instruction; it is possible for a signal to happen in the
+middle.  But that does not cause any problem.  If the signal happens
+early enough to see the value from before the increment or decrement,
+that is equivalent to a signal which came before the beginning of the
+increment or decrement, which is a case that works properly.
+
+It is absolutely vital to decrement @code{defer_signal} before testing
+@code{signal_pending}, because this avoids a subtle bug.  If we did
+these things in the other order, like this,
+
+@smallexample
+  if (defer_signal == 1 && signal_pending != 0)
+    raise (signal_pending);
+  defer_signal--;
+@end smallexample
+
+@noindent
+then a signal arriving in between the @code{if} statement and the decrement
+would be effetively ``lost'' for an indefinite amount of time.  The
+handler would merely set @code{defer_signal}, but the program having
+already tested this variable, it would not test the variable again.
+
+@cindex timing error in signal handling
+Bugs like these are called @dfn{timing errors}.  They are especially bad
+because they happen only rarely and are nearly impossible to reproduce.
+You can't expect to find them with a debugger as you would find a
+reproducible bug.  So it is worth being especially careful to avoid
+them.
+
+(You would not be tempted to write the code in this order, given the use
+of @code{defer_signal} as a counter which must be tested along with
+@code{signal_pending}.  After all, testing for zero is cleaner than
+testing for one.  But if you did not use @code{defer_signal} as a
+counter, and gave it values of zero and one only, then either order
+might seem equally simple.  This is a further advantage of using a
+counter for @code{defer_signal}: it will reduce the chance you will
+write the code in the wrong order and create a subtle bug.)
+
+@node Waiting for a Signal
+@section Waiting for a Signal
+@cindex waiting for a signal
+@cindex @code{pause} function
+
+If your program is driven by external events, or uses signals for
+synchronization, then when it has nothing to do it should probably wait
+until a signal arrives.
+
+@menu
+* Using Pause::                 The simple way, using @code{pause}.
+* Pause Problems::              Why the simple way is often not very good.
+* Sigsuspend::                  Reliably waiting for a specific signal.
+@end menu
+
+@node Using Pause
+@subsection Using @code{pause}
+
+The simple way to wait until a signal arrives is to call @code{pause}.
+Please read about its disadvantages, in the following section, before
+you use it.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int pause ()
+The @code{pause} function suspends program execution until a signal
+arrives whose action is either to execute a handler function, or to
+terminate the process.
+
+If the signal causes a handler function to be executed, then
+@code{pause} returns.  This is considered an unsuccessful return (since
+``successful'' behavior would be to suspend the program forever), so the
+return value is @code{-1}.  Even if you specify that other primitives
+should resume when a system handler returns (@pxref{Interrupted
+Primitives}), this has no effect on @code{pause}; it always fails when a
+signal is handled.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINTR
+The function was interrupted by delivery of a signal.
+@end table
+
+If the signal causes program termination, @code{pause} doesn't return
+(obviously).
+
+The @code{pause} function is declared in  @file{unistd.h}.
+@end deftypefun
+
+@node Pause Problems
+@subsection Problems with @code{pause}
+
+The simplicity of @code{pause} can conceal serious timing errors that
+can make a program hang mysteriously.
+
+It is safe to use @code{pause} if the real work of your program is done
+by the signal handlers themselves, and the ``main program'' does nothing
+but call @code{pause}.  Each time a signal is delivered, the handler
+will do the next batch of work that is to be done, and then return, so
+that the main loop of the program can call @code{pause} again.
+
+You can't safely use @code{pause} to wait until one more signal arrives,
+and then resume real work.  Even if you arrange for the signal handler
+to cooperate by setting a flag, you still can't use @code{pause}
+reliably.  Here is an example of this problem:
+
+@smallexample
+/* @r{@code{usr_interrupt} is set by the signal handler.}  */
+if (!usr_interrupt)
+  pause ();
+
+/* @r{Do work once the signal arrives.}  */
+@dots{}
+@end smallexample
+
+@noindent
+This has a bug: the signal could arrive after the variable
+@code{usr_interrupt} is checked, but before the call to @code{pause}.
+If no further signals arrive, the process would never wake up again.
+
+You can put an upper limit on the excess waiting by using @code{sleep}
+in a loop, instead of using @code{pause}.  (@xref{Sleeping}, for more
+about @code{sleep}.)  Here is what this looks like:
+
+@smallexample
+/* @r{@code{usr_interrupt} is set by the signal handler.}
+while (!usr_interrupt)
+  sleep (1);
+
+/* @r{Do work once the signal arrives.}  */
+@dots{}
+@end smallexample
+
+For some purposes, that is good enough.  But with a little more
+complexity, you can wait reliably until a particular signal handler is
+run, using @code{sigsuspend}.
+@ifinfo
+@xref{Sigsuspend}.
+@end ifinfo
+
+@node Sigsuspend
+@subsection Using @code{sigsuspend}
+
+The clean and reliable way to wait for a signal to arrive is to block it
+and then use @code{sigsuspend}.  By using @code{sigsuspend} in a loop,
+you can wait for certain kinds of signals, while letting other kinds of
+signals be handled by their handlers.
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigsuspend (const sigset_t *@var{set})
+This function replaces the process's signal mask with @var{set} and then
+suspends the process until a signal is delivered whose action is either
+to terminate the process or invoke a signal handling function.  In other
+words, the program is effectively suspended until one of the signals that
+is not a member of @var{set} arrives.
+
+If the process is woken up by deliver of a signal that invokes a handler
+function, and the handler function returns, then @code{sigsuspend} also
+returns.
+
+The mask remains @var{set} only as long as @code{sigsuspend} is waiting.
+The function @code{sigsuspend} always restores the previous signal mask
+when it returns.  
+
+The return value and error conditions are the same as for @code{pause}.
+@end deftypefun
+
+With @code{sigsuspend}, you can replace the @code{pause} or @code{sleep}
+loop in the previous section with something completely reliable:
+
+@smallexample
+sigset_t mask, oldmask;
+
+@dots{}
+
+/* @r{Set up the mask of signals to temporarily block.} */ 
+sigemptyset (&mask); 
+sigaddset (&mask, SIGUSR1);
+
+@dots{}
+
+/* @r{Wait for a signal to arrive.} */
+sigprocmask (SIG_BLOCK, &mask, &oldmask);
+while (!usr_interrupt)
+  sigsuspend (&oldmask);
+sigprocmask (SIG_UNBLOCK, &mask, NULL);
+@end smallexample
+
+This last piece of code is a little tricky.  The key point to remember
+here is that when @code{sigsuspend} returns, it resets the process's
+signal mask to the original value, the value from before the call to
+@code{sigsuspend}---in this case, the @code{SIGUSR1} signal is once
+again blocked.  The second call to @code{sigprocmask} is
+necessary to explicitly unblock this signal.
+
+One other point: you may be wondering why the @code{while} loop is
+necessary at all, since the program is apparently only waiting for one
+@code{SIGUSR1} signal.  The answer is that the mask passed to
+@code{sigsuspend} permits the process to be woken up by the delivery of
+other kinds of signals, as well---for example, job control signals.  If
+the process is woken up by a signal that doesn't set
+@code{usr_interrupt}, it just suspends itself again until the ``right''
+kind of signal eventually arrives.
+
+This technique takes a few more lines of preparation, but that is needed
+just once for each kind of wait criterion you want to use.  The code
+that actually waits is just four lines.
+
+@node Signal Stack
+@section Using a Separate Signal Stack
+
+A signal stack is a special area of memory to be used as the execution
+stack during signal handlers.  It should be fairly large, to avoid any
+danger that it will overflow in turn; the macro @code{SIGSTKSZ} is
+defined to a canonical size for signal stacks.  You can use
+@code{malloc} to allocate the space for the stack.  Then call
+@code{sigaltstack} or @code{sigstack} to tell the system to use that
+space for the signal stack.
+
+You don't need to write signal handlers differently in order to use a
+signal stack.  Switching from one stack to the other happens
+automatically.  (Some non-GNU debuggers on some machines may get
+confused if you examine a stack trace while a handler that uses the
+signal stack is running.)
+
+There are two interfaces for telling the system to use a separate signal
+stack.  @code{sigstack} is the older interface, which comes from 4.2
+BSD.  @code{sigaltstack} is the newer interface, and comes from 4.4
+BSD.  The @code{sigaltstack} interface has the advantage that it does
+not require your program to know which direction the stack grows, which
+depends on the specific machine and operating system.
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigaltstack}
+This structure describes a signal stack.  It contains the following members:
+
+@table @code
+@item void *ss_sp
+This points to the base of the signal stack.
+
+@item size_t ss_size
+This is the size (in bytes) of the signal stack which @samp{ss_sp} points to.
+You should set this to however much space you allocated for the stack.
+
+There are two macros defined in @file{signal.h} that you should use in
+calculating this size:
+
+@vtable @code
+@item SIGSTKSZ
+This is the canonical size for a signal stack.  It is judged to be
+sufficient for normal uses.
+
+@item MINSIGSTKSZ
+This is the amount of signal stack space the operating system needs just
+to implement signal delivery.  The size of a signal stack @strong{must}
+be greater than this.
+
+For most cases, just using @code{SIGSTKSZ} for @code{ss_size} is
+sufficient.  But if you know how much stack space your program's signal
+handlers will need, you may want to use a different size.  In this case,
+you should allocate @code{MINSIGSTKSZ} additional bytes for the signal
+stack and increase @code{ss_size} accordinly.
+@end vtable
+
+@item int ss_flags
+This field contains the bitwise @sc{or} of these flags:
+
+@vtable @code
+@item SA_DISABLE
+This tells the system that it should not use the signal stack.
+
+@item SA_ONSTACK
+This is set by the system, and indicates that the signal stack is
+currently in use.  If this bit is not set, then signals will be
+delivered on the normal user stack.
+@end vtable
+@end table
+@end deftp
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigaltstack (const struct sigaltstack *@var{stack}, struct sigaltstack *@var{oldstack})
+The @code{sigaltstack} function specifies an alternate stack for use
+during signal handling.  When a signal is received by the process and
+its action indicates that the signal stack is used, the system arranges
+a switch to the currently installed signal stack while the handler for
+that signal is executed.
+
+If @var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.  If
+@var{stack} is not a null pointer, then this is installed as the new
+stack for use by signal handlers.
+
+The return value is @code{0} on success and @code{-1} on failure.  If
+@code{sigaltstack} fails, it sets @code{errno} to one of these values:
+
+@table @code
+@item
+@item EINVAL
+You tried to disable a stack that was in fact currently in use.
+
+@item ENOMEM
+The size of the alternate stack was too small.  
+It must be greater than @code{MINSIGSTKSZ}.
+@end table
+@end deftypefun
+
+Here is the older @code{sigstack} interface.  You should use
+@code{sigaltstack} instead on systems that have it.
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigstack}
+This structure describes a signal stack.  It contains the following members:
+
+@table @code
+@item void *ss_sp
+This is the stack pointer.  If the stack grows downwards on your
+machine, this should point to the top of the area you allocated.  If the
+stack grows upwards, it should point to the bottom.
+
+@item int ss_onstack
+This field is true if the process is currently using this stack.
+@end table
+@end deftp
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigstack (const struct sigstack *@var{stack}, struct sigstack *@var{oldstack})
+The @code{sigstack} function specifies an alternate stack for use during
+signal handling.  When a signal is received by the process and its
+action indicates that the signal stack is used, the system arranges a
+switch to the currently installed signal stack while the handler for
+that signal is executed.
+
+If @var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.  If
+@var{stack} is not a null pointer, then this is installed as the new
+stack for use by signal handlers.
+
+The return value is @code{0} on success and @code{-1} on failure.
+@end deftypefun
+
+@node BSD Signal Handling
+@section BSD Signal Handling
+
+This section describes alternative signal handling functions derived
+from BSD Unix.  These facilities were an advance, in their time; today,
+they are mostly obsolete, and supported mainly for compatibility with
+BSD Unix.
+
+There are many similarities between the BSD and POSIX signal handling
+facilities, because the POSIX facilities were inspired by the BSD
+facilities.  Besides having different names for all the functions to
+avoid conflicts, the main differences between the two are:
+
+@itemize @bullet
+@item
+BSD Unix represents signal masks as an @code{int} bit mask, rather than
+as a @code{sigset_t} object.
+
+@item
+The BSD facilities use a different default for whether an interrupted
+primitive should fail or resume.  The POSIX facilities make system
+calls fail unless you specify that they should resume.  With the BSD
+facility, the default is to make system calls resume unless you say they
+should fail.  @xref{Interrupted Primitives}.
+@end itemize
+
+The BSD facilities are declared in @file{signal.h}.
+@pindex signal.h
+
+@menu
+* BSD Handler::                 BSD Function to Establish a Handler.
+* Blocking in BSD::             BSD Functions for Blocking Signals. 
+@end menu
+
+@node BSD Handler
+@subsection BSD Function to Establish a Handler
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigvec}
+This data type is the BSD equivalent of @code{struct sigaction}
+(@pxref{Advanced Signal Handling}); it is used to specify signal actions
+to the @code{sigvec} function.  It contains the following members:
+
+@table @code
+@item sighandler_t sv_handler
+This is the handler function.
+
+@item int sv_mask
+This is the mask of additional signals to be blocked while the handler
+function is being called.
+
+@item int sv_flags
+This is a bit mask used to specify various flags which affect the
+behavior of the signal.  You can also refer to this field as
+@code{sv_onstack}.
+@end table
+@end deftp
+
+These symbolic constants can be used to provide values for the
+@code{sv_flags} field of a @code{sigvec} structure.  This field is a bit
+mask value, so you bitwise-OR the flags of interest to you together.
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SV_ONSTACK
+If this bit is set in the @code{sv_flags} field of a @code{sigvec}
+structure, it means to use the signal stack when delivering the signal.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SV_INTERRUPT
+If this bit is set in the @code{sv_flags} field of a @code{sigvec}
+structure, it means that system calls interrupted by this kind of signal
+should not be restarted if the handler returns; instead, the system
+calls should return with a @code{EINTR} error status.  @xref{Interrupted
+Primitives}.
+@end deftypevr
+
+@comment signal.h
+@comment Sun
+@deftypevr Macro int SV_RESETHAND
+If this bit is set in the @code{sv_flags} field of a @code{sigvec}
+structure, it means to reset the action for the signal back to
+@code{SIG_DFL} when the signal is received.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigvec (int @var{signum}, const struct sigvec *@var{action},struct sigvec *@var{old-action})
+This function is the equivalent of @code{sigaction} (@pxref{Advanced Signal
+Handling}); it installs the action @var{action} for the signal @var{signum},
+returning information about the previous action in effect for that signal
+in @var{old-action}.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int siginterrupt (int @var{signum}, int @var{failflag})
+This function specifies which approach to use when certain primitives
+are interrupted by handling signal @var{signum}.  If @var{failflag} is
+false, signal @var{signum} restarts primitives.  If @var{failflag} is
+true, handling @var{signum} causes these primitives to fail with error
+code @code{EINTR}.  @xref{Interrupted Primitives}.
+@end deftypefun
+
+@node Blocking in BSD
+@subsection BSD Functions for Blocking Signals 
+
+@comment signal.h
+@comment BSD
+@deftypefn Macro int sigmask (int @var{signum})
+This macro returns a signal mask that has the bit for signal @var{signum}
+set.  You can bitwise-OR the results of several calls to @code{sigmask}
+together to specify more than one signal.  For example,
+
+@smallexample
+(sigmask (SIGTSTP) | sigmask (SIGSTOP)
+ | sigmask (SIGTTIN) | sigmask (SIGTTOU))
+@end smallexample
+
+@noindent
+specifies a mask that includes all the job-control stop signals.
+@end deftypefn
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigblock (int @var{mask})
+This function is equivalent to @code{sigprocmask} (@pxref{Process Signal
+Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the
+signals specified by @var{mask} to the calling process's set of blocked
+signals.  The return value is the previous set of blocked signals.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigsetmask (int @var{mask})
+This function equivalent to @code{sigprocmask} (@pxref{Process
+Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets
+the calling process's signal mask to @var{mask}.  The return value is
+the previous set of blocked signals.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigpause (int @var{mask})
+This function is the equivalent of @code{sigsuspend} (@pxref{Waiting
+for a Signal}):  it sets the calling process's signal mask to @var{mask},
+and waits for a signal to arrive.  On return the previous set of blocked
+signals is restored.
+@end deftypefun