manual/pthread_cond_init.html - platform/external/pthreads - Git at Google

 <!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_COND(3) manual page</TITLE>
 	<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3  (Linux)">
 	<META NAME="CREATED" CONTENT="20050504;16454400">
 	<META NAME="CHANGED" CONTENT="20050505;19004700">
 	<!-- 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_cond_init, pthread_cond_destroy, pthread_cond_signal,
 pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait -
 operations on conditions
 </P>
 <H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
 <P><B>#include &lt;pthread.h&gt;</B>
 </P>
 <P><B>pthread_cond_t </B><I>cond</I> <B>= PTHREAD_COND_INITIALIZER;</B>
 </P>
 <P><B>int pthread_cond_init(pthread_cond_t *</B><I>cond</I><B>,
 pthread_condattr_t *</B><I>cond_attr</I><B>);</B>
 </P>
 <P><B>int pthread_cond_signal(pthread_cond_t *</B><I>cond</I><B>);</B>
 </P>
 <P><B>int pthread_cond_broadcast(pthread_cond_t *</B><I>cond</I><B>);</B>
 </P>
 <P><B>int pthread_cond_wait(pthread_cond_t *</B><I>cond</I><B>,
 pthread_mutex_t *</B><I>mutex</I><B>);</B>
 </P>
 <P><B>int pthread_cond_timedwait(pthread_cond_t *</B><I>cond</I><B>,
 pthread_mutex_t *</B><I>mutex</I><B>, const struct timespec
 *</B><I>abstime</I><B>);</B>
 </P>
 <P><B>int pthread_cond_destroy(pthread_cond_t *</B><I>cond</I><B>);</B>
 </P>
 <H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
 <P>A condition (short for ‘‘condition variable’’) is a
 synchronization device that allows threads to suspend execution and
 relinquish the processors until some predicate on shared data is
 satisfied. The basic operations on conditions are: signal the
 condition (when the predicate becomes true), and wait for the
 condition, suspending the thread execution until another thread
 signals the condition.
 </P>
 <P>A condition variable must always be associated with a mutex, to
 avoid the race condition where a thread prepares to wait on a
 condition variable and another thread signals the condition just
 before the first thread actually waits on it.
 </P>
 <P><B>pthread_cond_init</B> initializes the condition variable <I>cond</I>,
 using the condition attributes specified in <I>cond_attr</I>, or
 default attributes if <I>cond_attr</I> is <B>NULL</B>.
 </P>
 <P>Variables of type <B>pthread_cond_t</B> can also be initialized
 statically, using the constant <B>PTHREAD_COND_INITIALIZER</B>. In
 the <B>Pthreads-w32</B> implementation, an application should still
 call <B>pthread_cond_destroy</B> at some point to ensure that any
 resources consumed by the condition variable are released.</P>
 <P><B>pthread_cond_signal</B> restarts one of the threads that are
 waiting on the condition variable <I>cond</I>. If no threads are
 waiting on <I>cond</I>, nothing happens. If several threads are
 waiting on <I>cond</I>, exactly one is restarted, but it is not
 specified which.
 </P>
 <P><B>pthread_cond_broadcast</B> restarts all the threads that are
 waiting on the condition variable <I>cond</I>. Nothing happens if no
 threads are waiting on <I>cond</I>.
 </P>
 <P><B>pthread_cond_wait</B> atomically unlocks the <I>mutex</I> (as
 per <B>pthread_unlock_mutex</B>) and waits for the condition variable
 <I>cond</I> to be signalled. The thread execution is suspended and
 does not consume any CPU time until the condition variable is
 signalled. The <I>mutex</I> must be locked by the calling thread on
 entrance to <B>pthread_cond_wait</B>. Before returning to the calling
 thread, <B>pthread_cond_wait</B> re-acquires <I>mutex</I> (as per
 <B>pthread_lock_mutex</B>).
 </P>
 <P>Unlocking the mutex and suspending on the condition variable is
 done atomically. Thus, if all threads always acquire the mutex before
 signalling the condition, this guarantees that the condition cannot
 be signalled (and thus ignored) between the time a thread locks the
 mutex and the time it waits on the condition variable.
 </P>
 <P><B>pthread_cond_timedwait</B> atomically unlocks <I>mutex</I> and
 waits on <I>cond</I>, as <B>pthread_cond_wait</B> does, but it also
 bounds the duration of the wait. If <I>cond</I> has not been
 signalled within the amount of time specified by <I>abstime</I>, the
 mutex <I>mutex</I> is re-acquired and <B>pthread_cond_timedwait</B>
 returns the error <B>ETIMEDOUT</B>. The <I>abstime</I> parameter
 specifies an absolute time, with the same origin as <A HREF="time.html"><B>time</B>(2)</A>
 and <A HREF="gettimeofday.html"><B>gettimeofday</B>(2)</A>.
 </P>
 <P><B>pthread_cond_destroy</B> destroys a condition variable, freeing
 the resources it might hold. No threads must be waiting on the
 condition variable on entrance to <B>pthread_cond_destroy</B>.</P>
 <H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
 <P><B>pthread_cond_wait</B> and <B>pthread_cond_timedwait</B> are
 cancellation points. If a thread is cancelled while suspended in one
 of these functions, the thread immediately resumes execution, then
 locks again the <I>mutex</I> argument to <B>pthread_cond_wait</B> and
 <B>pthread_cond_timedwait</B>, and finally executes the cancellation.
 Consequently, cleanup handlers are assured that <I>mutex</I> is
 locked when they are called.
 </P>
 <H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2>
 <P>The condition functions are not async-signal safe, and should not
 be called from a signal handler. In particular, calling
 <B>pthread_cond_signal</B> or <B>pthread_cond_broadcast</B> from a
 signal handler may deadlock the calling thread.
 </P>
 <H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2>
 <P>All condition variable functions return 0 on success and a
 non-zero error code on error.
 </P>
 <H2><A HREF="#toc6" NAME="sect6">Errors</A></H2>
 <P><B>pthread_cond_init</B>, <B>pthread_cond_signal</B>,
 <B>pthread_cond_broadcast</B>, and <B>pthread_cond_wait</B> never
 return an error code.
 </P>
 <P>The <B>pthread_cond_init</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">
 		The <I>cond</I> argument is invalid.
 		</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 		<B>ENOMEM</B>
 		</DT></DL>
 </DL>
 <BLOCKQUOTE STYLE="margin-left: 4cm">
 There was not enough memory to allocate the condition variable.
 </BLOCKQUOTE>
 <P>The <B>pthread_cond_signal</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">
 		The <I>cond</I> argument is invalid.
 		</DD></DL>
 </DL>
 <P>
 The <B>pthread_cond_broadcast</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">
 		The <I>cond</I> argument is invalid.
 		</DD></DL>
 </DL>
 <P>
 The <B>pthread_cond_wait</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">
 		The <I>cond</I> argument is invalid.
 		</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 		<B>ENOMEM</B>
 		</DT></DL>
 </DL>
 <BLOCKQUOTE STYLE="margin-left: 4cm">
 There was not enough memory to allocate the statically initialised
 condition variable. Statically initialised condition variables are
 dynamically allocated by the first thread to wait on them.</BLOCKQUOTE>
 <P>The <B>pthread_cond_timedwait</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></DL>
 </DL>
 <P STYLE="margin-left: 2cm">
 The <I>cond</I> argument is invalid.
 </P>
 <DL>
 	<DL>
 		<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B>
 				</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 		The condition variable was not signalled before the timeout
 		specified by <I>abstime</I>
 		</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 		<B>ENOMEM</B>
 		</DT></DL>
 </DL>
 <BLOCKQUOTE STYLE="margin-left: 4cm">
 There was not enough memory to allocate the statically initialised
 condition variable. Statically initialised condition variables are
 dynamically allocated by the first thread to wait on them.
 </BLOCKQUOTE>
 <P>The <B>pthread_cond_destroy</B> function returns the following
 error code on error:
 </P>
 <DL>
 	<DL>
 		<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
 		</DT></DL>
 </DL>
 <P STYLE="margin-left: 2cm; margin-right: 1cm">
 The <I>cond</I> argument is invalid.
 </P>
 <DL>
 	<DL>
 		<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B>
 		</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
 		Some threads are currently waiting on <I>cond</I>.
 		</DD></DL>
 </DL>
 <H2>
 <A HREF="#toc7" NAME="sect7">Author</A></H2>
 <P>Xavier Leroy &lt;Xavier.Leroy@inria.fr&gt;
 </P>
 <P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
 <H2><A HREF="#toc8" NAME="sect8">See Also</A></H2>
 <P><A HREF="pthread_condattr_init.html"><B>pthread_condattr_init</B>(3)</A>
 , <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
 , <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
 , <A HREF="pthread_cancel.html"><B>pthread_cancel(3)</B></A>.
 </P>
 <H2><A HREF="#toc9" NAME="sect9">Example</A></H2>
 <P>Consider two shared variables <I>x</I> and <I>y</I>, protected by
 the mutex <I>mut</I>, and a condition variable <I>cond</I> that is to
 be signaled whenever <I>x</I> becomes greater than <I>y</I>.
 </P>
 <PRE STYLE="margin-left: 1cm; margin-right: 1cm">int x,y;
 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
 pthread_cond_t cond = PTHREAD_COND_INITIALIZER;</PRE><BLOCKQUOTE>
 Waiting until <I>x</I> is greater than <I>y</I> is performed as
 follows:
 </BLOCKQUOTE>
 <PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&amp;mut);
 while (x &lt;= y) {
         pthread_cond_wait(&amp;cond, &amp;mut);
 }
 /* operate on x and y */
 pthread_mutex_unlock(&amp;mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
 Modifications on <I>x</I> and <I>y</I> that may cause <I>x</I> to
 become greater than <I>y</I> should signal the condition if needed:
 </BLOCKQUOTE>
 <PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&amp;mut);
 /* modify x and y */
 if (x &gt; y) pthread_cond_broadcast(&amp;cond);
 pthread_mutex_unlock(&amp;mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
 If it can be proved that at most one waiting thread needs to be waken
 up (for instance, if there are only two threads communicating through
 <I>x</I> and <I>y</I>), <B>pthread_cond_signal</B> can be used as a
 slightly more efficient alternative to <B>pthread_cond_broadcast</B>.
 If in doubt, use <B>pthread_cond_broadcast</B>.
 </BLOCKQUOTE>
 <BLOCKQUOTE STYLE="margin-left: 3.01cm">To wait for <I>x</I> to
 become greater than <I>y</I> with a timeout of 5 seconds, do:
 </BLOCKQUOTE>
 <PRE STYLE="margin-left: 1.01cm">struct timeval now;
 struct timespec timeout;
 int retcode;
 pthread_mutex_lock(&amp;mut);
 gettimeofday(&amp;now);
 timeout.tv_sec = now.tv_sec + 5;
 timeout.tv_nsec = now.tv_usec * 1000;
 retcode = 0;
 while (x &lt;= y &amp;&amp; retcode != ETIMEDOUT) {
         retcode = pthread_cond_timedwait(&amp;cond, &amp;mut, &amp;timeout);
 }
 if (retcode == ETIMEDOUT) {
         /* timeout occurred */
 } else {
         /* operate on x and y */
 }
 pthread_mutex_unlock(&amp;mut);</PRE>
 <HR>
 <BLOCKQUOTE STYLE="margin-left: 0cm; margin-right: 0cm"><A NAME="toc"></A>
 <B>Table of Contents</B></BLOCKQUOTE>
 <UL>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
 		</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
 		</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
 		</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
 		</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal
 	Safety</A>
 	</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return
 	Value</A>
 	</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A>
 		</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A>
 		</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">See
 	Also</A>
 	</BLOCKQUOTE>
 	<LI><BLOCKQUOTE STYLE="margin-right: 0cm"><A HREF="#sect9" NAME="toc9">Example</A>
 		</BLOCKQUOTE>
 </UL>
 </BODY>
 </HTML>
	<!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_COND(3) manual page</TITLE>
	<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
	<META NAME="CREATED" CONTENT="20050504;16454400">
	<META NAME="CHANGED" CONTENT="20050505;19004700">
	<!-- 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_cond_init, pthread_cond_destroy, pthread_cond_signal,
	pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait -
	operations on conditions
	</P>
	<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
	<P><B>#include <pthread.h></B>
	</P>
	<P><B>pthread_cond_t </B><I>cond</I> <B>= PTHREAD_COND_INITIALIZER;</B>
	</P>
	<P><B>int pthread_cond_init(pthread_cond_t *</B><I>cond</I><B>,
	pthread_condattr_t *</B><I>cond_attr</I><B>);</B>
	</P>
	<P><B>int pthread_cond_signal(pthread_cond_t *</B><I>cond</I><B>);</B>
	</P>
	<P><B>int pthread_cond_broadcast(pthread_cond_t *</B><I>cond</I><B>);</B>
	</P>
	<P><B>int pthread_cond_wait(pthread_cond_t *</B><I>cond</I><B>,
	pthread_mutex_t *</B><I>mutex</I><B>);</B>
	</P>
	<P><B>int pthread_cond_timedwait(pthread_cond_t *</B><I>cond</I><B>,
	pthread_mutex_t *</B><I>mutex</I><B>, const struct timespec
	*</B><I>abstime</I><B>);</B>
	</P>
	<P><B>int pthread_cond_destroy(pthread_cond_t *</B><I>cond</I><B>);</B>
	</P>
	<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
	<P>A condition (short for ‘‘condition variable’’) is a
	synchronization device that allows threads to suspend execution and
	relinquish the processors until some predicate on shared data is
	satisfied. The basic operations on conditions are: signal the
	condition (when the predicate becomes true), and wait for the
	condition, suspending the thread execution until another thread
	signals the condition.
	</P>
	<P>A condition variable must always be associated with a mutex, to
	avoid the race condition where a thread prepares to wait on a
	condition variable and another thread signals the condition just
	before the first thread actually waits on it.
	</P>
	<P><B>pthread_cond_init</B> initializes the condition variable <I>cond</I>,
	using the condition attributes specified in <I>cond_attr</I>, or
	default attributes if <I>cond_attr</I> is <B>NULL</B>.
	</P>
	<P>Variables of type <B>pthread_cond_t</B> can also be initialized
	statically, using the constant <B>PTHREAD_COND_INITIALIZER</B>. In
	the <B>Pthreads-w32</B> implementation, an application should still
	call <B>pthread_cond_destroy</B> at some point to ensure that any
	resources consumed by the condition variable are released.</P>
	<P><B>pthread_cond_signal</B> restarts one of the threads that are
	waiting on the condition variable <I>cond</I>. If no threads are
	waiting on <I>cond</I>, nothing happens. If several threads are
	waiting on <I>cond</I>, exactly one is restarted, but it is not
	specified which.
	</P>
	<P><B>pthread_cond_broadcast</B> restarts all the threads that are
	waiting on the condition variable <I>cond</I>. Nothing happens if no
	threads are waiting on <I>cond</I>.
	</P>
	<P><B>pthread_cond_wait</B> atomically unlocks the <I>mutex</I> (as
	per <B>pthread_unlock_mutex</B>) and waits for the condition variable
	<I>cond</I> to be signalled. The thread execution is suspended and
	does not consume any CPU time until the condition variable is
	signalled. The <I>mutex</I> must be locked by the calling thread on
	entrance to <B>pthread_cond_wait</B>. Before returning to the calling
	thread, <B>pthread_cond_wait</B> re-acquires <I>mutex</I> (as per
	<B>pthread_lock_mutex</B>).
	</P>
	<P>Unlocking the mutex and suspending on the condition variable is
	done atomically. Thus, if all threads always acquire the mutex before
	signalling the condition, this guarantees that the condition cannot
	be signalled (and thus ignored) between the time a thread locks the
	mutex and the time it waits on the condition variable.
	</P>
	<P><B>pthread_cond_timedwait</B> atomically unlocks <I>mutex</I> and
	waits on <I>cond</I>, as <B>pthread_cond_wait</B> does, but it also
	bounds the duration of the wait. If <I>cond</I> has not been
	signalled within the amount of time specified by <I>abstime</I>, the
	mutex <I>mutex</I> is re-acquired and <B>pthread_cond_timedwait</B>
	returns the error <B>ETIMEDOUT</B>. The <I>abstime</I> parameter
	specifies an absolute time, with the same origin as <A HREF="time.html"><B>time</B>(2)</A>
	and <A HREF="gettimeofday.html"><B>gettimeofday</B>(2)</A>.
	</P>
	<P><B>pthread_cond_destroy</B> destroys a condition variable, freeing
	the resources it might hold. No threads must be waiting on the
	condition variable on entrance to <B>pthread_cond_destroy</B>.</P>
	<H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
	<P><B>pthread_cond_wait</B> and <B>pthread_cond_timedwait</B> are
	cancellation points. If a thread is cancelled while suspended in one
	of these functions, the thread immediately resumes execution, then
	locks again the <I>mutex</I> argument to <B>pthread_cond_wait</B> and
	<B>pthread_cond_timedwait</B>, and finally executes the cancellation.
	Consequently, cleanup handlers are assured that <I>mutex</I> is
	locked when they are called.
	</P>
	<H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2>
	<P>The condition functions are not async-signal safe, and should not
	be called from a signal handler. In particular, calling
	<B>pthread_cond_signal</B> or <B>pthread_cond_broadcast</B> from a
	signal handler may deadlock the calling thread.
	</P>
	<H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2>
	<P>All condition variable functions return 0 on success and a
	non-zero error code on error.
	</P>
	<H2><A HREF="#toc6" NAME="sect6">Errors</A></H2>
	<P><B>pthread_cond_init</B>, <B>pthread_cond_signal</B>,
	<B>pthread_cond_broadcast</B>, and <B>pthread_cond_wait</B> never
	return an error code.
	</P>
	<P>The <B>pthread_cond_init</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">
	The <I>cond</I> argument is invalid.
	</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
	<B>ENOMEM</B>
	</DT></DL>
	</DL>
	<BLOCKQUOTE STYLE="margin-left: 4cm">
	There was not enough memory to allocate the condition variable.
	</BLOCKQUOTE>
	<P>The <B>pthread_cond_signal</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">
	The <I>cond</I> argument is invalid.
	</DD></DL>
	</DL>
	<P>
	The <B>pthread_cond_broadcast</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">
	The <I>cond</I> argument is invalid.
	</DD></DL>
	</DL>
	<P>
	The <B>pthread_cond_wait</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">
	The <I>cond</I> argument is invalid.
	</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
	<B>ENOMEM</B>
	</DT></DL>
	</DL>
	<BLOCKQUOTE STYLE="margin-left: 4cm">
	There was not enough memory to allocate the statically initialised
	condition variable. Statically initialised condition variables are
	dynamically allocated by the first thread to wait on them.</BLOCKQUOTE>
	<P>The <B>pthread_cond_timedwait</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></DL>
	</DL>
	<P STYLE="margin-left: 2cm">
	The <I>cond</I> argument is invalid.
	</P>
	<DL>
	<DL>
	<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B>
	</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
	The condition variable was not signalled before the timeout
	specified by <I>abstime</I>
	</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
	<B>ENOMEM</B>
	</DT></DL>
	</DL>
	<BLOCKQUOTE STYLE="margin-left: 4cm">
	There was not enough memory to allocate the statically initialised
	condition variable. Statically initialised condition variables are
	dynamically allocated by the first thread to wait on them.
	</BLOCKQUOTE>
	<P>The <B>pthread_cond_destroy</B> function returns the following
	error code on error:
	</P>
	<DL>
	<DL>
	<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
	</DT></DL>
	</DL>
	<P STYLE="margin-left: 2cm; margin-right: 1cm">
	The <I>cond</I> argument is invalid.
	</P>
	<DL>
	<DL>
	<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B>
	</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
	Some threads are currently waiting on <I>cond</I>.
	</DD></DL>
	</DL>
	<H2>
	<A HREF="#toc7" NAME="sect7">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="#toc8" NAME="sect8">See Also</A></H2>
	<P><A HREF="pthread_condattr_init.html"><B>pthread_condattr_init</B>(3)</A>
	, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
	, <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
	, <A HREF="pthread_cancel.html"><B>pthread_cancel(3)</B></A>.
	</P>
	<H2><A HREF="#toc9" NAME="sect9">Example</A></H2>
	<P>Consider two shared variables <I>x</I> and <I>y</I>, protected by
	the mutex <I>mut</I>, and a condition variable <I>cond</I> that is to
	be signaled whenever <I>x</I> becomes greater than <I>y</I>.
	</P>
	<PRE STYLE="margin-left: 1cm; margin-right: 1cm">int x,y;
	pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
	pthread_cond_t cond = PTHREAD_COND_INITIALIZER;</PRE><BLOCKQUOTE>
	Waiting until <I>x</I> is greater than <I>y</I> is performed as
	follows:
	</BLOCKQUOTE>
	<PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&mut);
	while (x <= y) {
	pthread_cond_wait(&cond, &mut);
	}
	/* operate on x and y */
	pthread_mutex_unlock(&mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
	Modifications on <I>x</I> and <I>y</I> that may cause <I>x</I> to
	become greater than <I>y</I> should signal the condition if needed:
	</BLOCKQUOTE>
	<PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&mut);
	/* modify x and y */
	if (x > y) pthread_cond_broadcast(&cond);
	pthread_mutex_unlock(&mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
	If it can be proved that at most one waiting thread needs to be waken
	up (for instance, if there are only two threads communicating through
	<I>x</I> and <I>y</I>), <B>pthread_cond_signal</B> can be used as a
	slightly more efficient alternative to <B>pthread_cond_broadcast</B>.
	If in doubt, use <B>pthread_cond_broadcast</B>.
	</BLOCKQUOTE>
	<BLOCKQUOTE STYLE="margin-left: 3.01cm">To wait for <I>x</I> to
	become greater than <I>y</I> with a timeout of 5 seconds, do:
	</BLOCKQUOTE>
	<PRE STYLE="margin-left: 1.01cm">struct timeval now;
	struct timespec timeout;
	int retcode;
	pthread_mutex_lock(&mut);
	gettimeofday(&now);
	timeout.tv_sec = now.tv_sec + 5;
	timeout.tv_nsec = now.tv_usec * 1000;
	retcode = 0;
	while (x <= y && retcode != ETIMEDOUT) {
	retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
	}
	if (retcode == ETIMEDOUT) {
	/* timeout occurred */
	} else {
	/* operate on x and y */
	}
	pthread_mutex_unlock(&mut);</PRE>
	<HR>
	<BLOCKQUOTE STYLE="margin-left: 0cm; margin-right: 0cm"><A NAME="toc"></A>
	<B>Table of Contents</B></BLOCKQUOTE>
	<UL>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal
	Safety</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return
	Value</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">See
	Also</A>
	</BLOCKQUOTE>
	<LI><BLOCKQUOTE STYLE="margin-right: 0cm"><A HREF="#sect9" NAME="toc9">Example</A>
	</BLOCKQUOTE>
	</UL>
	</BODY>
	</HTML>