3318 lines
124 KiB
Plaintext
3318 lines
124 KiB
Plaintext
@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 synchronous 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 ISO
|
|
@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
|
|
and ANSI/IEEE Std 854-1987)}
|
|
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 ISO
|
|
@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 ISO
|
|
@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 ISO
|
|
@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 ISO
|
|
@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 ISO
|
|
@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 descriptor 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 ISO
|
|
@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 ISO
|
|
@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 @w{ISO 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 ISO
|
|
@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 ISO
|
|
@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 @w{ISO 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 exception
|
|
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 explicitly 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 effectively ``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} accordingly.
|
|
@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
|