signal.texi

一个C源代码分析器

The @code{signal} function returns the action that was previously in
effect for the specified @var{signum}.  You can save this value and
restore it later by calling @code{signal} again.

If @code{signal} can't honor the request, it returns @code{SIG_ERR}
instead.  The following @code{errno} error conditions are defined for
this function:

@table @code
@item EINVAL
You specified an invalid @var{signum}; or you tried to ignore or provide
a handler for @code{SIGKILL} or @code{SIGSTOP}.
@end table
@end deftypefun

Here is a simple example of setting up a handler to delete temporary
files when certain fatal signals happen:

@smallexample
#include <signal.h>

void
termination_handler (int signum)
@{
  struct temp_file *p;

  for (p = temp_file_list; p; p = p->next)
    unlink (p->name);
@}

int
main (void)
@{
  @dots{}
  if (signal (SIGINT, termination_handler) == SIG_IGN)
    signal (SIGINT, SIG_IGN);
  if (signal (SIGHUP, termination_handler) == SIG_IGN)
    signal (SIGHUP, SIG_IGN);
  if (signal (SIGTERM, termination_handler) == SIG_IGN)
    signal (SIGTERM, SIG_IGN);
  @dots{}
@}
@end smallexample

@noindent
Note how if a given signal was previously set to be ignored, this code
avoids altering that setting.  This is because non-job-control shells
often ignore certain signals when starting children, and it is important
for the children to respect this.

We do not handle @code{SIGQUIT} or the program error signals in this
example because these are designed to provide information for debugging
(a core dump), and the temporary files may give useful information.

@comment signal.h
@comment SVID
@deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action})
The @code{ssignal} function does the same thing as @code{signal}; it is
provided only for compatibility with SVID.
@end deftypefun

@comment signal.h
@comment ANSI
@deftypevr Macro sighandler_t SIG_ERR
The value of this macro is used as the return value from @code{signal}
to indicate an error.
@end deftypevr

@ignore
@comment RMS says that ``we don't do this''.
Implementations might define additional macros for built-in signal
actions that are suitable as a @var{action} argument to @code{signal},
besides @code{SIG_IGN} and @code{SIG_DFL}.  Identifiers whose names
begin with @samp{SIG_} followed by an uppercase letter are reserved for
this purpose.
@end ignore


@node Advanced Signal Handling
@subsection Advanced Signal Handling
@cindex @code{sigaction} function

The @code{sigaction} function has the same basic effect as
@code{signal}: to specify how a signal should be handled by the process.
However, @code{sigaction} offers more control, at the expense of more
complexity.  In particular, @code{sigaction} allows you to specify
additional flags to control when the signal is generated and how the
handler is invoked.

The @code{sigaction} function is declared in @file{signal.h}.
@pindex signal.h

@comment signal.h
@comment POSIX.1
@deftp {Data Type} {struct sigaction}
Structures of type @code{struct sigaction} are used in the
@code{sigaction} function to specify all the information about how to
handle a particular signal.  This structure contains at least the
following members:

@table @code
@item sighandler_t sa_handler
This is used in the same way as the @var{action} argument to the
@code{signal} function.  The value can be @code{SIG_DFL},
@code{SIG_IGN}, or a function pointer.  @xref{Basic Signal Handling}.

@item sigset_t sa_mask
This specifies a set of signals to be blocked while the handler runs.
Blocking is explained in @ref{Blocking for Handler}.  Note that the
signal that was delivered is automatically blocked by default before its
handler is started; this is true regardless of the value in
@code{sa_mask}.  If you want that signal not to be blocked within its
handler, you must write code in the handler to unblock it.

@item int sa_flags
This specifies various flags which can affect the behavior of 
the signal.  These are described in more detail in @ref{Flags for Sigaction}.
@end table
@end deftp

@comment signal.h
@comment POSIX.1
@deftypefun int sigaction (int @var{signum}, const struct sigaction *@var{action}, struct sigaction *@var{old-action})
The @var{action} argument is used to set up a new action for the signal
@var{signum}, while the @var{old-action} argument is used to return
information about the action previously associated with this symbol.
(In other words, @var{old-action} has the same purpose as the
@code{signal} function's return value---you can check to see what the
old action in effect for the signal was, and restore it later if you
want.)

Either @var{action} or @var{old-action} can be a null pointer.  If
@var{old-action} is a null pointer, this simply suppresses the return
of information about the old action.  If @var{action} is a null pointer,
the action associated with the signal @var{signum} is unchanged; this
allows you to inquire about how a signal is being handled without changing
that handling.

The return value from @code{sigaction} is zero if it succeeds, and
@code{-1} on failure.  The following @code{errno} error conditions are
defined for this function:

@table @code
@item EINVAL
The @var{signum} argument is not valid, or you are trying to
trap or ignore @code{SIGKILL} or @code{SIGSTOP}.
@end table
@end deftypefun

@node Signal and Sigaction
@subsection Interaction of @code{signal} and @code{sigaction}

It's possible to use both the @code{signal} and @code{sigaction}
functions within a single program, but you have to be careful because
they can interact in slightly strange ways.

The @code{sigaction} function specifies more information than the
@code{signal} function, so the return value from @code{signal} cannot
express the full range of @code{sigaction} possibilities.  Therefore, if
you use @code{signal} to save and later reestablish an action, it may
not be able to reestablish properly a handler that was established with
@code{sigaction}.

To avoid having problems as a result, always use @code{sigaction} to
save and restore a handler if your program uses @code{sigaction} at all.
Since @code{sigaction} is more general, it can properly save and
reestablish any action, regardless of whether it was established
originally with @code{signal} or @code{sigaction}.

On some systems if you establish an action with @code{signal} and then
examine it with @code{sigaction}, the handler address that you get may
not be the same as what you specified with @code{signal}.  It may not
even be suitable for use as an action argument with @code{signal}.  But
you can rely on using it as an argument to @code{sigaction}.  This
problem never happens on the GNU system.

So, you're better off using one or the other of the mechanisms
consistently within a single program.  

@strong{Portability Note:} The basic @code{signal} function is a feature
of ANSI C, while @code{sigaction} is part of the POSIX.1 standard.  If
you are concerned about portability to non-POSIX systems, then you
should use the @code{signal} function instead.

@node Sigaction Function Example
@subsection @code{sigaction} Function Example

In @ref{Basic Signal Handling}, we gave an example of establishing a
simple handler for termination signals using @code{signal}.  Here is an
equivalent example using @code{sigaction}:

@smallexample
#include <signal.h>

void
termination_handler (int signum)
@{
  struct temp_file *p;

  for (p = temp_file_list; p; p = p->next)
    unlink (p->name);
@}

int
main (void)
@{
  @dots{}
  struct sigaction new_action, old_action;

  /* @r{Set up the structure to specify the new action.} */
  new_action.sa_handler = termination_handler;
  sigemptyset (&new_action.sa_mask);
  new_action.sa_flags = 0;

  sigaction (SIGINT, NULL, &old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGINT, &new_action, NULL);
  sigaction (SIGHUP, NULL, &old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGHUP, &new_action, NULL);
  sigaction (SIGTERM, NULL, &old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGTERM, &new_action, NULL);
  @dots{}
@}
@end smallexample

The program just loads the @code{new_action} structure with the desired
parameters and passes it in the @code{sigaction} call.  The usage of
@code{sigemptyset} is described later; see @ref{Blocking Signals}.

As in the example using @code{signal}, we avoid handling signals
previously set to be ignored.  Here we can avoid altering the signal
handler even momentarily, by using the feature of @code{sigaction} that
lets us examine the current action without specifying a new one.

Here is another example.  It retrieves information about the current
action for @code{SIGINT} without changing that action.

@smallexample
struct sigaction query_action;

if (sigaction (SIGINT, NULL, &query_action) < 0)
  /* @r{@code{sigaction} returns -1 in case of error.} */ 
else if (query_action.sa_handler == SIG_DFL)
  /* @r{@code{SIGINT} is handled in the default, fatal manner.} */
else if (query_action.sa_handler == SIG_IGN)
  /* @r{@code{SIGINT} is ignored.} */
else
  /* @r{A programmer-defined signal handler is in effect.} */
@end smallexample

@node Flags for Sigaction
@subsection Flags for @code{sigaction}
@cindex signal flags
@cindex flags for @code{sigaction}
@cindex @code{sigaction} flags

The @code{sa_flags} member of the @code{sigaction} structure is a
catch-all for special features.  Most of the time, @code{SA_RESTART} is
a good value to use for this field.

The value of @code{sa_flags} is interpreted as a bit mask.  Thus, you
should choose the flags you want to set, @sc{or} those flags together,
and store the result in the @code{sa_flags} member of your
@code{sigaction} structure.

Each signal number has its own set of flags.  Each call to
@code{sigaction} affects one particular signal number, and the flags
that you specify apply only to that particular signal.

In the GNU C library, establishing a handler with @code{signal} sets all
the flags to zero except for @code{SA_RESTART}, whose value depends on
the settings you have made with @code{siginterrupt}.  @xref{Interrupted
Primitives}, to see what this is about.

@pindex signal.h
These macros are defined in the header file @file{signal.h}.

@comment signal.h
@comment POSIX.1
@deftypevr Macro int SA_NOCLDSTOP
This flag is meaningful only for the @code{SIGCHLD} signal.  When the
flag is set, the system delivers the signal for a terminated child
process but not for one that is stopped.  By default, @code{SIGCHLD} is
delivered for both terminated children and stopped children.

Setting this flag for a signal other than @code{SIGCHLD} has no effect.
@end deftypevr

@comment signal.h
@comment BSD
@deftypevr Macro int SA_ONSTACK
If this flag is set for a particular signal number, the system uses the
signal stack when delivering that kind of signal.  @xref{Signal Stack}.
If a signal with this flag arrives and you have not set a signal stack,
the system terminates the program with @code{SIGILL}.
@end deftypevr

@comment signal.h
@comment BSD
@deftypevr Macro int SA_RESTART
This flag controls what happens when a signal is delivered during
certain primitives (such as @code{open}, @code{read} or @code{write}),
and the signal handler returns normally.  There are two alternatives:
the library function can resume, or it can return failure with error
code @code{EINTR}.

The choice is controlled by the @code{SA_RESTART} flag for the
particular kind of signal that was delivered.  If the flag is set,
returning from a handler resumes the library function.  If the flag is
clear, returning from a handler makes the function fail.
@xref{Interrupted Primitives}.
@end deftypevr

@node Initial Signal Actions
@subsection Initial Signal Actions
@cindex initial signal actions

When a new process is created (@pxref{Creating a Process}), it inherits
handling of signals from its parent process.  However, when you load a
new process image using the @code{exec} function (@pxref{Executing a
File}), any signals that you've defined your own handlers for revert to
their @code{SIG_DFL} handling.  (If you think about it a little, this
makes sense; the handler functions from the old program are specific to
that program, and aren't even present in the address space of the new
program image.)  Of course, the new program can establish its own
handlers.

When a program is run by a shell, the shell normally sets the initial
actions for the child process to @code{SIG_DFL} or @code{SIG_IGN}, as
appropriate.  It's a good idea to check to make sure that the shell has
not set up an initial action of @code{SIG_IGN} before you establish your
own signal handlers.

Here is an example of how to establish a handler for @code{SIGHUP}, but
not if @code{SIGHUP} is currently ignored:

@smallexample
@group
@dots{}
struct sigaction temp;