[ae68ff0] | 1 | @c |
---|
[1e524995] | 2 | @c COPYRIGHT (c) 1988-1998. |
---|
[ae68ff0] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[139b2e4a] | 6 | @c $Id$ |
---|
| 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @chapter Mutex Manager |
---|
[c4dddee] | 10 | |
---|
[ae68ff0] | 11 | @section Introduction |
---|
| 12 | |
---|
| 13 | The mutex manager ... |
---|
| 14 | |
---|
| 15 | The directives provided by the mutex manager are: |
---|
| 16 | |
---|
| 17 | @itemize @bullet |
---|
| 18 | @item @code{pthread_mutexattr_init} - |
---|
| 19 | @item @code{pthread_mutexattr_destroy} - |
---|
| 20 | @item @code{pthread_mutexattr_setprotocol} - |
---|
| 21 | @item @code{pthread_mutexattr_getprotocol} - |
---|
| 22 | @item @code{pthread_mutexattr_setprioceiling} - |
---|
| 23 | @item @code{pthread_mutexattr_getprioceiling} - |
---|
| 24 | @item @code{pthread_mutexattr_setpshared} - |
---|
| 25 | @item @code{pthread_mutexattr_getpshared} - |
---|
| 26 | @item @code{pthread_mutex_init} - |
---|
| 27 | @item @code{pthread_mutex_destroy} - |
---|
| 28 | @item @code{pthread_mutex_lock} - |
---|
| 29 | @item @code{pthread_mutex_trylock} - |
---|
| 30 | @item @code{pthread_mutex_timedlock} - |
---|
| 31 | @item @code{pthread_mutex_unlock} - |
---|
| 32 | @item @code{pthread_mutex_setprioceiling} - |
---|
| 33 | @item @code{pthread_mutex_getprioceiling} - |
---|
| 34 | @end itemize |
---|
| 35 | |
---|
| 36 | @section Background |
---|
| 37 | |
---|
[c4dddee] | 38 | There is currently no text in this section. |
---|
| 39 | |
---|
[ae68ff0] | 40 | @section Operations |
---|
| 41 | |
---|
[c4dddee] | 42 | There is currently no text in this section. |
---|
| 43 | |
---|
[ae68ff0] | 44 | @section Directives |
---|
| 45 | |
---|
| 46 | This section details the mutex manager's directives. |
---|
| 47 | A subsection is dedicated to each of this manager's directives |
---|
| 48 | and describes the calling sequence, related constants, usage, |
---|
| 49 | and status codes. |
---|
| 50 | |
---|
| 51 | @page |
---|
| 52 | @subsection pthread_mutexattr_init |
---|
| 53 | |
---|
| 54 | @subheading CALLING SEQUENCE: |
---|
| 55 | |
---|
| 56 | @example |
---|
| 57 | #include <pthread.h> |
---|
| 58 | |
---|
| 59 | int pthread_mutexattr_init( |
---|
| 60 | pthread_mutexattr_t *attr |
---|
| 61 | ); |
---|
| 62 | @end example |
---|
| 63 | |
---|
| 64 | @subheading STATUS CODES: |
---|
| 65 | |
---|
| 66 | @table @b |
---|
| 67 | @item EINVAL |
---|
| 68 | The attribute pointer argument is invalid. |
---|
| 69 | |
---|
| 70 | @end table |
---|
| 71 | |
---|
| 72 | @subheading DESCRIPTION: |
---|
| 73 | |
---|
| 74 | @subheading NOTES: |
---|
| 75 | |
---|
| 76 | @page |
---|
| 77 | @subsection pthread_mutexattr_destroy |
---|
| 78 | |
---|
| 79 | @subheading CALLING SEQUENCE: |
---|
| 80 | |
---|
| 81 | @example |
---|
| 82 | #include <pthread.h> |
---|
| 83 | |
---|
| 84 | int pthread_mutexattr_destroy( |
---|
| 85 | pthread_mutexattr_t *attr |
---|
| 86 | ); |
---|
| 87 | @end example |
---|
| 88 | |
---|
| 89 | @subheading STATUS CODES: |
---|
| 90 | |
---|
| 91 | @table @b |
---|
| 92 | @item EINVAL |
---|
| 93 | The attribute pointer argument is invalid. |
---|
| 94 | |
---|
| 95 | @item EINVAL |
---|
| 96 | The attribute set is not initialized. |
---|
| 97 | |
---|
| 98 | @end table |
---|
| 99 | |
---|
| 100 | @subheading DESCRIPTION: |
---|
| 101 | |
---|
| 102 | @subheading NOTES: |
---|
| 103 | |
---|
| 104 | @page |
---|
| 105 | @subsection pthread_mutexattr_setprotocol |
---|
| 106 | |
---|
| 107 | @subheading CALLING SEQUENCE: |
---|
| 108 | |
---|
| 109 | @example |
---|
| 110 | #include <pthread.h> |
---|
| 111 | |
---|
| 112 | int pthread_mutexattr_setprotocol( |
---|
| 113 | pthread_mutexattr_t *attr, |
---|
| 114 | int protocol |
---|
| 115 | ); |
---|
| 116 | @end example |
---|
| 117 | |
---|
| 118 | @subheading STATUS CODES: |
---|
| 119 | |
---|
| 120 | @table @b |
---|
| 121 | @item EINVAL |
---|
| 122 | The attribute pointer argument is invalid. |
---|
| 123 | |
---|
| 124 | @item EINVAL |
---|
| 125 | The attribute set is not initialized. |
---|
| 126 | |
---|
| 127 | @item EINVAL |
---|
| 128 | The protocol argument is invalid. |
---|
| 129 | |
---|
| 130 | @end table |
---|
| 131 | |
---|
| 132 | @subheading DESCRIPTION: |
---|
| 133 | |
---|
| 134 | @subheading NOTES: |
---|
| 135 | |
---|
| 136 | @page |
---|
| 137 | @subsection pthread_mutexattr_getprotocol |
---|
| 138 | |
---|
| 139 | @subheading CALLING SEQUENCE: |
---|
| 140 | |
---|
| 141 | @example |
---|
| 142 | #include <pthread.h> |
---|
| 143 | |
---|
| 144 | int pthread_mutexattr_getprotocol( |
---|
| 145 | pthread_mutexattr_t *attr, |
---|
| 146 | int *protocol |
---|
| 147 | ); |
---|
| 148 | @end example |
---|
| 149 | |
---|
| 150 | @subheading STATUS CODES: |
---|
| 151 | |
---|
| 152 | @table @b |
---|
| 153 | @item EINVAL |
---|
| 154 | The attribute pointer argument is invalid. |
---|
| 155 | |
---|
| 156 | @item EINVAL |
---|
| 157 | The attribute set is not initialized. |
---|
| 158 | |
---|
| 159 | @item EINVAL |
---|
| 160 | The protocol pointer argument is invalid. |
---|
| 161 | |
---|
| 162 | @end table |
---|
| 163 | |
---|
| 164 | @subheading DESCRIPTION: |
---|
| 165 | |
---|
| 166 | @subheading NOTES: |
---|
| 167 | |
---|
| 168 | @page |
---|
| 169 | @subsection pthread_mutexattr_setprioceiling |
---|
| 170 | |
---|
| 171 | @subheading CALLING SEQUENCE: |
---|
| 172 | |
---|
| 173 | @example |
---|
| 174 | #include <pthread.h> |
---|
| 175 | |
---|
| 176 | int pthread_mutexattr_setprioceiling( |
---|
| 177 | pthread_mutexattr_t *attr, |
---|
| 178 | int prioceiling |
---|
| 179 | ); |
---|
| 180 | @end example |
---|
| 181 | |
---|
| 182 | @subheading STATUS CODES: |
---|
| 183 | |
---|
| 184 | @table @b |
---|
| 185 | @item EINVAL |
---|
| 186 | The attribute pointer argument is invalid. |
---|
| 187 | |
---|
| 188 | @item EINVAL |
---|
| 189 | The attribute set is not initialized. |
---|
| 190 | |
---|
| 191 | @item EINVAL |
---|
| 192 | The prioceiling argument is invalid. |
---|
| 193 | |
---|
| 194 | @end table |
---|
| 195 | |
---|
| 196 | @subheading DESCRIPTION: |
---|
| 197 | |
---|
| 198 | @subheading NOTES: |
---|
| 199 | |
---|
| 200 | @page |
---|
| 201 | @subsection pthread_mutexattr_getprioceiling |
---|
| 202 | |
---|
| 203 | @subheading CALLING SEQUENCE: |
---|
| 204 | |
---|
| 205 | @example |
---|
| 206 | #include <pthread.h> |
---|
| 207 | |
---|
| 208 | int pthread_mutexattr_getprioceiling( |
---|
| 209 | const pthread_mutexattr_t *attr, |
---|
| 210 | int *prioceiling |
---|
| 211 | ); |
---|
| 212 | @end example |
---|
| 213 | |
---|
| 214 | @subheading STATUS CODES: |
---|
| 215 | |
---|
| 216 | @table @b |
---|
| 217 | @item EINVAL |
---|
| 218 | The attribute pointer argument is invalid. |
---|
| 219 | |
---|
| 220 | @item EINVAL |
---|
| 221 | The attribute set is not initialized. |
---|
| 222 | |
---|
| 223 | @item EINVAL |
---|
| 224 | The prioceiling pointer argument is invalid. |
---|
| 225 | |
---|
| 226 | @end table |
---|
| 227 | |
---|
| 228 | @subheading DESCRIPTION: |
---|
| 229 | |
---|
| 230 | @subheading NOTES: |
---|
| 231 | |
---|
| 232 | @page |
---|
| 233 | @subsection pthread_mutexattr_setpshared |
---|
| 234 | |
---|
| 235 | @subheading CALLING SEQUENCE: |
---|
| 236 | |
---|
| 237 | @example |
---|
| 238 | #include <pthread.h> |
---|
| 239 | |
---|
| 240 | int pthread_mutexattr_setpshared( |
---|
| 241 | pthread_mutexattr_t *attr, |
---|
| 242 | int pshared |
---|
| 243 | ); |
---|
| 244 | @end example |
---|
| 245 | |
---|
| 246 | @subheading STATUS CODES: |
---|
| 247 | |
---|
| 248 | @table @b |
---|
| 249 | @item EINVAL |
---|
| 250 | The attribute pointer argument is invalid. |
---|
| 251 | |
---|
| 252 | @item EINVAL |
---|
| 253 | The attribute set is not initialized. |
---|
| 254 | |
---|
| 255 | @item EINVAL |
---|
| 256 | The pshared argument is invalid. |
---|
| 257 | |
---|
| 258 | @end table |
---|
| 259 | |
---|
| 260 | @subheading DESCRIPTION: |
---|
| 261 | |
---|
| 262 | @subheading NOTES: |
---|
| 263 | |
---|
| 264 | @page |
---|
| 265 | @subsection pthread_mutexattr_getpshared |
---|
| 266 | |
---|
| 267 | @subheading CALLING SEQUENCE: |
---|
| 268 | |
---|
| 269 | @example |
---|
| 270 | #include <pthread.h> |
---|
| 271 | |
---|
| 272 | int pthread_mutexattr_getpshared( |
---|
| 273 | const pthread_mutexattr_t *attr, |
---|
| 274 | int *pshared |
---|
| 275 | ); |
---|
| 276 | @end example |
---|
| 277 | |
---|
| 278 | @subheading STATUS CODES: |
---|
| 279 | |
---|
| 280 | @table @b |
---|
| 281 | @item EINVAL |
---|
| 282 | The attribute pointer argument is invalid. |
---|
| 283 | |
---|
| 284 | @item EINVAL |
---|
| 285 | The attribute set is not initialized. |
---|
| 286 | |
---|
| 287 | @item EINVAL |
---|
| 288 | The pshared pointer argument is invalid. |
---|
| 289 | |
---|
| 290 | @end table |
---|
| 291 | |
---|
| 292 | @subheading DESCRIPTION: |
---|
| 293 | |
---|
| 294 | @subheading NOTES: |
---|
| 295 | |
---|
| 296 | @page |
---|
| 297 | @subsection pthread_mutex_init |
---|
| 298 | |
---|
| 299 | @subheading CALLING SEQUENCE: |
---|
| 300 | |
---|
| 301 | @example |
---|
| 302 | #include <pthread.h> |
---|
| 303 | |
---|
| 304 | int pthread_mutex_init( |
---|
| 305 | pthread_mutex_t *mutex, |
---|
| 306 | const pthread_mutexattr_t *attr |
---|
| 307 | ); |
---|
| 308 | @end example |
---|
| 309 | |
---|
| 310 | @subheading STATUS CODES: |
---|
| 311 | |
---|
| 312 | @table @b |
---|
| 313 | @item EINVAL |
---|
| 314 | The attribute set is not initialized. |
---|
| 315 | |
---|
| 316 | @item EINVAL |
---|
| 317 | The specified protocol is invalid. |
---|
| 318 | |
---|
| 319 | @item EAGAIN |
---|
| 320 | The system lacked the necessary resources to initialize another mutex. |
---|
| 321 | |
---|
| 322 | @item ENOMEM |
---|
| 323 | Insufficient memory exists to initialize the mutex. |
---|
| 324 | |
---|
| 325 | @item EBUSY |
---|
| 326 | Attempted to reinialize the object reference by mutex, a previously |
---|
| 327 | initialized, but not yet destroyed. |
---|
| 328 | |
---|
| 329 | @end table |
---|
| 330 | |
---|
| 331 | @subheading DESCRIPTION: |
---|
| 332 | |
---|
| 333 | @subheading NOTES: |
---|
| 334 | |
---|
| 335 | @page |
---|
| 336 | @subsection pthread_mutex_destroy |
---|
| 337 | |
---|
| 338 | @subheading CALLING SEQUENCE: |
---|
| 339 | |
---|
| 340 | @example |
---|
| 341 | #include <pthread.h> |
---|
| 342 | |
---|
| 343 | int pthread_mutex_destroy( |
---|
| 344 | pthread_mutex_t *mutex |
---|
| 345 | ); |
---|
| 346 | @end example |
---|
| 347 | |
---|
| 348 | @subheading STATUS CODES: |
---|
| 349 | |
---|
| 350 | @table @b |
---|
| 351 | @item EINVAL |
---|
| 352 | The specified mutex is invalid. |
---|
| 353 | |
---|
| 354 | @item EBUSY |
---|
| 355 | Attempted to destroy the object reference by mutex, while it is locked or |
---|
| 356 | referenced by another thread. |
---|
| 357 | |
---|
| 358 | @end table |
---|
| 359 | |
---|
| 360 | @subheading DESCRIPTION: |
---|
| 361 | |
---|
| 362 | @subheading NOTES: |
---|
| 363 | |
---|
| 364 | @page |
---|
| 365 | @subsection pthread_mutex_lock |
---|
| 366 | |
---|
| 367 | @subheading CALLING SEQUENCE: |
---|
| 368 | |
---|
| 369 | @example |
---|
| 370 | #include <pthread.h> |
---|
| 371 | |
---|
| 372 | int pthread_mutex_lock( |
---|
| 373 | pthread_mutex_t *mutex |
---|
| 374 | ); |
---|
| 375 | @end example |
---|
| 376 | |
---|
| 377 | @subheading STATUS CODES: |
---|
| 378 | |
---|
| 379 | @table @b |
---|
| 380 | @item EINVAL |
---|
| 381 | The specified mutex is invalid. |
---|
| 382 | |
---|
| 383 | @item EINVAL |
---|
| 384 | The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the |
---|
| 385 | priority of the calling thread is higher than the current priority |
---|
| 386 | ceiling. |
---|
| 387 | |
---|
| 388 | @item EDEADLK |
---|
| 389 | The current thread already owns the mutex. |
---|
| 390 | |
---|
| 391 | @end table |
---|
| 392 | |
---|
| 393 | @subheading DESCRIPTION: |
---|
| 394 | |
---|
| 395 | @subheading NOTES: |
---|
| 396 | |
---|
| 397 | @page |
---|
| 398 | @subsection pthread_mutex_trylock |
---|
| 399 | |
---|
| 400 | @subheading CALLING SEQUENCE: |
---|
| 401 | |
---|
| 402 | @example |
---|
| 403 | #include <pthread.h> |
---|
| 404 | |
---|
| 405 | int pthread_mutex_trylock( |
---|
| 406 | pthread_mutex_t *mutex |
---|
| 407 | ); |
---|
| 408 | @end example |
---|
| 409 | |
---|
| 410 | @subheading STATUS CODES: |
---|
| 411 | |
---|
| 412 | @table @b |
---|
| 413 | @item EINVAL |
---|
| 414 | The specified mutex is invalid. |
---|
| 415 | |
---|
| 416 | @item EINVAL |
---|
| 417 | The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the |
---|
| 418 | priority of the calling thread is higher than the current priority |
---|
| 419 | ceiling. |
---|
| 420 | |
---|
| 421 | @item EDEADLK |
---|
| 422 | The current thread already owns the mutex. |
---|
| 423 | |
---|
| 424 | @end table |
---|
| 425 | |
---|
| 426 | @subheading DESCRIPTION: |
---|
| 427 | |
---|
| 428 | @subheading NOTES: |
---|
| 429 | |
---|
| 430 | @page |
---|
| 431 | @subsection pthread_mutex_timedlock |
---|
| 432 | |
---|
| 433 | @subheading CALLING SEQUENCE: |
---|
| 434 | |
---|
| 435 | @example |
---|
| 436 | #include <pthread.h> |
---|
| 437 | #include <time.h> |
---|
| 438 | |
---|
| 439 | int pthread_mutex_timedlock( |
---|
| 440 | pthread_mutex_t *mutex, |
---|
| 441 | const struct timespec *timeout |
---|
| 442 | ); |
---|
| 443 | @end example |
---|
| 444 | |
---|
| 445 | @subheading STATUS CODES: |
---|
| 446 | |
---|
| 447 | @table @b |
---|
| 448 | @item EINVAL |
---|
| 449 | The specified mutex is invalid. |
---|
| 450 | |
---|
| 451 | @item EINVAL |
---|
| 452 | The nanoseconds field of timeout is invalid. |
---|
| 453 | |
---|
| 454 | @item EINVAL |
---|
| 455 | The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the |
---|
| 456 | priority of the calling thread is higher than the current priority |
---|
| 457 | ceiling. |
---|
| 458 | |
---|
| 459 | @item EDEADLK |
---|
| 460 | The current thread already owns the mutex. |
---|
| 461 | |
---|
| 462 | @end table |
---|
| 463 | |
---|
| 464 | @subheading DESCRIPTION: |
---|
| 465 | |
---|
| 466 | @subheading NOTES: |
---|
| 467 | |
---|
| 468 | |
---|
| 469 | @page |
---|
| 470 | @subsection pthread_mutex_unlock |
---|
| 471 | |
---|
| 472 | @subheading CALLING SEQUENCE: |
---|
| 473 | |
---|
| 474 | @example |
---|
| 475 | #include <pthread.h> |
---|
| 476 | |
---|
| 477 | int pthread_mutex_unlock( |
---|
| 478 | pthread_mutex_t *mutex |
---|
| 479 | ); |
---|
| 480 | @end example |
---|
| 481 | |
---|
| 482 | @subheading STATUS CODES: |
---|
| 483 | |
---|
| 484 | @table @b |
---|
| 485 | @item EINVAL |
---|
| 486 | The specified mutex is invalid. |
---|
| 487 | |
---|
| 488 | @end table |
---|
| 489 | |
---|
| 490 | @subheading DESCRIPTION: |
---|
| 491 | |
---|
| 492 | @subheading NOTES: |
---|
| 493 | |
---|
| 494 | @page |
---|
| 495 | @subsection pthread_mutex_setprioceiling |
---|
| 496 | |
---|
| 497 | @subheading CALLING SEQUENCE: |
---|
| 498 | |
---|
| 499 | @example |
---|
| 500 | #include <pthread.h> |
---|
| 501 | |
---|
| 502 | int pthread_mutex_setprioceiling( |
---|
| 503 | pthread_mutex_t *mutex, |
---|
| 504 | int prioceiling, |
---|
| 505 | int *oldceiling |
---|
| 506 | ); |
---|
| 507 | @end example |
---|
| 508 | |
---|
| 509 | @subheading STATUS CODES: |
---|
| 510 | |
---|
| 511 | @table @b |
---|
| 512 | @item EINVAL |
---|
| 513 | The oldceiling pointer parameter is invalid. |
---|
| 514 | |
---|
| 515 | @item EINVAL |
---|
| 516 | The prioceiling parameter is an invalid priority. |
---|
| 517 | |
---|
| 518 | @item EINVAL |
---|
| 519 | The specified mutex is invalid. |
---|
| 520 | |
---|
| 521 | @end table |
---|
| 522 | |
---|
| 523 | @subheading DESCRIPTION: |
---|
| 524 | |
---|
| 525 | @subheading NOTES: |
---|
| 526 | |
---|
| 527 | @page |
---|
| 528 | @subsection pthread_mutex_getprioceiling |
---|
| 529 | |
---|
| 530 | @subheading CALLING SEQUENCE: |
---|
| 531 | |
---|
| 532 | @example |
---|
| 533 | #include <pthread.h> |
---|
| 534 | |
---|
| 535 | int pthread_mutex_getprioceiling( |
---|
| 536 | pthread_mutex_t *mutex, |
---|
| 537 | int *prioceiling |
---|
| 538 | ); |
---|
| 539 | @end example |
---|
| 540 | |
---|
| 541 | @subheading STATUS CODES: |
---|
| 542 | |
---|
| 543 | @table @b |
---|
| 544 | @item EINVAL |
---|
| 545 | The prioceiling pointer parameter is invalid. |
---|
| 546 | |
---|
| 547 | @item EINVAL |
---|
| 548 | The specified mutex is invalid. |
---|
| 549 | |
---|
| 550 | @end table |
---|
| 551 | |
---|
| 552 | @subheading DESCRIPTION: |
---|
| 553 | |
---|
| 554 | @subheading NOTES: |
---|
| 555 | |
---|