lib/libpthread/pthread.3

   1 .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by John Birrell.
  15 .\" 4. Neither the name of the author nor the names of any co-contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD: src/share/man/man3/pthread.3,v 1.33 2009/04/01 08:08:25 trhodes Exp $
  32 .\"
  33 .Dd November 15, 2019
  34 .Dt PTHREAD 3
  35 .Os
  36 .Sh NAME
  37 .Nm pthread
  38 .Nd POSIX thread functions
  39 .Sh LIBRARY
  40 .Lb libpthread
  41 .Sh SYNOPSIS
  42 .In pthread.h
  43 .Sh DESCRIPTION
  44 POSIX threads are a set of functions that support applications with
  45 requirements for multiple flows of control, called
  46 .Em threads ,
  47 within a process.
  48 Multithreading is used to improve the performance of a
  49 program.
  50 .Pp
  51 The POSIX thread functions are summarized in this section in the following
  52 groups:
  53 .Pp
  54 .Bl -bullet -offset indent -compact
  55 .It
  56 Thread Routines
  57 .It
  58 Attribute Object Routines
  59 .It
  60 Mutex Routines
  61 .It
  62 Condition Variable Routines
  63 .It
  64 Read/Write Lock Routines
  65 .It
  66 Spin Lock Routines
  67 .It
  68 Barrier Routines
  69 .It
  70 Per-Thread Context Routines
  71 .It
  72 Cleanup Routines
  73 .El
  74 .Ss Thread Routines
  75 .Bl -tag -width indent
  76 .It Xo
  77 .Ft int
  78 .Fo pthread_create
  79 .Fa "pthread_t * restrict thread" "const pthread_attr_t * restrict attr"
  80 .Fa "void *(*start_routine)(void *)" "void * restrict arg"
  81 .Fc
  82 .Xc
  83 Creates a new thread of execution.
  84 .It Xo
  85 .Ft int
  86 .Fn pthread_cancel "pthread_t thread"
  87 .Xc
  88 Cancels execution of a thread.
  89 .It Xo
  90 .Ft int
  91 .Fn pthread_detach "pthread_t thread"
  92 .Xc
  93 Marks a thread for deletion.
  94 .It Xo
  95 .Ft int
  96 .Fn pthread_equal "pthread_t t1" "pthread_t t2"
  97 .Xc
  98 Compares two thread IDs.
  99 .It Xo
 100 .Ft void
 101 .Fn pthread_exit "void *value_ptr"
 102 .Xc
 103 Terminates the calling thread.
 104 .It Xo
 105 .Ft int
 106 .Fn pthread_getconcurrency void
 107 .Xc
 108 Get the current thread's level of concurrency.
 109 .It Xo
 110 .Ft int
 111 .Fn pthread_getcpuclockid "pthread_t thread" "clockid_t *clock_id"
 112 .Xc
 113 Access a specific thread's CPU-time clock.
 114 .It Xo
 115 .Ft int
 116 .Fn pthread_getschedparam "pthread_t thread" "int * restrict policy" "struct sched_param * restrict param"
 117 .Xc
 118 Get the scheduling parameters of a specific thread.
 119 .It Xo
 120 .Ft int
 121 .Fn pthread_join "pthread_t thread" "void **value_ptr"
 122 .Xc
 123 Causes the calling thread to wait for the termination of the specified thread.
 124 .It Xo
 125 .Ft int
 126 .Fn pthread_kill "pthread_t thread" "int sig"
 127 .Xc
 128 Delivers a signal to a specified thread.
 129 .It Xo
 130 .Ft int
 131 .Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
 132 .Xc
 133 Calls an initialization routine once.
 134 .It Xo
 135 .Ft pthread_t
 136 .Fn pthread_self void
 137 .Xc
 138 Returns the thread ID of the calling thread.
 139 .It Xo
 140 .Ft int
 141 .Fn pthread_setcancelstate "int state" "int *oldstate"
 142 .Xc
 143 Sets the current thread's cancelability state.
 144 .It Xo
 145 .Ft int
 146 .Fn pthread_setcanceltype "int type" "int *oldtype"
 147 .Xc
 148 Sets the current thread's cancelability type.
 149 .It Xo
 150 .Ft int
 151 .Fn pthread_setconcurrency "int new_level"
 152 .Xc
 153 Set the current thread's level of concurrency.
 154 .It Xo
 155 .Ft int
 156 .Fn pthread_setschedparam "pthread_t thread" "int policy" "struct sched_param *param"
 157 .Xc
 158 Set the scheduling parameters for a specific thread.
 159 .It Xo
 160 .Ft void
 161 .Fn pthread_sigmask "int how" "const sigset_t * restrict set" "sigset_t * restrict oset"
 162 .Xc
 163 Examine and/or change the calling thread's signal mask.
 164 .It Xo
 165 .Ft void
 166 .Fn pthread_testcancel void
 167 .Xc
 168 Creates a cancellation point in the calling thread.
 169 .It Xo
 170 .Ft void
 171 .Fn pthread_yield void
 172 .Xc
 173 Allows the scheduler to run another thread instead of the current one.
 174 .El
 175 .Ss Attribute Object Routines
 176 .Bl -tag -width indent
 177 .It Xo
 178 .Ft int
 179 .Fn pthread_attr_destroy "pthread_attr_t *attr"
 180 .Xc
 181 Destroy a thread attributes object.
 182 .It Xo
 183 .Ft int
 184 .Fo pthread_attr_getguardsize
 185 .Fa "const pthread_attr_t * restrict attr" "size_t * restrict guardsize"
 186 .Fc
 187 .Xc
 188 Get the guard size attribute from a thread attributes object.
 189 .It Xo
 190 .Ft int
 191 .Fo pthread_attr_getinheritsched
 192 .Fa "const pthread_attr_t * restrict attr" "int * restrict inheritsched"
 193 .Fc
 194 .Xc
 195 Get the inherit scheduling attribute from a thread attributes object.
 196 .It Xo
 197 .Ft int
 198 .Fo pthread_attr_getschedparam
 199 .Fa "const pthread_attr_t * restrict attr" "struct sched_param * restrict param"
 200 .Fc
 201 .Xc
 202 Get the scheduling parameter attribute from a thread attributes object.
 203 .It Xo
 204 .Ft int
 205 .Fn pthread_attr_getschedpolicy "const pthread_attr_t * restrict attr" "int * restrict policy"
 206 .Xc
 207 Get the scheduling policy attribute from a thread attributes object.
 208 .It Xo
 209 .Ft int
 210 .Fn pthread_attr_getscope "const pthread_attr_t * restrict attr" "int * restrict contentionscope"
 211 .Xc
 212 Get the contention scope attribute from a thread attributes object.
 213 .It Xo
 214 .Ft int
 215 .Fn pthread_attr_getstack "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" "size_t * restrict stacksize"
 216 .Xc
 217 Get the stack attributes from a thread attributes object.
 218 .It Xo
 219 .Ft int
 220 .Fn pthread_attr_getstacksize "const pthread_attr_t * restrict attr" "size_t * restrict stacksize"
 221 .Xc
 222 Get the stack size attribute from a thread attributes object.
 223 .It Xo
 224 .Ft int
 225 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
 226 .Xc
 227 Get the stack address attribute from a thread attributes object.
 228 .It Xo
 229 .Ft int
 230 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
 231 .Xc
 232 Get the detach state attribute from a thread attributes object.
 233 .It Xo
 234 .Ft int
 235 .Fn pthread_attr_init "pthread_attr_t *attr"
 236 .Xc
 237 Initialize a thread attributes object with default values.
 238 .It Xo
 239 .Ft int
 240 .Fo pthread_attr_setguardsize
 241 .Fa "pthread_attr_t *attr" "size_t guardsize"
 242 .Fc
 243 .Xc
 244 Set the guard size attribute in a thread attributes object.
 245 .It Xo
 246 .Ft int
 247 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 248 .Xc
 249 Set the inherit scheduling attribute in a thread attributes object.
 250 .It Xo
 251 .Ft int
 252 .Fo pthread_attr_setschedparam
 253 .Fa "pthread_attr_t * restrict attr" "const struct sched_param * restrict param"
 254 .Fc
 255 .Xc
 256 Set the scheduling parameter attribute in a thread attributes object.
 257 .It Xo
 258 .Ft int
 259 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 260 .Xc
 261 Set the scheduling policy attribute in a thread attributes object.
 262 .It Xo
 263 .Ft int
 264 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 265 .Xc
 266 Set the contention scope attribute in a thread attributes object.
 267 .It Xo
 268 .Ft int
 269 .Fn pthread_attr_setstack "pthread_attr_t *attr" "void *stackaddr" "size_t stacksize"
 270 .Xc
 271 Set the stack attributes in a thread attributes object.
 272 .It Xo
 273 .Ft int
 274 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
 275 .Xc
 276 Set the stack size attribute in a thread attributes object.
 277 .It Xo
 278 .Ft int
 279 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
 280 .Xc
 281 Set the stack address attribute in a thread attributes object.
 282 .It Xo
 283 .Ft int
 284 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 285 .Xc
 286 Set the detach state in a thread attributes object.
 287 .El
 288 .Ss Mutex Routines
 289 .Bl -tag -width indent
 290 .It Xo
 291 .Ft int
 292 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
 293 .Xc
 294 Destroy a mutex attributes object.
 295 .It Xo
 296 .Ft int
 297 .Fn pthread_mutexattr_getprioceiling "const pthread_mutexattr_t * restrict attr" "int * restrict ceiling"
 298 .Xc
 299 Obtain priority ceiling attribute of mutex attribute object.
 300 .It Xo
 301 .Ft int
 302 .Fn pthread_mutexattr_getprotocol "const pthread_mutexattr_t * restrict attr" "int * restrict protocol"
 303 .Xc
 304 Obtain protocol attribute of mutex attribute object.
 305 .It Xo
 306 .Ft int
 307 .Fn pthread_mutexattr_getpshared "const pthread_mutexattr_t * restrict attr" "int * restrict pshared"
 308 .Xc
 309 Get the process shared setting from a mutex attributes object.
 310 .It Xo
 311 .Ft int
 312 .Fn pthread_mutexattr_gettype "const pthread_mutexattr_t * restrict attr" "int * restrict type"
 313 .Xc
 314 Obtain the mutex type attribute in the specified mutex attributes object.
 315 .It Xo
 316 .Ft int
 317 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
 318 .Xc
 319 Initialize a mutex attributes object with default values.
 320 .It Xo
 321 .Ft int
 322 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
 323 .Xc
 324 Set priority ceiling attribute of mutex attribute object.
 325 .It Xo
 326 .Ft int
 327 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
 328 .Xc
 329 Set protocol attribute of mutex attribute object.
 330 .It Xo
 331 .Ft int
 332 .Fn pthread_mutexattr_setpshared "pthread_mutexattr_t *attr" "int pshared"
 333 .Xc
 334 Set the process shared setting in a mutex attributes object.
 335 .It Xo
 336 .Ft int
 337 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
 338 .Xc
 339 Set the mutex type attribute that is used when a mutex is created.
 340 .It Xo
 341 .Ft int
 342 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
 343 .Xc
 344 Destroy a mutex.
 345 .It Xo
 346 .Ft int
 347 .Fn pthread_mutex_getprioceiling "const pthread_mutex_t * restrict mutex" "int * restrict ceiling"
 348 .Xc
 349 Get the priority ceiling of a mutex.
 350 .It Xo
 351 .Ft int
 352 .Fo pthread_mutex_init
 353 .Fa "pthread_mutex_t * restrict mutex" "const pthread_mutexattr_t * restrict attr"
 354 .Fc
 355 .Xc
 356 Initialize a mutex with specified attributes.
 357 .It Xo
 358 .Ft int
 359 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
 360 .Xc
 361 Lock a mutex and block until it becomes available.
 362 .It Xo
 363 .Ft int
 364 .Fn pthread_mutex_setprioceiling "pthread_mutex_t * restrict mutex" "int ceiling" "int * restrict old_ceiling"
 365 .Xc
 366 Set the priority ceiling of a mutex.
 367 .It Xo
 368 .Ft int
 369 .Fo pthread_mutex_timedlock
 370 .Fa "pthread_mutex_t * restrict mutex" "const struct timespec * restrict abstime"
 371 .Fc
 372 .Xc
 373 Lock a mutex and block until it becomes available or until the timeout expires.
 374 .It Xo
 375 .Ft int
 376 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 377 .Xc
 378 Try to lock a mutex, but do not block if the mutex is locked by another thread,
 379 including the current thread.
 380 .It Xo
 381 .Ft int
 382 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
 383 .Xc
 384 Unlock a mutex.
 385 .El
 386 .Ss Condition Variable Routines
 387 .Bl -tag -width indent
 388 .It Xo
 389 .Ft int
 390 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
 391 .Xc
 392 Destroy a condition variable attributes object.
 393 .It Xo
 394 .Ft int
 395 .Fn pthread_condattr_getclock "const pthread_condattr_t * restrict attr" "clockid_t * restrict clock_id"
 396 .Xc
 397 Get the clock selection attribute from a condition variable attributes object.
 398 .It Xo
 399 .Ft int
 400 .Fn pthread_condattr_init "pthread_condattr_t *attr"
 401 .Xc
 402 Initialize a condition variable attributes object with default values.
 403 .It Xo
 404 .Ft int
 405 .Fn pthread_condattr_getpshared "const pthread_condattr_t * restrict attr" "int * restrict pshared"
 406 .Xc
 407 Get the process shared setting from a condition variable attributes object.
 408 .It Xo
 409 .Ft int
 410 .Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id"
 411 .Xc
 412 Set the clock selection attribute in a condition variable attributes object.
 413 .It Xo
 414 .Ft int
 415 .Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared"
 416 .Xc
 417 Set the process shared setting in a condition variable attributes object.
 418 .It Xo
 419 .Ft int
 420 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
 421 .Xc
 422 Unblock all threads currently blocked on the specified condition variable.
 423 .It Xo
 424 .Ft int
 425 .Fn pthread_cond_destroy "pthread_cond_t *cond"
 426 .Xc
 427 Destroy a condition variable.
 428 .It Xo
 429 .Ft int
 430 .Fn pthread_cond_init "pthread_cond_t * restrict cond" "const pthread_condattr_t * restrict attr"
 431 .Xc
 432 Initialize a condition variable with specified attributes.
 433 .It Xo
 434 .Ft int
 435 .Fn pthread_cond_signal "pthread_cond_t *cond"
 436 .Xc
 437 Unblock at least one of the threads blocked on the specified condition variable.
 438 .It Xo
 439 .Ft int
 440 .Fo pthread_cond_timedwait
 441 .Fa "pthread_cond_t * restrict cond" "pthread_mutex_t * restrict mutex"
 442 .Fa "const struct timespec * restrict abstime"
 443 .Fc
 444 .Xc
 445 Wait no longer than the specified time for a condition
 446 and lock the specified mutex.
 447 .It Xo
 448 .Ft int
 449 .Fn pthread_cond_wait "pthread_cond_t * restrict cond" "pthread_mutex_t * restrict mutex"
 450 .Xc
 451 Wait for a condition and lock the specified mutex.
 452 .El
 453 .Ss Read/Write Lock Routines
 454 .Bl -tag -width indent
 455 .It Xo
 456 .Ft int
 457 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 458 .Xc
 459 Destroy a read/write lock object.
 460 .It Xo
 461 .Ft int
 462 .Fo pthread_rwlock_init
 463 .Fa "pthread_rwlock_t * restrict lock" "const pthread_rwlockattr_t * restrict attr"
 464 .Fc
 465 .Xc
 466 Initialize a read/write lock object.
 467 .It Xo
 468 .Ft int
 469 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 470 .Xc
 471 Lock a read/write lock for reading, blocking until the lock can be
 472 acquired.
 473 .It Xo
 474 .Ft int
 475 .Fn pthread_rwlock_timedrdlock "pthread_rwlock_t * restrict lock" "const struct timespec * restrict abstime"
 476 .Xc
 477 Lock a read/write lock for reading with a timeout.
 478 .It Xo
 479 .Ft int
 480 .Fn pthread_rwlock_timedwrlock "pthread_rwlock_t * restrict lock" "const struct timespec * restrict abstime"
 481 .Xc
 482 Lock a read/write lock for writing with a timeout.
 483 .It Xo
 484 .Ft int
 485 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 486 .Xc
 487 Attempt to lock a read/write lock for reading, without blocking if the
 488 lock is unavailable.
 489 .It Xo
 490 .Ft int
 491 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 492 .Xc
 493 Attempt to lock a read/write lock for writing, without blocking if the
 494 lock is unavailable.
 495 .It Xo
 496 .Ft int
 497 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 498 .Xc
 499 Unlock a read/write lock.
 500 .It Xo
 501 .Ft int
 502 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 503 .Xc
 504 Lock a read/write lock for writing, blocking until the lock can be
 505 acquired.
 506 .It Xo
 507 .Ft int
 508 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 509 .Xc
 510 Destroy a read/write lock attribute object.
 511 .It Xo
 512 .Ft int
 513 .Fo pthread_rwlockattr_getpshared
 514 .Fa "const pthread_rwlockattr_t * restrict attr" "int * restrict pshared"
 515 .Fc
 516 .Xc
 517 Retrieve the process shared setting for the read/write lock attribute
 518 object.
 519 .It Xo
 520 .Ft int
 521 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 522 .Xc
 523 Initialize a read/write lock attribute object.
 524 .It Xo
 525 .Ft int
 526 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
 527 .Xc
 528 Set the process shared setting for the read/write lock attribute object.
 529 .El
 530 .Ss Spin Lock Routines
 531 .Bl -tag -width indent
 532 .It Xo
 533 .Ft int
 534 .Fn pthread_spin_destroy "pthread_spinlock_t *lock"
 535 .Xc
 536 Destroy a spin lock object.
 537 .It Xo
 538 .Ft int
 539 .Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared"
 540 .Xc
 541 Initialize a spin lock object.
 542 .It Xo
 543 .Ft int
 544 .Fn pthread_spin_lock "pthread_spinlock_t *lock"
 545 .Xc
 546 Lock a spin lock object.
 547 .It Xo
 548 .Ft int
 549 .Fn pthread_spin_trylock "pthread_spinlock_t *lock"
 550 .Xc
 551 Lock a spin lock object if it is not held.
 552 .It Xo
 553 .Ft int
 554 .Fn pthread_spin_unlock "pthread_spinlock_t *lock"
 555 .Xc
 556 Unlock a spin lock object.
 557 .El
 558 .Ss Barrier Routines
 559 .Bl -tag -width indent
 560 .It Xo
 561 .Ft int
 562 .Fn pthread_barrier_destroy "pthread_barrier_t *barrier"
 563 .Xc
 564 Delete a barrier and its resources.
 565 .It Xo
 566 .Ft int
 567 .Fn pthread_barrier_init "pthread_barrier_t * restrict barrier" "const pthread_barrierattr_t * restrict attr" "unsigned count"
 568 .Xc
 569 Initialize a barrier with the specified attribute object.
 570 .It Xo
 571 .Ft int
 572 .Fn pthread_barrier_wait "pthread_barrier_t *barrier"
 573 .Xc
 574 Block the calling threads until the barrier count is reached.
 575 .It Xo
 576 .Ft int
 577 .Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr"
 578 .Xc
 579 Destroy a barrier attribute object.
 580 .It Xo
 581 .Ft int
 582 .Fn pthread_barrierattr_getpshared "const pthread_barrierattr_t * restrict attr" "int * restrict pshared"
 583 .Xc
 584 Get the process-shared attribute from a barrier attribute object.
 585 .It Xo
 586 .Ft int
 587 .Fn pthread_barrierattr_init "pthread_barrierattr_t *attr"
 588 .Xc
 589 Initialize a barrier attribute object.
 590 .It Xo
 591 .Ft int
 592 .Fn pthread_barrierattr_setpshared "pthread_barrierattr_t *attr" "int pshared"
 593 .Xc
 594 Set the process-shared attribute in a barrier attribute object.
 595 .El
 596 .Ss Per-Thread Context Routines
 597 .Bl -tag -width indent
 598 .It Xo
 599 .Ft int
 600 .Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
 601 .Xc
 602 Create a thread-specific data key.
 603 .It Xo
 604 .Ft int
 605 .Fn pthread_key_delete "pthread_key_t key"
 606 .Xc
 607 Delete a thread-specific data key.
 608 .It Xo
 609 .Ft "void *"
 610 .Fn pthread_getspecific "pthread_key_t key"
 611 .Xc
 612 Get the thread-specific value for the specified key.
 613 .It Xo
 614 .Ft int
 615 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 616 .Xc
 617 Set the thread-specific value for the specified key.
 618 .El
 619 .Ss Cleanup Routines
 620 .Bl -tag -width indent
 621 .It Xo
 622 .Ft int
 623 .Fo pthread_atfork
 624 .Fa "void (*prepare)(void)"
 625 .Fa "void (*parent)(void)"
 626 .Fa "void (*child)(void)"
 627 .Fc
 628 .Xc
 629 Register fork handlers
 630 .It Xo
 631 .Ft void
 632 .Fn pthread_cleanup_pop "int execute"
 633 .Xc
 634 Remove the routine at the top of the calling thread's cancellation cleanup
 635 stack and optionally invoke it.
 636 .It Xo
 637 .Ft void
 638 .Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
 639 .Xc
 640 Push the specified cancellation cleanup handler onto the calling thread's
 641 cancellation stack.
 642 .El
 643 .Sh IMPLEMENTATION NOTES
 644 The current
 645 .Dx
 646 POSIX thread implementation is built in the library
 647 .Sy libthread_xu
 648 which contains both thread-safe libc functions and the thread functions.
 649 .Pp
 650 In
 651 .Dx ,
 652 it is possible to switch the threading library used by dynamically linked
 653 binaries at execution time by re-linking
 654 .Pa /usr/lib/libpthread.so.x
 655 to a different library in
 656 .Pa /usr/lib/thread .
 657 At link time,
 658 .Xr ld 1
 659 reads the
 660 .Sy SONAME
 661 of
 662 .Pa libpthread.so ,
 663 which is set to
 664 .Pa libpthread.so.0
 665 (or a higher major, if there were ABI changes).
 666 For normal libraries
 667 .Pa libfoo.so
 668 is usually a symlink to
 669 .Pa libfoo.so.3
 670 which also has its
 671 .Sy SONAME
 672 set to
 673 .Pa libfoo.so.3 ,
 674 so that if
 675 .Pa libfoo.so.4
 676 is installed, programs will still continue to use
 677 .Pa libfoo.so.3
 678 and not follow the symlink
 679 .Pa libfoo.so
 680 to the newer (and possibly incompatible)
 681 .Pa libfoo.so.4 .
 682 What we do for
 683 .Pa libpthread.so
 684 is approximately the opposite:
 685 .Pa libpthread.so
 686 is not a symlink but nevertheless has its
 687 .Sy SONAME
 688 set to
 689 .Pa libpthread.so.0 .
 690 .Pa libpthread.so.0 ,
 691 however, is a symlink to the threading library of the user's choice.
 692 The linker will use the default threading library which
 693 .Pa libpthread.so
 694 is linked to, but the runtime linker will instead follow the symlink.
 695 .Pp
 696 .Pa libc.so
 697 defines all pthread functions as weak symbols except for
 698 .Fn pthread_create
 699 (which is defined by libpthread.so.x to satisfy
 700 .Xr ld 1 ) .
 701 At execution time,
 702 .Xr rtld 1
 703 will resolve all these references to the strong symbols from the thread
 704 library.
 705 .Pp
 706 .\"
 707 .\".Xr make.conf 5
 708 .\"option,
 709 .\".Va THREAD_LIB ,
 710 .\"can be used to override the system's default threading library.
 711 .\".Pp
 712 A
 713 .Dx
 714 specific option exists in
 715 .Xr gcc 1
 716 to simplify the linking of threaded processes.
 717 .Nm gcc Fl pthread
 718 links a threaded process against
 719 .Pa libpthread.so
 720 instead of
 721 .Fa libc .
 722 .Sh SEE ALSO
 723 .Xr pthread_atfork 3 ,
 724 .Xr pthread_attr_destroy 3 ,
 725 .Xr pthread_attr_getdetachstate 3 ,
 726 .Xr pthread_attr_getguardsize 3 ,
 727 .Xr pthread_attr_getinheritsched 3 ,
 728 .Xr pthread_attr_getschedparam 3 ,
 729 .Xr pthread_attr_getschedpolicy 3 ,
 730 .Xr pthread_attr_getscope 3 ,
 731 .Xr pthread_attr_getstack 3 ,
 732 .Xr pthread_attr_getstackaddr 3 ,
 733 .Xr pthread_attr_getstacksize 3 ,
 734 .Xr pthread_attr_init 3 ,
 735 .Xr pthread_attr_setdetachstate 3 ,
 736 .Xr pthread_attr_setguardsize 3 ,
 737 .Xr pthread_attr_setinheritsched 3 ,
 738 .Xr pthread_attr_setschedparam 3 ,
 739 .Xr pthread_attr_setschedpolicy 3 ,
 740 .Xr pthread_attr_setscope 3 ,
 741 .Xr pthread_attr_setstack 3 ,
 742 .Xr pthread_attr_setstackaddr 3 ,
 743 .Xr pthread_attr_setstacksize 3 ,
 744 .Xr pthread_barrierattr_destroy 3 ,
 745 .Xr pthread_barrierattr_getpshared 3 ,
 746 .Xr pthread_barrierattr_init 3 ,
 747 .Xr pthread_barrierattr_setpshared 3 ,
 748 .Xr pthread_barrier_destroy 3 ,
 749 .Xr pthread_barrier_init 3 ,
 750 .Xr pthread_barrier_wait 3 ,
 751 .Xr pthread_cancel 3 ,
 752 .Xr pthread_cleanup_pop 3 ,
 753 .Xr pthread_cleanup_push 3 ,
 754 .Xr pthread_condattr_destroy 3 ,
 755 .Xr pthread_condattr_getclock 3 ,
 756 .Xr pthread_condattr_getpshared 3 ,
 757 .Xr pthread_condattr_init 3 ,
 758 .Xr pthread_condattr_setclock 3 ,
 759 .Xr pthread_condattr_setpshared 3 ,
 760 .Xr pthread_cond_broadcast 3 ,
 761 .Xr pthread_cond_destroy 3 ,
 762 .Xr pthread_cond_init 3 ,
 763 .Xr pthread_cond_signal 3 ,
 764 .Xr pthread_cond_timedwait 3 ,
 765 .Xr pthread_cond_wait 3 ,
 766 .Xr pthread_create 3 ,
 767 .Xr pthread_detach 3 ,
 768 .Xr pthread_equal 3 ,
 769 .Xr pthread_exit 3 ,
 770 .Xr pthread_getconcurrency 3 ,
 771 .Xr pthread_getcpuclockid 3 ,
 772 .Xr pthread_getschedparam 3 ,
 773 .Xr pthread_getspecific 3 ,
 774 .Xr pthread_join 3 ,
 775 .Xr pthread_key_create 3 ,
 776 .Xr pthread_key_delete 3 ,
 777 .Xr pthread_kill 3 ,
 778 .Xr pthread_mutexattr_destroy 3 ,
 779 .Xr pthread_mutexattr_getprioceiling 3 ,
 780 .Xr pthread_mutexattr_getprotocol 3 ,
 781 .Xr pthread_mutexattr_getpshared 3 ,
 782 .Xr pthread_mutexattr_gettype 3 ,
 783 .Xr pthread_mutexattr_init 3 ,
 784 .Xr pthread_mutexattr_setprioceiling 3 ,
 785 .Xr pthread_mutexattr_setprotocol 3 ,
 786 .Xr pthread_mutexattr_setpshared 3 ,
 787 .Xr pthread_mutexattr_settype 3 ,
 788 .Xr pthread_mutex_destroy 3 ,
 789 .Xr pthread_mutex_getprioceiling 3 ,
 790 .Xr pthread_mutex_init 3 ,
 791 .Xr pthread_mutex_lock 3 ,
 792 .Xr pthread_mutex_setprioceiling 3 ,
 793 .Xr pthread_mutex_timedlock 3 ,
 794 .Xr pthread_mutex_trylock 3 ,
 795 .Xr pthread_mutex_unlock 3 ,
 796 .Xr pthread_once 3 ,
 797 .Xr pthread_rwlockattr_destroy 3 ,
 798 .Xr pthread_rwlockattr_getpshared 3 ,
 799 .Xr pthread_rwlockattr_init 3 ,
 800 .Xr pthread_rwlockattr_setpshared 3 ,
 801 .Xr pthread_rwlock_destroy 3 ,
 802 .Xr pthread_rwlock_init 3 ,
 803 .Xr pthread_rwlock_rdlock 3 ,
 804 .Xr pthread_rwlock_timedrdlock 3 ,
 805 .Xr pthread_rwlock_timedwrlock 3 ,
 806 .Xr pthread_rwlock_tryrdlock 3 ,
 807 .Xr pthread_rwlock_trywrlock 3 ,
 808 .Xr pthread_rwlock_unlock 3 ,
 809 .Xr pthread_rwlock_wrlock 3 ,
 810 .Xr pthread_self 3 ,
 811 .Xr pthread_setcancelstate 3 ,
 812 .Xr pthread_setcanceltype 3 ,
 813 .Xr pthread_setconcurrency 3 ,
 814 .Xr pthread_setschedparam 3 ,
 815 .Xr pthread_setspecific 3 ,
 816 .Xr pthread_sigmask 3 ,
 817 .Xr pthread_spin_destroy 3 ,
 818 .Xr pthread_spin_init 3 ,
 819 .Xr pthread_spin_lock 3 ,
 820 .Xr pthread_spin_trylock 3 ,
 821 .Xr pthread_spin_unlock 3 ,
 822 .Xr pthread_testcancel 3 ,
 823 .Xr pthread_yield 3
 824 .Sh STANDARDS
 825 The functions with the
 826 .Nm pthread_
 827 prefix and not
 828 .Nm _np
 829 suffix or
 830 .Nm pthread_rwlock
 831 prefix conform to
 832 .St -p1003.1-96 .
 833 .Pp
 834 The functions with the
 835 .Nm pthread_
 836 prefix and
 837 .Nm _np
 838 suffix are non-portable extensions to POSIX threads.
 839 .Pp
 840 The functions with the
 841 .Nm pthread_rwlock
 842 prefix are extensions created by The Open Group as part of the
 843 .St -susv2 .