Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PTHREAD_SIGNAL(3)	   Library Functions Manual	     PTHREAD_SIGNAL(3)

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

       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  de-
       scribed	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  sig-
       procmask(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  ac-
       tions 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  sig-
       nal 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.

       sigwait is a cancellation point.

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

       The  pthread_sigmask  function returns the following error codes	on er-

	      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

       The sigwait function never returns an error.

       Xavier Leroy <>

       sigprocmask(2), kill(2),	sigaction(2), sigsuspend(2).

       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.

       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  han-
       dlers 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)


Want to link to this manual page? Use this URL:

home | help