← Back to branch summary

~ubuntu-branches/ubuntu/natty/clamav/natty-security

« back to all changes in this revision

Viewing changes to win32/3rdparty/pthreads/manual/sem_init.html

  • Committer: Bazaar Package Importer
  • Author(s): Scott Kitterman
  • Date: 2011-02-19 09:51:33 UTC
  • mfrom: (0.35.19 sid)
  • Revision ID: james.westby@ubuntu.com-20110219095133-sde2dyj8a6bjbkdh
Tags: 0.97+dfsg-0ubuntu1
* Merge from debian unstable (0ubuntu1 because the Debian upload was
  inadvertently left marked UNRELEASED).  Remaining changes:
  - Drop initial signature definitions from clamav-base
  - Drop build-dep on electric-fence (in Universe)
  - Add apparmor profiles for clamd and freshclam along with maintainer
    script changes

Show diffs side-by-side

added added

removed removed

Lines of Context:
win32/3rdparty/pthreads/manual/sem_init.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
2
<HTML>
 
3
<HEAD>
 
4
        <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
 
5
        <TITLE>SEMAPHORES(3) manual page</TITLE>
 
6
        <META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3  (Linux)">
 
7
        <META NAME="CREATED" CONTENT="20050505;14061900">
 
8
        <META NAME="CHANGED" CONTENT="20050514;195200">
 
9
        <!-- manual page source format generated by PolyglotMan v3.2, -->
 
10
        <!-- available at http://polyglotman.sourceforge.net/ -->
 
11
</HEAD>
 
12
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
 
13
<H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
 
14
<P><A HREF="index.html">Reference Index</A></P>
 
15
<P><A HREF="#toc">Table of Contents</A></P>
 
16
<H2><A HREF="#toc0" NAME="sect0">Name</A></H2>
 
17
<P>sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue,
 
18
sem_destroy - operations on semaphores 
 
19
</P>
 
20
<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
 
21
<P><B>#include &lt;semaphore.h&gt;</B> 
 
22
</P>
 
23
<P><B>int sem_init(sem_t *</B><I>sem</I><B>, int </B><I>pshared</I><B>,
 
24
unsigned int </B><I>value</I><B>);</B> 
 
25
</P>
 
26
<P><B>int sem_wait(sem_t * </B><I>sem</I><B>);</B> 
 
27
</P>
 
28
<P><B>int sem_timedwait(sem_t * </B><I>sem</I>, <B>const struct
 
29
timespec *</B><I>abstime</I><B>);</B> 
 
30
</P>
 
31
<P><B>int sem_trywait(sem_t * </B><I>sem</I><B>);</B> 
 
32
</P>
 
33
<P><B>int sem_post(sem_t * </B><I>sem</I><B>);</B> 
 
34
</P>
 
35
<P><B>int sem_post_multiple(sem_t * </B><I>sem, </I><B>int</B>
 
36
<I>number</I><B>);</B> 
 
37
</P>
 
38
<P><B>int sem_getvalue(sem_t * </B><I>sem</I><B>, int * </B><I>sval</I><B>);</B>
 
39
</P>
 
40
<P><B>int sem_destroy(sem_t * </B><I>sem</I><B>);</B> 
 
41
</P>
 
42
<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
 
43
<P>Semaphores are counters for resources shared between threads. The
 
44
basic operations on semaphores are: increment the counter atomically,
 
45
and wait until the counter is non-null and decrement it atomically. 
 
46
</P>
 
47
<P><B>sem_init</B> initializes the semaphore object pointed to by
 
48
<I>sem</I>. The count associated with the semaphore is set initially
 
49
to <I>value</I>. The <I>pshared</I> argument indicates whether the
 
50
semaphore is local to the current process ( <I>pshared</I> is zero)
 
51
or is to be shared between several processes ( <I>pshared</I> is not
 
52
zero).</P>
 
53
<P><B>Pthreads-w32</B> currently does not support process-shared
 
54
semaphores, thus <B>sem_init</B> always returns with error <B>EPERM</B>
 
55
if <I>pshared</I> is not zero. 
 
56
</P>
 
57
<P><B>sem_wait</B> atomically decrements <I>sem</I>'s count if it is
 
58
greater than 0 and returns immediately or it suspends the calling
 
59
thread until it can resume following a call to <B>sem_post</B> or
 
60
<B>sem_post_multiple</B>.</P>
 
61
<P><B>sem_timedwait</B> atomically decrements <I>sem</I>'s count if
 
62
it is greater than 0 and returns immediately, or it suspends the
 
63
calling thread. If <I>abstime</I> time arrives before the thread can
 
64
resume following a call to <B>sem_post</B> or <B>sem_post_multiple</B>,
 
65
then <B>sem_timedwait</B> returns with a return code of -1 after
 
66
having set <B>errno</B> to <B>ETIMEDOUT</B>. If the call can return
 
67
without suspending then <I>abstime</I> is not checked.</P>
 
68
<P><B>sem_trywait</B> atomically decrements <I>sem</I>'s count if it
 
69
is greater than 0 and returns immediately, or it returns immediately
 
70
with a return code of -1 after having set <B>errno</B> to <B>EAGAIN</B>.
 
71
<B>sem_trywait</B> never blocks.</P>
 
72
<P><B>sem_post</B> either releases one thread if there are any
 
73
waiting on <I>sem</I>, or it atomically increments <I>sem</I>'s
 
74
count.</P>
 
75
<P><B>sem_post_multiple</B> either releases multiple threads if there
 
76
are any waiting on <I>sem</I> and/or it atomically increases <I>sem</I>'s
 
77
count. If there are currently <I>n</I> waiters, where <I>n</I> the
 
78
largest number less than or equal to <I>number</I>, then <I>n</I>
 
79
waiters are released and <I>sem</I>'s count is incremented by <I>number</I>
 
80
minus <I>n</I>.</P>
 
81
<P><B>sem_getvalue</B> stores in the location pointed to by <I>sval</I>
 
82
the current count of the semaphore <I>sem</I>. In the <B>Pthreads-w32</B>
 
83
implementation: if the value returned in <I>sval</I> is greater than
 
84
or equal to 0 it was the <I>sem</I>'s count at some point during the
 
85
call to <B>sem_getvalue</B>. If the value returned in <I>sval</I> is
 
86
less than 0 then it's absolute value represents the number of threads
 
87
waiting on <I>sem</I> at some point during the call to <B>sem_getvalue.
 
88
</B>POSIX does not require an implementation of <B>sem_getvalue</B>
 
89
to return a value in <I>sval</I> that is less than 0, but if it does
 
90
then it's absolute value must represent the number of waiters.</P>
 
91
<P><B>sem_destroy</B> destroys a semaphore object, freeing the
 
92
resources it might hold. No threads should be waiting on the
 
93
semaphore at the time <B>sem_destroy</B> is called.</P>
 
94
<H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
 
95
<P><B>sem_wait</B> and <B>sem_timedwait</B> are cancellation points. 
 
96
</P>
 
97
<H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2>
 
98
<P>These routines are not async-cancel safe.</P>
 
99
<H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2>
 
100
<P>All semaphore functions return 0 on success, or -1 on error in
 
101
which case they write an error code in <B>errno</B>. 
 
102
</P>
 
103
<H2><A HREF="#toc6" NAME="sect6">Errors</A></H2>
 
104
<P>The <B>sem_init</B> function sets <B>errno</B> to the following
 
105
codes on error: 
 
106
</P>
 
107
<DL>
 
108
        <DL>
 
109
                <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B> 
 
110
                </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 
111
                <I>value</I> exceeds the maximal counter value <B>SEM_VALUE_MAX</B>
 
112
                                </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 
113
                <B>ENOSYS</B> 
 
114
                </DT></DL>
 
115
</DL>
 
116
<BLOCKQUOTE STYLE="margin-left: 3cm">
 
117
<I>pshared</I> is not zero 
 
118
</BLOCKQUOTE>
 
119
<P>The <B>sem_timedwait</B> function sets <B>errno</B> to the
 
120
following error code on error: 
 
121
</P>
 
122
<DL>
 
123
        <DL>
 
124
                <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B>
 
125
                                </DT></DL>
 
126
</DL>
 
127
<BLOCKQUOTE STYLE="margin-left: 3cm">
 
128
if <I>abstime</I> arrives before the waiting thread can resume
 
129
following a call to <B>sem_post</B> or <B>sem_post_multiple</B>. 
 
130
</BLOCKQUOTE>
 
131
<P>The <B>sem_trywait</B> function sets <B>errno</B> to the following
 
132
error code on error: 
 
133
</P>
 
134
<DL>
 
135
        <DL>
 
136
                <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EAGAIN</B> 
 
137
                </DT></DL>
 
138
</DL>
 
139
<BLOCKQUOTE STYLE="margin-left: 3cm">
 
140
if the semaphore count is currently 0 
 
141
</BLOCKQUOTE>
 
142
<P>The <B>sem_post</B> and <B>sem_post_multiple</B> functions set
 
143
<B>errno</B> to the following error code on error: 
 
144
</P>
 
145
<DL>
 
146
        <DL>
 
147
                <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ERANGE</B> 
 
148
                </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 
149
                if after incrementing, the semaphore count would exceed
 
150
                <B>SEM_VALUE_MAX</B> (the semaphore count is left unchanged in this
 
151
                case) 
 
152
                </DD></DL>
 
153
</DL>
 
154
<P>
 
155
The <B>sem_destroy</B> function sets <B>errno</B> to the following
 
156
error code on error: 
 
157
</P>
 
158
<DL>
 
159
        <DL>
 
160
                <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B> 
 
161
                </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 
162
                if some threads are currently blocked waiting on the semaphore. 
 
163
                </DD></DL>
 
164
</DL>
 
165
<H2>
 
166
<A HREF="#toc7" NAME="sect7">Author</A></H2>
 
167
<P>Xavier Leroy &lt;Xavier.Leroy@inria.fr&gt; 
 
168
</P>
 
169
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
 
170
<H2><A HREF="#toc8" NAME="sect8">See Also</A></H2>
 
171
<P><A HREF="pthread_mutex_init.html"><B>pthread_mutex_init</B>(3)</A>
 
172
, <A HREF="pthread_cond_init.html"><B>pthread_cond_init</B>(3)</A> ,
 
173
<A HREF="pthread_cancel.html"><B>pthread_cancel</B>(3)</A> . 
 
174
</P>
 
175
<HR>
 
176
<P><A NAME="toc"></A><B>Table of Contents</B></P>
 
177
<UL>
 
178
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
 
179
                </P>
 
180
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
 
181
                </P>
 
182
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
 
183
                </P>
 
184
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
 
185
                </P>
 
186
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal
 
187
        Safety</A> 
 
188
        </P>
 
189
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return
 
190
        Value</A> 
 
191
        </P>
 
192
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A>
 
193
                </P>
 
194
        <LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A>
 
195
                </P>
 
196
        <LI><P><A HREF="#sect8" NAME="toc8">See Also</A> 
 
197
        </P>
 
198
</UL>
 
199
</BODY>
 
200
</HTML>
 
 
b'\\ No newline at end of file'