PTHREAD_SIGNAL(3)

NAME
       pthread_sigmask,  pthread_kill, sigwait - handling of sig-
       nals in threads

SYNOPSIS
       #include <<pthread.h>>
       #include <<signal.h>>

       int  pthread_sigmask(int  how,  const  sigset_t  *newmask,
       sigset_t *oldmask);

       int pthread_kill(pthread_t thread, int signo);

       int sigwait(const sigset_t *set, int *sig);

DESCRIPTION
       pthread_sigmask  changes  the  signal mask for the calling
       thread as described by the how and newmask  arguments.  If
       oldmask is not NULL, the previous signal mask is stored in
       the location pointed to by oldmask.

       The meaning of the how and newmask arguments is  the  same
       as  for sigprocmask(2).  If how is SIG_SETMASK, the signal
       mask is set to newmask.  If how is SIG_BLOCK, the  signals
       specified to newmask are added to the current signal mask.
       If how is SIG_UNBLOCK, the signals  specified  to  newmask
       are removed from the current signal mask.

       Recall  that  signal  masks are set on a per-thread basis,
       but signal actions and signal handlers, as set with sigac-
       tion(2), are shared between all threads.

       pthread_kill  send  signal  number  signo  to  the  thread
       thread.  The signal is delivered and handled as  described
       in kill(2).

       sigwait  suspends the calling thread until one of the sig-
       nals in set is delivered to the calling  thread.  It  then
       stores  the  number of the signal received in the location
       pointed to by sig and returns. The signals in set must  be
       blocked  and  not  ignored on entrance to sigwait.  If the
       delivered signal has a signal handler  function  attached,
       that function is not called.

CANCELLATION
       sigwait is a cancellation point.

RETURN VALUE
       On  success,  0  is returned. On failure, a non-zero error
       code is returned.

ERRORS
       The pthread_sigmask function returns the  following  error
       codes on error:
              EINVAL how is not one of SIG_SETMASK, SIG_BLOCK, or
                     SIG_UNBLOCK
              EFAULT newmask  or   oldmask   point   to   invalid
                     addresses

       The  pthread_kill  function  returns  the  following error
       codes on error:
              EINVAL signo is not a valid signal number
              ESRCH  the thread thread does not  exist  (e.g.  it
                     has already terminated)

       The sigwait function never returns an error.

AUTHOR
       Xavier Leroy lt;Xavier.Leroy@inria.fr

SEE ALSO
       sigprocmask(2) kill(2) sigaction(2) sigsuspend(2). 

NOTES
       For sigwait to work reliably, the signals being waited for
       must be blocked in all threads, not only  in  the  calling
       thread,  since  otherwise  the  POSIX semantics for signal
       delivery do not guarantee that it's the thread  doing  the
       sigwait  that  will  receive  the signal.  The best way to
       achieve this is block those signals before any threads are
       created,  and never unblock them in the program other than
       by calling sigwait.

BUGS
       Signal handling in LinuxThreads departs significantly from
       the  POSIX  standard.  According  to the standard, ``asyn-
       chronous'' (external) signals are addressed to  the  whole
       process (the collection of all threads), which then deliv-
       ers them to one particular thread. The thread  that  actu-
       ally  receives the signal is any thread that does not cur-
       rently block the signal.

       In LinuxThreads, each thread is actually a kernel  process
       with  its own PID, so external signals are always directed
       to one  particular  thread.   If,  for  instance,  another

       thread  is  blocked in sigwait on that signal, it will not
       be restarted.

       The LinuxThreads implementation of sigwait installs  dummy
       signal handlers for the signals in set for the duration of
       the wait. Since signal handlers  are  shared  between  all
       threads,  other  threads  must not attach their own signal
       handlers to these signals, or  alternatively  they  should
       all  block  these  signals (which is recommended anyway --
       see the Notes section).