Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/cond_init.3c
+++ new/usr/src/man/man3c/cond_init.3c
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
|
↓ open down ↓ |
36 lines elided |
↑ open up ↑ |
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
44 44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
46 46 .\"
47 -.TH COND_INIT 3C "Jun 5, 2007"
47 +.TH COND_INIT 3C "February 15, 2020"
48 48 .SH NAME
49 49 cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal,
50 50 cond_broadcast, cond_destroy \- condition variables
51 51 .SH SYNOPSIS
52 -.LP
53 52 .nf
54 53 cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
55 54 #include <thread.h>
56 55 #include <synch.h>
57 56
58 57 \fBint\fR \fBcond_init\fR(\fBcond_t *\fR\fIcvp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
59 58 .fi
60 59
61 60 .LP
62 61 .nf
63 62 \fBint\fR \fBcond_wait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR);
64 63 .fi
65 64
66 65 .LP
67 66 .nf
68 67 \fBint\fR \fBcond_timedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR,
69 68 \fBtimestruc_t *\fR\fIabstime\fR);
70 69 .fi
71 70
72 71 .LP
73 72 .nf
74 73 \fBint\fR \fBcond_reltimedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR,
75 74 \fBtimestruc_t *\fR\fIreltime\fR);
76 75 .fi
77 76
78 77 .LP
79 78 .nf
80 79 \fBint\fR \fBcond_signal\fR(\fBcond_t *\fR\fIcvp\fR);
81 80 .fi
82 81
83 82 .LP
84 83 .nf
|
↓ open down ↓ |
22 lines elided |
↑ open up ↑ |
85 84 \fBint\fR \fBcond_broadcast\fR(\fBcond_t *\fR\fIcvp\fR);
86 85 .fi
87 86
88 87 .LP
89 88 .nf
90 89 \fBint\fR \fBcond_destroy\fR(\fBcond_t *\fR\fIcvp\fR);
91 90 .fi
92 91
93 92 .SH DESCRIPTION
94 93 .SS "Initialize"
95 -.sp
96 -.LP
97 94 Condition variables and mutexes should be global. Condition variables that are
98 95 allocated in writable memory can synchronize threads among processes if they
99 96 are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized
100 97 for this purpose.
101 98 .sp
102 99 .LP
103 100 The scope of a condition variable is either intra-process or inter-process.
104 101 This is dependent upon whether the argument is passed implicitly or explicitly
105 102 to the initialization of that condition variable. A condition variable does not
106 103 need to be explicitly initialized. A condition variable is initialized with all
107 104 zeros, by default, and its scope is set to within the calling process. For
108 105 inter-process synchronization, a condition variable must be initialized once,
109 106 and only once, before use.
110 107 .sp
111 108 .LP
|
↓ open down ↓ |
5 lines elided |
↑ open up ↑ |
112 109 A condition variable must not be simultaneously initialized by multiple threads
113 110 or re-initialized while in use by other threads.
114 111 .sp
115 112 .LP
116 113 Attributes of condition variables can be set to the default or customized at
117 114 initialization.
118 115 .sp
119 116 .LP
120 117 The \fBcond_init()\fR function initializes the condition variable pointed to by
121 118 \fIcvp\fR. A condition variable can have several different types of behavior,
122 -specified by \fItype\fR. No current type uses \fIarg\fR although a future type
119 +specified by \fItype\fR. No current type uses \fIarg\fR although a future type
123 120 may specify additional behavior parameters with \fIarg\fR. The \fItype\fR
124 121 argument c take one of the following values:
125 122 .sp
126 123 .ne 2
127 124 .na
128 125 \fB\fBUSYNC_THREAD\fR\fR
129 126 .ad
130 127 .RS 17n
131 -The condition variable can synchronize threads only in this process. This is
128 +The condition variable can synchronize threads only in this process. This is
132 129 the default.
133 130 .RE
134 131
135 132 .sp
136 133 .ne 2
137 134 .na
138 135 \fB\fBUSYNC_PROCESS\fR\fR
139 136 .ad
140 137 .RS 17n
141 138 The condition variable can synchronize threads in this process and other
142 139 processes. Only one process should initialize the condition variable. The
143 140 object initialized with this attribute must be allocated in memory shared
144 141 between processes, either in System V shared memory (see \fBshmop\fR(2)) or in
145 142 memory mapped to a file (see \fBmmap\fR(2)). It is illegal to initialize the
146 143 object this way and to not allocate it in such shared memory.
147 144 .RE
148 145
149 146 .sp
150 147 .LP
151 148 Initializing condition variables can also be accomplished by allocating in
152 149 zeroed memory, in which case, a \fItype\fR of \fBUSYNC_THREAD\fR is assumed.
153 150 .sp
154 151 .LP
155 152 If default condition variable attributes are used, statically allocated
156 153 condition variables can be initialized by the macro \fBDEFAULTCV\fR.
157 154 .sp
158 155 .LP
159 156 Default condition variable initialization (intra-process):
160 157 .sp
161 158 .in +2
162 159 .nf
163 160 cond_t cvp;
164 161
165 162 cond_init(&cvp, NULL, NULL); /*initialize condition variable
166 163 with default*/
167 164 .fi
168 165 .in -2
169 166
170 167 .sp
171 168 .LP
172 169 or
173 170 .sp
174 171 .in +2
175 172 .nf
176 173 cond_init(&cvp, USYNC_THREAD, NULL);
177 174 .fi
178 175 .in -2
179 176
180 177 .sp
181 178 .LP
182 179 or
183 180 .sp
184 181 .in +2
185 182 .nf
186 183 cond_t cond = DEFAULTCV;
187 184 .fi
188 185 .in -2
189 186
190 187 .sp
191 188 .LP
|
↓ open down ↓ |
50 lines elided |
↑ open up ↑ |
192 189 Customized condition variable initialization (inter-process):
193 190 .sp
194 191 .in +2
195 192 .nf
196 193 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
197 194 inter-process scope */
198 195 .fi
199 196 .in -2
200 197
201 198 .SS "Condition Wait"
202 -.sp
203 -.LP
204 199 The condition wait interface allows a thread to wait for a condition and
205 200 atomically release the associated mutex that it needs to hold to check the
206 201 condition. The thread waits for another thread to make the condition true and
207 202 that thread's resulting call to signal and wakeup the waiting thread.
208 203 .sp
209 204 .LP
210 205 The \fBcond_wait()\fR function atomically releases the mutex pointed to by
211 206 \fImp\fR and causes the calling thread to block on the condition variable
212 207 pointed to by \fIcvp\fR. The blocked thread may be awakened by
213 208 \fBcond_signal()\fR, \fBcond_broadcast()\fR, or when interrupted by delivery of
214 -a \fBUNIX\fR signal or a \fBfork()\fR.
209 +a \fBUNIX\fR signal or a \fBfork()\fR.
215 210 .sp
216 211 .LP
217 212 The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
218 213 functions always return with the mutex locked and owned by the calling thread
219 214 even when returning an error, except when the mutex has the \fBLOCK_ROBUST\fR
220 215 attribute and has been left irrecoverable by the mutex's last owner. The
221 216 \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
222 217 functions return the appropriate error value if they fail to internally
223 218 reacquire the mutex.
224 219 .SS "Condition Signaling"
225 -.sp
226 -.LP
227 220 A condition signal allows a thread to unblock a single thread waiting on the
228 221 condition variable, whereas a condition broadcast allows a thread to unblock
229 222 all threads waiting on the condition variable.
230 223 .sp
231 224 .LP
232 225 The \fBcond_signal()\fR function unblocks one thread that is blocked on the
233 226 condition variable pointed to by \fIcvp\fR.
234 227 .sp
235 228 .LP
236 229 The \fBcond_broadcast()\fR function unblocks all threads that are blocked on
237 230 the condition variable pointed to by \fIcvp\fR.
238 231 .sp
239 232 .LP
240 233 If no threads are blocked on the condition variable, then \fBcond_signal()\fR
|
↓ open down ↓ |
4 lines elided |
↑ open up ↑ |
241 234 and \fBcond_broadcast()\fR have no effect.
242 235 .sp
243 236 .LP
244 237 The \fBcond_signal()\fR or \fBcond_broadcast()\fR functions can be called by a
245 238 thread whether or not it currently owns the mutex that threads calling
246 239 \fBcond_wait()\fR, \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR have
247 240 associated with the condition variable during their waits. If, however,
248 241 predictable scheduling behavior is required, then that mutex should be locked
249 242 by the thread prior to calling \fBcond_signal()\fR or \fBcond_broadcast()\fR.
250 243 .SS "Destroy"
251 -.sp
252 -.LP
253 244 The condition destroy functions destroy any state, but not the space,
254 245 associated with the condition variable.
255 246 .sp
256 247 .LP
257 248 The \fBcond_destroy()\fR function destroys any state associated with the
258 249 condition variable pointed to by \fIcvp\fR. The space for storing the condition
259 250 variable is not freed.
260 251 .SH RETURN VALUES
261 -.sp
262 -.LP
263 252 Upon successful completion, these functions return \fB0\fR. Otherwise, a
264 253 non-zero value is returned to indicate the error.
265 254 .SH ERRORS
266 -.sp
267 -.LP
268 255 The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions will fail
269 256 if:
270 257 .sp
271 258 .ne 2
272 259 .na
273 260 \fB\fBETIME\fR\fR
274 261 .ad
275 262 .RS 9n
276 263 The time specified by \fIabstime\fR or \fIreltime\fR has passed.
277 264 .RE
278 265
279 266 .sp
280 267 .LP
281 268 The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
282 269 functions will fail if:
283 270 .sp
284 271 .ne 2
285 272 .na
286 273 \fB\fBEINTR\fR\fR
287 274 .ad
288 275 .RS 9n
289 276 Interrupted. The calling thread was awakened by the delivery of a UNIX signal.
290 277 .RE
291 278
292 279 .sp
293 280 .LP
294 281 If the mutex pointed to by \fImp\fR is a robust mutex (initialized with the
295 282 \fBLOCK_ROBUST\fR attribute), the \fBcond_wait()\fR, \fBcond_timedwait()\fR and
296 283 \fBcond_reltimedwait()\fR functions will, under the specified conditions,
297 284 return the following error values. For complete information, see the
298 285 description of the \fBmutex_lock()\fR function on the \fBmutex_init\fR(3C)
299 286 manual page.
300 287 .sp
301 288 .ne 2
302 289 .na
303 290 \fB\fBENOTRECOVERABLE\fR\fR
304 291 .ad
305 292 .RS 19n
|
↓ open down ↓ |
28 lines elided |
↑ open up ↑ |
306 293 The mutex was protecting the state that has now been left irrecoverable. The
307 294 mutex has not been acquired.
308 295 .RE
309 296
310 297 .sp
311 298 .ne 2
312 299 .na
313 300 \fB\fBEOWNERDEAD\fR\fR
314 301 .ad
315 302 .RS 19n
316 -The last owner of the mutex died while holding the mutex, possibly leaving the
303 +The last owner of the mutex died while holding the mutex, possibly leaving the
317 304 state it was protecting inconsistent. The mutex is now owned by the caller.
318 305 .RE
319 306
320 307 .sp
321 308 .LP
322 309 These functions may fail if:
323 310 .sp
324 311 .ne 2
325 312 .na
326 313 \fB\fBEFAULT\fR\fR
327 314 .ad
328 315 .RS 10n
329 316 The \fIcond\fR, \fIattr\fR, \fIcvp\fR, \fIarg\fR, \fIabstime\fR, or \fImutex\fR
330 317 argument points to an illegal address.
331 318 .RE
332 319
333 320 .sp
334 321 .ne 2
|
↓ open down ↓ |
8 lines elided |
↑ open up ↑ |
335 322 .na
336 323 \fB\fBEINVAL\fR\fR
337 324 .ad
338 325 .RS 10n
339 326 Invalid argument. For \fBcond_init()\fR, \fItype\fR is not a recognized type.
340 327 For \fBcond_timedwait()\fR, the number of nanoseconds is greater than or equal
341 328 to 1,000,000,000.
342 329 .RE
343 330
344 331 .SH EXAMPLES
345 -.LP
346 332 \fBExample 1 \fRUse \fBcond_wait()\fR in a loop to test some condition.
347 333 .sp
348 334 .LP
349 -The \fBcond_wait()\fR functin is normally used in a loop testing some
335 +The \fBcond_wait()\fR function is normally used in a loop testing some
350 336 condition, as follows:
351 337
352 338 .sp
353 339 .in +2
354 340 .nf
355 341 (void) mutex_lock(mp);
356 342 while (cond == FALSE) {
357 343 (void) cond_wait(cvp, mp);
358 344 }
359 345 (void) mutex_unlock(mp);
360 346 .fi
361 347 .in -2
362 348
363 349 .LP
364 350 \fBExample 2 \fRUse \fBcond_timedwait()\fR in a loop to test some condition.
365 351 .sp
366 352 .LP
367 353 The \fBcond_timedwait()\fR function is normally used in a loop testing some
368 354 condition. It uses an absolute timeout value as follows:
369 355
370 356 .sp
371 357 .in +2
372 358 .nf
373 359 timestruc_t to;
374 360 \&...
375 361 (void) mutex_lock(mp);
376 362 to.tv_sec = time(NULL) + TIMEOUT;
377 363 to.tv_nsec = 0;
378 364 while (cond == FALSE) {
379 365 err = cond_timedwait(cvp, mp, &to);
380 366 if (err == ETIME) {
381 367 /* timeout, do something */
382 368 break;
383 369 }
384 370 }
385 371 (void) mutex_unlock(mp);
386 372 .fi
387 373 .in -2
388 374
389 375 .LP
390 376 \fBExample 3 \fRUse \fBcond_reltimedwait()\fR in a loop to test some condition.
391 377 .sp
392 378 .LP
393 379 The \fBcond_reltimedwait()\fR function is normally used in a loop testing in
394 380 some condition. It uses a relative timeout value as follows:
395 381
396 382 .sp
397 383 .in +2
398 384 .nf
399 385 timestruc_t to;
400 386 \&...
401 387 (void) mutex_lock(mp);
402 388 while (cond == FALSE) {
403 389 to.tv_sec = TIMEOUT;
404 390 to.tv_nsec = 0;
405 391 err = cond_reltimedwait(cvp, mp, &to);
|
↓ open down ↓ |
46 lines elided |
↑ open up ↑ |
406 392 if (err == ETIME) {
407 393 /* timeout, do something */
408 394 break;
409 395 }
410 396 }
411 397 (void) mutex_unlock(mp);
412 398 .fi
413 399 .in -2
414 400
415 401 .SH ATTRIBUTES
416 -.sp
417 -.LP
418 402 See \fBattributes\fR(5) for descriptions of the following attributes:
419 403 .sp
420 404
421 405 .sp
422 406 .TS
423 407 box;
424 408 c | c
425 409 l | l .
426 410 ATTRIBUTE TYPE ATTRIBUTE VALUE
427 411 _
428 412 MT-Level MT-Safe
429 413 .TE
430 414
431 415 .SH SEE ALSO
432 -.sp
433 -.LP
434 416 \fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2),
435 417 \fBmutex_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5),
436 418 \fBcondition\fR(5), \fBmutex\fR(5), \fBstandards\fR(5)
437 419 .SH NOTES
438 -.sp
439 -.LP
440 420 If more than one thread is blocked on a condition variable, the order in which
441 421 threads are unblocked is determined by the scheduling policy. When each thread,
442 422 unblocked as a result of a \fBcond_signal()\fR or \fBcond_broadcast()\fR,
443 423 returns from its call to \fBcond_wait()\fR or \fBcond_timedwait()\fR , the
444 424 thread owns the mutex with which it called \fBcond_wait()\fR,
445 425 \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR. The thread(s) that are
446 426 unblocked compete for the mutex according to the scheduling policy and as if
447 427 each had called \fBmutex_lock\fR(3C).
448 428 .sp
449 429 .LP
450 430 When \fBcond_wait()\fR returns the value of the condition is indeterminate and
451 431 must be reevaluated.
452 432 .sp
453 433 .LP
454 434 The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions are similar
455 435 to \fBcond_wait()\fR, except that the calling thread will not wait for the
456 436 condition to become true past the absolute time specified by \fIabstime\fR or
457 437 the relative time specified by \fIreltime\fR. Note that \fBcond_timedwait()\fR
458 438 or \fBcond_reltimedwait()\fR might continue to block as it trys to reacquire
459 439 the mutex pointed to by \fImp\fR, which may be locked by another thread. If
460 440 either \fBcond_timedwait()\fR or \fBcond_reltimedwait()\fR returns because of a
461 441 timeout, it returns the error value \fBETIME\fR.
|
↓ open down ↓ |
12 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX