1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>PTHREAD_SIGNAL(3) manual page</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
<META NAME="CREATED" CONTENT="20050504;18500100">
<META NAME="CHANGED" CONTENT="20050504;23005800">
<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at http://polyglotman.sourceforge.net/ -->
</HEAD>
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
<H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
<P><A HREF="index.html">Reference Index</A></P>
<P><A HREF="#toc">Table of Contents</A></P>
<H2><A HREF="#toc0" NAME="sect0">Name</A></H2>
<P>pthread_sigmask, pthread_kill, sigwait - handling of signals in
threads
</P>
<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
<P><B>#include <pthread.h></B> <BR><B>#include <signal.h></B>
</P>
<P><B>int pthread_sigmask(int </B><I>how</I><B>, const sigset_t
*</B><I>newmask</I><B>, sigset_t *</B><I>oldmask</I><B>);</B>
</P>
<P><B>int pthread_kill(pthread_t </B><I>thread</I><B>, int </B><I>signo</I><B>);</B>
</P>
<P><B>int sigwait(const sigset_t *</B>set, <B>int</B> *sig);</P>
<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
<P><B>pthread_sigmask</B> changes the signal mask for the calling
thread as described by the <I>how</I> and <I>newmask</I> arguments.
If <I>oldmask</I> is not <B>NULL</B>, the previous signal mask is
stored in the location pointed to by <I>oldmask</I>. <B>Pthreads-w32</B>
implements this function but no other function uses the signal mask
yet.</P>
<P>The meaning of the <I>how</I> and <I>newmask</I> arguments is the
same as for <B><SPAN STYLE="font-style: normal">sigprocmask</SPAN></B>(2).
If <I>how</I> is <B>SIG_SETMASK</B>, the signal mask is set to
<I>newmask</I>. If <I>how</I> is <B>SIG_BLOCK</B>, the signals
specified to <I>newmask</I> are added to the current signal mask. If
<I>how</I> is <B>SIG_UNBLOCK</B>, the signals specified to <I>newmask</I>
are removed from the current signal mask.
</P>
<P>Recall that signal masks are set on a per-thread basis, but signal
actions and signal handlers, as set with <B>sigaction</B>(2), are
shared between all threads.
</P>
<P><B>pthread_kill</B> send signal number <I>signo</I> to the thread
<I>thread</I>. <B>Pthreads-w32</B> only supports signal number 0,
which does not send any signal but causes <B>pthread_kill</B> to
return an error if <I>thread</I> is not valid.</P>
<P><B>sigwait</B> suspends the calling thread until one of the
signals in <I>set</I> is delivered to the calling thread. It then
stores the number of the signal received in the location pointed to
by <I>sig</I> and returns. The signals in <I>set</I> must be blocked
and not ignored on entrance to <B>sigwait</B>. If the delivered
signal has a signal handler function attached, that function is <I>not</I>
called. <B>Pthreads-w32</B> implements this function as a
cancellation point only - it does not wait for any signals and does
not change the location pointed to by <I>sig</I>.</P>
<H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
<P><B>sigwait</B> is a cancellation point.
</P>
<H2><A HREF="#toc4" NAME="sect4">Return Value</A></H2>
<P>On success, 0 is returned. On failure, a non-zero error code is
returned.
</P>
<H2><A HREF="#toc5" NAME="sect5">Errors</A></H2>
<P>The <B>pthread_sigmask</B> function returns the following error
codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<I>how</I> is not one of <B>SIG_SETMASK</B>, <B>SIG_BLOCK</B>, or
<B>SIG_UNBLOCK</B>
</DD></DL>
</DL>
<P>
The <B>pthread_kill</B> function returns the following error codes on
error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<I>signo</I> is not a valid signal number or is unsupported.</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<B>ESRCH</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the thread <I>thread</I> does not exist (e.g. it has already
terminated)
</DD></DL>
</DL>
<P>
The <B>sigwait</B> function never returns an error.
</P>
<H2><A HREF="#toc6" NAME="sect6">Author</A></H2>
<P>Xavier Leroy <Xavier.Leroy@inria.fr>
</P>
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
<H2><A HREF="#toc7" NAME="sect7">See Also</A></H2>
<P>
</P>
<H2><A HREF="#toc8" NAME="sect8">Notes</A></H2>
<P>In any implementation, for <B>sigwait</B> 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 <B>sigwait</B>
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 <B>sigwait</B>. This works
because all threads inherit their initial sigmask from their creating
thread.</P>
<H2><A HREF="#toc9" NAME="sect9">Bugs</A></H2>
<P><B>Pthreads-w32</B> does not implement signals yet and so these
routines have almost no use except to prevent the compiler or linker
from complaining. <B>pthread_kill</B> 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. <B>Pthreads-w32</B> from version 1.0.0
onwards implements pseudo-unique thread IDs, so applications that use
this technique (but really shouldn't) have some protection.</P>
<HR>
<P><A NAME="toc"></A><B>Table of Contents</B></P>
<UL>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Return
Value</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Errors</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Author</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">See
Also</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">Notes</A>
</P>
<LI><P><A HREF="#sect9" NAME="toc9">Bugs</A>
</P>
</UL>
</BODY>
</HTML>
|
