linuxthreads/man/pthread_sigmask.man

   1 .TH PTHREAD_SIGNAL 3 LinuxThreads
   2
   3 .XREF pthread_kill
   4 .XREF sigwait
   5
   6 .SH NAME
   7 pthread_sigmask, pthread_kill, sigwait \- handling of signals in threads
   8
   9 .SH SYNOPSIS
  10 #include <pthread.h>
  11 .br
  12 #include <signal.h>
  13
  14 int pthread_sigmask(int how, const sigset_t *newmask, sigset_t *oldmask);
  15
  16 int pthread_kill(pthread_t thread, int signo);
  17
  18 int sigwait(const sigset_t *set, int *sig);
  19
  20 .SH DESCRIPTION
  21
  22 !pthread_sigmask! changes the signal mask for the calling thread as
  23 described by the |how| and |newmask| arguments. If |oldmask| is not
  24 !NULL!, the previous signal mask is stored in the location pointed to
  25 by |oldmask|.
  26
  27 The meaning of the |how| and |newmask| arguments is the same as for
  28 !sigprocmask!(2). If |how| is !SIG_SETMASK!, the signal mask is set to
  29 |newmask|. If |how| is !SIG_BLOCK!, the signals specified to |newmask|
  30 are added to the current signal mask.  If |how| is !SIG_UNBLOCK!, the
  31 signals specified to |newmask| are removed from the current signal
  32 mask.
  33
  34 Recall that signal masks are set on a per-thread basis, but signal
  35 actions and signal handlers, as set with !sigaction!(2), are shared
  36 between all threads.
  37
  38 !pthread_kill! send signal number |signo| to the thread
  39 |thread|. The signal is delivered and handled as described in
  40 !kill!(2).
  41
  42 !sigwait! suspends the calling thread until one of the signals
  43 in |set| is delivered to the calling thread. It then stores the number
  44 of the signal received in the location pointed to by |sig| and
  45 returns. The signals in |set| must be blocked and not ignored on
  46 entrance to !sigwait!. If the delivered signal has a signal handler
  47 function attached, that function is |not| called.
  48
  49 .SH CANCELLATION
  50
  51 !sigwait! is a cancellation point.
  52
  53 .SH "RETURN VALUE"
  54
  55 On success, 0 is returned. On failure, a non-zero error code is returned.
  56
  57 .SH ERRORS
  58
  59 The !pthread_sigmask! function returns the following error codes
  60 on error:
  61 .RS
  62 .TP
  63 !EINVAL!
  64 |how| is not one of !SIG_SETMASK!, !SIG_BLOCK!, or !SIG_UNBLOCK!
  65
  66 .TP
  67 !EFAULT!
  68 |newmask| or |oldmask| point to invalid addresses
  69 .RE
  70
  71 The !pthread_kill! function returns the following error codes
  72 on error:
  73 .RS
  74 .TP
  75 !EINVAL!
  76 |signo| is not a valid signal number
  77
  78 .TP
  79 !ESRCH!
  80 the thread |thread| does not exist (e.g. it has already terminated)
  81 .RE
  82
  83 The !sigwait! function never returns an error.
  84
  85 .SH AUTHOR
  86 Xavier Leroy <Xavier.Leroy@inria.fr>
  87
  88 .SH "SEE ALSO"
  89 !sigprocmask!(2),
  90 !kill!(2),
  91 !sigaction!(2),
  92 !sigsuspend!(2).
  93
  94 .SH NOTES
  95
  96 For !sigwait! to work reliably, the signals being waited for must be
  97 blocked in all threads, not only in the calling thread, since
  98 otherwise the POSIX semantics for signal delivery do not guarantee
  99 that it's the thread doing the !sigwait! that will receive the signal.
 100 The best way to achieve this is block those signals before any threads
 101 are created, and never unblock them in the program other than by
 102 calling !sigwait!.
 103
 104 .SH BUGS
 105
 106 Signal handling in LinuxThreads departs significantly from the POSIX
 107 standard. According to the standard, ``asynchronous'' (external)
 108 signals are addressed to the whole process (the collection of all
 109 threads), which then delivers them to one particular thread. The
 110 thread that actually receives the signal is any thread that does
 111 not currently block the signal.
 112
 113 In LinuxThreads, each thread is actually a kernel process with its own
 114 PID, so external signals are always directed to one particular thread.
 115 If, for instance, another thread is blocked in !sigwait! on that
 116 signal, it will not be restarted.
 117
 118 The LinuxThreads implementation of !sigwait! installs dummy signal
 119 handlers for the signals in |set| for the duration of the wait. Since
 120 signal handlers are shared between all threads, other threads must not
 121 attach their own signal handlers to these signals, or alternatively
 122 they should all block these signals (which is recommended anyway --
 123 see the Notes section).