pthread_sigmask, pthread_kill, sigwait - handling of signals in threads
#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);
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. Pthreads-w32 implements this function but no other function uses the signal mask yet.
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. Pthreads-w32 only supports signal number 0, which does not send any signal but causes pthread_kill to return an error if thread is not valid.
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. Pthreads-w32 implements this function as a cancellation point only - it does not wait for any signals and does not change the location pointed to by sig.
sigwait is a cancellation point.
On success, 0 is returned. On failure, a non-zero error code is returned.
The pthread_sigmask function returns the following error codes on error:
The pthread_kill function returns the following error codes on error:
The sigwait function never returns an error.
Xavier Leroy <Xavier.Leroy@inria.fr>
Modified by Ross Johnson for use with Pthreads-w32.
In any implementation, 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 to block those signals before any threads are created, and never unblock them in the program other than by calling sigwait. This works because all threads inherit their initial sigmask from their creating thread.
Pthreads-w32 does not implement signals yet and so these routines have almost no use except to prevent the compiler or linker from complaining. pthread_kill is useful in determining if the thread is a valid thread, but since many threads implementations reuse thread IDs, the valid thread may no longer be the thread you think it is, and so this method of determining thread validity is not portable, and very risky. Pthreads-w32 from version 1.0.0 onwards implements pseudo-unique thread IDs, so applications that use this technique (but really shouldn't) have some protection.