1pthread_cond_wait(3C)    Standard C Library Functions    pthread_cond_wait(3C)
2
3
4

NAME

6       pthread_cond_wait, pthread_cond_timedwait, pthread_cond_reltimedwait_np
7       - wait on a condition
8

SYNOPSIS

10       cc -mt [ flag... ] file... -lpthread [ library... ]
11       #include <pthread.h>
12
13       int pthread_cond_wait(pthread_cond_t *restrict cond,
14            pthread_mutex_t *restrict mutex);
15
16
17       int pthread_cond_timedwait(pthread_cond_t *restrict cond,
18            pthread_mutex_t *restrict mutex,
19            const struct timespec *restrict abstime);
20
21
22       int pthread_cond_reltimedwait_np(pthread_cond_t *cond,
23            pthread_mutex_t *mutex, const struct timespec *reltime);
24
25

DESCRIPTION

27       The      pthread_cond_wait(),       pthread_cond_timedwait(),       and
28       pthread_cond_reltimedwait_np()  functions are used to block on a condi‐
29       tion variable. They are called with mutex locked by the calling  thread
30       or undefined behavior will result.
31
32
33       These  functions  atomically release mutex and cause the calling thread
34       to block on the condition variable cond. Atomically here means ``atomi‐
35       cally  with  respect to access by another  thread to the mutex and then
36       the condition variable." That is, if another thread is able to  acquire
37       the  mutex after the about-to-block thread has released it, then a sub‐
38       sequent call to pthread_cond_signal()  or  pthread_cond_broadcast()  in
39       that  thread  behaves  as  if  it  were issued after the about-to-block
40       thread has blocked.
41
42
43       Upon successful return, the mutex has been locked and is owned  by  the
44       calling  thread.  If  mutex is a robust mutex where an owner terminated
45       while holding the lock and the  state  is  recoverable,  the  mutex  is
46       acquired even though the function returns an error value.
47
48
49       When  using condition variables there is always a boolean predicate, an
50       invariant, associated with each condition wait that must be true before
51       the    thread    should    proceed.    Spurious    wakeups   from   the
52       pthread_cond_wait(),  pthread_cond_timedwait(),  or   pthread_cond_rel‐
53       timedwait_np()   functions   could   occur.   Since   the  return  from
54       pthread_cond_wait(),  pthread_cond_timedwait(),  or   pthread_cond_rel‐
55       timedwait_np()  does  not imply anything about the value of this predi‐
56       cate, the predicate should always be reevaluated.
57
58
59       The order in which blocked threads are  awakened  by  pthread_cond_sig‐
60       nal()  or pthread_cond_broadcast() is determined by the scheduling pol‐
61       icy. See pthreads(5).
62
63
64       The  effect   of   using   more   than   one   mutex   for   concurrent
65       pthread_cond_wait(),   pthread_cond_timedwait(),  or  pthread_cond_rel‐
66       timedwait_np() operations on the same condition variable will result in
67       undefined behavior.
68
69
70       A  condition  wait (whether timed or not) is a cancellation point. When
71       the cancelability enable state of  a  thread  is  set  to  PTHREAD_CAN‐
72       CEL_DEFERRED, a side effect of acting upon a cancellation request while
73       in a condition wait is that the mutex is reacquired before calling  the
74       first cancellation cleanup handler.
75
76
77       A  thread  that  has  been unblocked because it has been canceled while
78       blocked in a call to  pthread_cond_wait()  or  pthread_cond_timedwait()
79       does not consume any condition signal that may be directed concurrently
80       at the condition variable if there are other  threads  blocked  on  the
81       condition variable.
82
83
84       The     pthread_cond_timedwait()    function    is    the    same    as
85       pthread_cond_wait() except that an error is returned  if  the  absolute
86       time  specified  by  abstime  passes  (that  is,  system time equals or
87       exceeds abstime) before the condition cond is signaled or broadcast, or
88       if  the  absolute  time specified by abstime has already been passed at
89       the time of the call. The abstime argument is of type struct  timespec,
90       defined     in    time.h(3HEAD).    When    such    time-outs    occur,
91       pthread_cond_timedwait() will nonetheless  release  and  reacquire  the
92       mutex  referenced  by  mutex.  The function pthread_cond_timedwait() is
93       also a cancellation point.
94
95
96       The pthread_cond_reltimedwait_np() function is a non-standard extension
97       provided  by  the  Solaris version of POSIX threads as indicated by the
98       ``_np'' (non-portable) suffix. The pthread_cond_reltimedwait_np() func‐
99       tion  is  the  same as pthread_cond_timedwait() except that the reltime
100       argument specifies a non-negative time relative to the  current  system
101       time  rather  than  an  absolute  time. The reltime argument is of type
102       struct timespec, defined in time.h(3HEAD). An error value  is  returned
103       if the relative time passes (that is, system time equals or exceeds the
104       starting system time plus the relative time) before the condition  cond
105       is  signaled or broadcast.  When such timeouts occur, pthread_cond_rel‐
106       timedwait_np() releases and reacquires the mutex referenced  by  mutex.
107       The  pthread_cond_reltimedwait_np()  function  is  also  a cancellation
108       point.
109
110
111       If a signal is delivered to a thread waiting for a condition  variable,
112       upon  return from the signal handler the thread resumes waiting for the
113       condition variable as if it was not interrupted, or it returns 0 due to
114       spurious wakeup.
115

RETURN VALUES

117       Except in the case of ETIMEDOUT, EOWNERDEAD, or ENOTRECOVERABLE, all of
118       these error checks act as if they were  performed  immediately  at  the
119       beginning  of processing for the function and cause an error return, in
120       effect, prior to modifying the state of the mutex specified by mutex or
121       the condition variable specified by cond.
122
123
124       Upon successful completion, 0 is returned. Otherwise, an error value is
125       returned to indicate the error.
126

ERRORS

128       These functions will fail if:
129
130       EPERM    The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex  is  a
131                robust mutex, and the current thread does not own the mutex.
132
133
134
135       The  pthread_cond_timedwait() function will fail if:
136
137       ETIMEDOUT    The    absolute    time    specified    by    abstime   to
138                    pthread_cond_timedwait() has passed.
139
140
141
142       The pthread_cond_reltimedwait_np() function will fail if:
143
144       EINVAL       The value specified by reltime is invalid.
145
146
147       ETIMEDOUT    The   relative    time    specified    by    reltime    to
148                    pthread_cond_reltimedwait_np() has passed.
149
150
151
152       These functions may fail if:
153
154       EINVAL    The  value  specified  by cond, mutex, abstime, or reltime is
155                 invalid.
156
157
158       EINVAL    Different mutexes were supplied for concurrent operations  on
159                 the same condition variable.
160
161
162
163       If the mutex specified by mutex is a robust mutex (initialized with the
164       robustness attribute  PTHREAD_MUTEX_ROBUST),  the  pthread_cond_wait(),
165       pthread_cond_timedwait(),  and pthread_cond_reltimedwait_np() functions
166       will, under the specified conditions, return the following  error  val‐
167       ues.   For  complete  information,  see  the pthread_mutex_lock(3C) and
168       pthread_mutexattr_setrobust(3C) manual pages.
169
170       EOWNERDEAD         The last owner of this mutex died while holding  the
171                          mutex,  leaving the state it was protecting possibly
172                          inconsistent. The mutex is now owned by the caller.
173
174
175       ENOTRECOVERABLE    The mutex was protecting state  that  has  now  been
176                          left irrecoverable. The mutex has not been acquired.
177
178

ATTRIBUTES

180       See attributes(5) for descriptions of the following attributes:
181
182
183
184
185       ┌─────────────────────────────┬─────────────────────────────┐
186       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
187       ├─────────────────────────────┼─────────────────────────────┤
188       │Interface Stability          │Standard                     │
189       ├─────────────────────────────┼─────────────────────────────┤
190       │MT-Level                     │MT-Safe                      │
191       └─────────────────────────────┴─────────────────────────────┘
192

SEE ALSO

194       pthread_cond_signal(3C),                    pthread_cond_broadcast(3C),
195       pthread_mutex_lock(3C), pthread_mutexattr_getrobust(3C), time.h(3HEAD),
196       attributes(5), condition(5), pthreads(5), standards(5)
197
198
199
200SunOS 5.11                        11 Nov 2008            pthread_cond_wait(3C)
Impressum