0 files changed, 0 insertions, 0 deletions

path: root/libjava/classpath/lib/java/util/Collections$6.class

@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.