PTHREAD_SIGNAL(3)					     Library Functions Manual						 PTHREAD_SIGNAL(3)

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) sig-
       nals 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)