   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.2.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.

Signals Arriving While a Handler Runs
-------------------------------------

   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 `sigprocmask', if you want to allow more
signals of this type to arrive; see Process Signal Mask.)

   However, your handler can still be interrupted by delivery of another
kind of signal.  To avoid this, you can use the `sa_mask' member of the
action structure passed to `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.  See
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 `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.

   *Portability Note:* Always use `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 `signal'
automatically sets the signal's action back to `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.

Signals Close Together Merge into One
-------------------------------------

   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 `SIGCHLD' that compensates for
the fact that the number of signals received may not equal the number of
child processes that generate them.  It assumes that the program keeps
track of all the child processes with a chain of structures as follows:

     struct process
     {
       struct process *next;
       /* The process ID of this child.  */
       int pid;
       /* The descriptor of the pipe or pseudo terminal
          on which output comes from this child.  */
       int input_descriptor;
       /* Nonzero if this process has stopped or terminated.  */
       sig_atomic_t have_status;
       /* The status of this child; 0 if running,
          otherwise a status value from `waitpid'.  */
       int status;
     };

     struct process *process_list;

   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.

     /* Nonzero means some child's status has changed
        so look at `process_list' for the details.  */
     int process_status_change;

   Here is the handler itself:

     void
     sigchld_handler (int signo)
     {
       int old_errno = errno;

       while (1) {
         register int pid;
         int w;
         struct process *p;

         /* 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) {
           /* A real failure means there are no more
              stopped or terminated child processes, so return.  */
           errno = old_errno;
           return;
         }

         /* 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;
             /* Indicate that the `status' field
                has data to look at.  We do this only after storing it.  */
             p->have_status = 1;

             /* 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);

             /* The program should check this flag from time to time
                to see if there is any news in `process_list'.  */
             ++process_status_change;
           }

         /* Loop around to handle all the processes
            that have something to tell us.  */
       }
     }

   Here is the proper way to check the flag `process_status_change':

     if (process_status_change) {
       struct process *p;
       process_status_change = 0;
       for (p = process_list; p; p = p->next)
         if (p->have_status) {
           ... Examine `p->status' ...
         }
     }

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 `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
`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.  See Atomic Usage, for more
information about coping with interruptions during accesses 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.

     sig_atomic_t process_status_change;

     sig_atomic_t last_process_status_change;

     ...
     {
       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) {
             ... Examine `p->status' ...
           }
       }
     }

Signal Handling and Nonreentrant 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 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 `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.

   * If your handler needs to access any global variables from your
     program, declare those variables `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.

   * If you call a function in the handler, make sure it is "reentrant"
     with respect to signals, or else make sure that the signal cannot
     interrupt a call to a related function.

   A function can be non-reentrant if it uses memory that is not on the
stack.

   * 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 `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 `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 `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.  Function descriptions in
     this manual always mention this behavior.

   * 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 `fprintf'.  Suppose that the
     program was in the middle of an `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.

   * On most systems, `malloc' and `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.

   * Any function that modifies `errno' is non-reentrant, but you can
     correct for this: in the handler, save the original value of
     `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.

   * 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.  See
     Atomic Data Access.

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

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 "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 be invoked 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 (see Blocking Signals).

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

     #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);
     }

     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;
          }
     }

   This program fills `memory' with zeros, ones, zeros, ones,
alternating forever; meanwhile, once per second, the alarm signal
handler prints the current contents.  (Calling `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 `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 `memory.a' is zero and
`memory.b' is one (or vice versa).

   On some machines it may be possible to store a new value in `memory'
with just one instruction that cannot be interrupted.  On these
machines, the handler will always print two zeros or two ones.

Atomic Types
............

   To avoid uncertainty about interrupting access to a variable, you can
use a particular data type for which access is always atomic:
`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 `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.

 - Data Type: sig_atomic_t
     This is an integer data type.  Objects of this type are always
     accessed atomically.

   In practice, you can assume that `int' and other integer types no
longer than `int' are atomic.  You can also assume that pointer types
are atomic; that is very convenient.  Both of these assumptions are
true on all of the machines that the GNU C library supports and on all
POSIX systems we know of.

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.  See Merged Signals, for an example.

Primitives Interrupted by Signals
=================================

   A signal can arrive and be handled while an I/O primitive such as
`open' or `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 `EINTR'.  This is flexible,
but usually inconvenient.  Typically, POSIX applications that use signal
handlers must check for `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 `TEMP_FAILURE_RETRY':

 - Macro: TEMP_FAILURE_RETRY (EXPRESSION)
     This macro evaluates EXPRESSION once.  If it fails and reports
     error code `EINTR', `TEMP_FAILURE_RETRY' evaluates it again, and
     over and over until the result is not a temporary failure.

     The value returned by `TEMP_FAILURE_RETRY' is whatever value
     EXPRESSION produced.

   BSD avoids `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 `EINTR'.

   You can choose either approach with the GNU library.  If you use
`sigaction' to establish a signal handler, you can specify how that
handler should behave.  If you specify the `SA_RESTART' flag, return
from that handler will resume a primitive; otherwise, return from that
handler will cause `EINTR'.  See Flags for Sigaction.

   Another way to specify the choice is with the `siginterrupt'
function.  See BSD Handler.

   When you don't specify with `sigaction' or `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 `_BSD_SOURCE' or `_GNU_SOURCE' before calling
`signal', the default is to resume primitives; otherwise, the default
is to make them fail with `EINTR'.  (The library contains alternate
versions of the `signal' function, and the feature test macros
determine which one you really call.)  See Feature Test Macros.

   The description of each primitive affected by this issue lists
`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 `read' or
`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; see Datagrams),
where splitting one `read' or `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.

Generating Signals
==================

   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.

Signaling Yourself
------------------

   A process can send itself a signal with the `raise' function.  This
function is declared in `signal.h'.

 - Function: int raise (int SIGNUM)
     The `raise' function sends the signal 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
     SIGNUM is invalid.

 - Function: int gsignal (int SIGNUM)
     The `gsignal' function does the same thing as `raise'; it is
     provided only for compatibility with SVID.

   One convenient use for `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 `C-z'; see Special Characters)
to send it an interactive stop signal (`SIGTSTP'), and
you want to clean up some internal data buffers before stopping.  You
might set this up like this:

     #include <signal.h>

     /* 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);
       /* Do cleanup actions here. */
       ...
       raise (SIGTSTP);
     }

     /* When the process is continued again, restore the signal handler. */

     void
     cont_handler (int sig)
     {
       signal (SIGCONT, cont_handler);
       signal (SIGTSTP, tstp_handler);
     }

     /* Enable both handlers during program initialization. */

     int
     main (void)
     {
       signal (SIGCONT, cont_handler);
       signal (SIGTSTP, tstp_handler);
       ...
     }

   *Portability note:* `raise' was invented by the ISO C committee.
Older systems may not support it, so using `kill' may be more portable.
See Signaling Another Process.

Signaling Another Process
-------------------------

   The `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:

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

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

   * Two processes need to synchronize while working together.

   This section assumes that you know a little bit about how processes
work.  For more information on this subject, see Processes.

   The `kill' function is declared in `signal.h'.

 - Function: int kill (pid_t PID, int SIGNUM)
     The `kill' function sends the signal SIGNUM to the process or
     process group specified by PID.  Besides the signals listed in
     Standard Signals, SIGNUM can also have a value of zero to
     check the validity of the PID.

     The PID specifies the process or process group to receive the
     signal:

    `PID > 0'
          The process whose identifier is PID.

    `PID == 0'
          All processes in the same process group as the sender.

    `PID < -1'
          The process group whose identifier is -PID.

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

     A process can send a signal to itself with a call like
     `kill (getpid(), SIGNUM)'.  If `kill' is used by a process to send
     a signal to itself, and the signal is not blocked, then `kill'
     delivers at least one signal (which might be some other pending
     unblocked signal instead of the signal SIGNUM) to that process
     before it returns.

     The return value from `kill' is zero if the signal can be sent
     successfully.  Otherwise, no signal is sent, and a value of `-1' is
     returned.  If PID specifies sending a signal to several processes,
     `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 `errno' error conditions are defined for this
     function:

    `EINVAL'
          The SIGNUM argument is an invalid or unsupported number.

    `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 PID.

    `ESCRH'
          The PID argument does not refer to an existing process or
          group.

 - Function: int killpg (int PGID, int SIGNUM)
     This is similar to `kill', but sends signal SIGNUM to the process
     group PGID.  This function is provided for compatibility with BSD;
     using `kill' to do this is more portable.

   As a simple example of `kill', the call `kill (getpid (), SIG)' has
the same effect as `raise (SIG)'.

Permission for using `kill'
---------------------------

   There are restrictions that prevent you from using `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, `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 `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 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 `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 `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.

Using `kill' for Communication
------------------------------

   Here is a longer example showing how signals can be used for
interprocess communication.  This is what the `SIGUSR1' and `SIGUSR2'
signals are provided for.  Since these signals are fatal by default,
the process that is supposed to receive them must trap them through
`signal' or `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 `SIGUSR1' signal,
using the `kill' function.

     #include <signal.h>
     #include <stdio.h>
     #include <sys/types.h>
     #include <unistd.h>

     /* When a `SIGUSR1' signal arrives, set this variable. */
     volatile sig_atomic_t usr_interrupt = 0;

     void
     synch_signal (int sig)
     {
       usr_interrupt = 1;
     }

     /* The child process executes this function. */
     void
     child_function (void)
     {
       /* Perform initialization. */
       printf ("I'm here!!!  My pid is %d.\n", (int) getpid ());

       /* Let parent know you're done. */
       kill (getppid (), SIGUSR1);

       /* Continue with execution. */
       puts ("Bye, now....");
       exit (0);
     }

     int
     main (void)
     {
       struct sigaction usr_action;
       sigset_t block_mask;
       pid_t child_id;

       /* Establish the signal handler. */
       sigfillset (&block_mask);
       usr_action.sa_handler = synch_signal;
       usr_action.sa_mask = block_mask;
       usr_action.sa_flags = 0;
       sigaction (SIGUSR1, &usr_action, NULL);

       /* Create the child process. */
       child_id = fork ();
       if (child_id == 0)
         child_function ();          /* Does not return. */

       /* Busy wait for the child to send a signal. */
       while (!usr_interrupt)
         ;

       /* Now continue execution. */
       puts ("That's all, folks!");

       return 0;
     }

   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
Waiting for a Signal.

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
`SIG_IGN'.  But it is useful to block signals briefly, to prevent them
from interrupting sensitive operations.  For instance:

   * You can use the `sigprocmask' function to block signals while you
     modify global variables that are also modified by the handlers for
     these signals.

   * You can set `sa_mask' in your `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.

Why Blocking Signals is Useful
------------------------------

   Temporary blocking of signals with `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
`sig_atomic_t' (see 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 `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.

Signal Sets
-----------

   All of the signal blocking functions use a data structure called a
"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.

   These facilities are declared in the header file `signal.h'.

 - Data Type: sigset_t
     The `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 `sigset_t'
     objects--don't try to manipulate them directly.

   There are two ways to initialize a signal set.  You can initially
specify it to be empty with `sigemptyset' and then add specified
signals individually.  Or you can specify it to be full with
`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 `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.)

 - Function: int sigemptyset (sigset_t *SET)
     This function initializes the signal set SET to exclude all of the
     defined signals.  It always returns `0'.

 - Function: int sigfillset (sigset_t *SET)
     This function initializes the signal set SET to include all of the
     defined signals.  Again, the return value is `0'.

 - Function: int sigaddset (sigset_t *SET, int SIGNUM)
     This function adds the signal SIGNUM to the signal set SET.  All
     `sigaddset' does is modify SET; it does not block or unblock any
     signals.

     The return value is `0' on success and `-1' on failure.  The
     following `errno' error condition is defined for this function:

    `EINVAL'
          The SIGNUM argument doesn't specify a valid signal.

 - Function: int sigdelset (sigset_t *SET, int SIGNUM)
     This function removes the signal SIGNUM from the signal set SET.
     All `sigdelset' does is modify SET; it does not block or unblock
     any signals.  The return value and error conditions are the same
     as for `sigaddset'.

   Finally, there is a function to test what signals are in a signal
set:

 - Function: int sigismember (const sigset_t *SET, int SIGNUM)
     The `sigismember' function tests whether the signal SIGNUM is a
     member of the signal set SET.  It returns `1' if the signal is in
     the set, `0' if not, and `-1' if there is an error.

     The following `errno' error condition is defined for this function:

    `EINVAL'
          The SIGNUM argument doesn't specify a valid signal.

Process Signal Mask
-------------------

   The collection of signals that are currently blocked is called the
"signal mask".  Each process has its own signal mask.  When you create
a new process (see 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 `sigprocmask' function is in `signal.h'.

 - Function: int sigprocmask (int HOW, const sigset_t *restrict SET,
          sigset_t *restrict OLDSET)
     The `sigprocmask' function is used to examine or change the calling
     process's signal mask.  The HOW argument determines how the signal
     mask is changed, and must be one of the following values:

    `SIG_BLOCK'
          Block the signals in `set'--add them to the existing mask.  In
          other words, the new mask is the union of the existing mask
          and SET.

    `SIG_UNBLOCK'
          Unblock the signals in SET--remove them from the existing
          mask.

    `SIG_SETMASK'
          Use SET for the mask; ignore the previous value of the mask.

     The last argument, 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 OLDSET argument.
     Similarly, if you want to know what's in the mask without changing
     it, pass a null pointer for SET (in this case the HOW argument is
     not significant).  The OLDSET argument is often used to remember
     the previous signal mask in order to restore it later.  (Since the
     signal mask is inherited over `fork' and `exec' calls, you can't
     predict what its contents are when your program starts running.)

     If invoking `sigprocmask' causes any pending signals to be
     unblocked, at least one of those signals is delivered to the
     process before `sigprocmask' returns.  The order in which pending
     signals are delivered is not specified, but you can control the
     order explicitly by making multiple `sigprocmask' calls to unblock
     various signals one at a time.

     The `sigprocmask' function returns `0' if successful, and `-1' to
     indicate an error.  The following `errno' error conditions are
     defined for this function:

    `EINVAL'
          The HOW argument is invalid.

     You can't block the `SIGKILL' and `SIGSTOP' signals, but if the
     signal set includes these, `sigprocmask' just ignores them instead
     of returning an error status.

     Remember, too, that blocking program error signals such as `SIGFPE'
     leads to undesirable results for signals generated by an actual
     program error (as opposed to signals sent with `raise' or `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.
     See Program Error Signals.

Blocking to Test for Delivery of a Signal
-----------------------------------------

   Now for a simple example.  Suppose you establish a handler for
`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 `SIGALRM' signals from arriving in the
meantime by wrapping the critical part of the code with calls to
`sigprocmask', like this:

     /* This variable is set by the SIGALRM signal handler. */
     volatile sig_atomic_t flag = 0;

     int
     main (void)
     {
       sigset_t block_alarm;

       ...

       /* Initialize the signal mask. */
       sigemptyset (&block_alarm);
       sigaddset (&block_alarm, SIGALRM);

       while (1)
         {
           /* Check if a signal has arrived; if so, reset the flag. */
           sigprocmask (SIG_BLOCK, &block_alarm, NULL);
           if (flag)
             {
               ACTIONS-IF-NOT-ARRIVED
               flag = 0;
             }
           sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);

           ...
         }
     }

Blocking Signals for 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 `SIGTSTP', for instance, then the arrival
of that signal forces further `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 `sa_mask' member of the
`sigaction' structure.

   Here is an example:

     #include <signal.h>
     #include <stddef.h>

     void catch_stop ();

     void
     install_handler (void)
     {
       struct sigaction setup_action;
       sigset_t block_mask;

       sigemptyset (&block_mask);
       /* 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);
     }

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

Checking for Pending Signals
----------------------------

   You can find out which signals are pending at any time by calling
`sigpending'.  This function is declared in `signal.h'.

 - Function: int sigpending (sigset_t *SET)
     The `sigpending' function stores information about pending signals
     in 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
     `sigismember'; see Signal Sets.)

     The return value is `0' if successful, and `-1' on failure.

   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.

     #include <signal.h>
     #include <stddef.h>

     sigset_t base_mask, waiting_mask;

     sigemptyset (&base_mask);
     sigaddset (&base_mask, SIGINT);
     sigaddset (&base_mask, SIGTSTP);

     /* Block user interrupts while doing other processing. */
     sigprocmask (SIG_SETMASK, &base_mask, NULL);
     ...

     /* After a while, check to see whether any signals are pending. */
     sigpending (&waiting_mask);
     if (sigismember (&waiting_mask, SIGINT)) {
       /* User has tried to kill the process. */
     }
     else if (sigismember (&waiting_mask, SIGTSTP)) {
       /* User has tried to stop the process. */
     }

   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 `SIGINT' signal is
pending when another `SIGINT' signal arrives, your program will
probably only see one of them when you unblock this signal.

   *Portability Note:* The `sigpending' function is new in POSIX.1.
Older systems have no equivalent facility.