Provided by: glibc-doc_2.3.6-0ubuntu20_all bug

NAME

       pthread_sigmask, pthread_kill, sigwait - handling of signals 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  !sigaction!(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 signals 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 <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,  ‘‘asynchronous’’  (external)
       signals are addressed to the  whole  process  (the  collection  of  all
       threads), which then delivers them to one particular thread. The thread
       that actually receives the signal is any thread that does not currently
       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).

                                 LinuxThreads                PTHREAD_SIGNAL(3)