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 .\" $DragonFly: src/share/man/man3/pthread.3,v 1.5 2007/09/14 19:47:03 swildner Exp $
  33 .\"
  34 .Dd July 10, 2009
  35 .Dt PTHREAD 3
  36 .Os
  37 .Sh NAME
  38 .Nm pthread
  39 .Nd POSIX thread functions
  40 .Sh LIBRARY
  41 .Lb libpthread
  42 .Sh SYNOPSIS
  43 .In pthread.h
  44 .Sh DESCRIPTION
  45 POSIX threads are a set of functions that support applications with
  46 requirements for multiple flows of control, called
  47 .Em threads ,
  48 within a process.
  49 Multithreading is used to improve the performance of a
  50 program.
  51 .Pp
  52 The POSIX thread functions are summarized in this section in the following
  53 groups:
  54 .Pp
  55 .Bl -bullet -offset indent -compact
  56 .It
  57 Thread Routines
  58 .It
  59 Attribute Object Routines
  60 .It
  61 Mutex Routines
  62 .It
  63 Condition Variable Routines
  64 .It
  65 Read/Write Lock Routines
  66 .It
  67 Per-Thread Context Routines
  68 .It
  69 Cleanup Routines
  70 .El
  71 .Ss Thread Routines
  72 .Bl -tag -width indent
  73 .It Xo
  74 .Ft int
  75 .Fo pthread_create
  76 .Fa "pthread_t *thread" "const pthread_attr_t *attr"
  77 .Fa "void *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "void *arg"
  78 .Fc
  79 .Xc
  80 Creates a new thread of execution.
  81 .It Xo
  82 .Ft int
  83 .Fn pthread_cancel "pthread_t thread"
  84 .Xc
  85 Cancels execution of a thread.
  86 .It Xo
  87 .Ft int
  88 .Fn pthread_detach "pthread_t thread"
  89 .Xc
  90 Marks a thread for deletion.
  91 .It Xo
  92 .Ft int
  93 .Fn pthread_equal "pthread_t t1" "pthread_t t2"
  94 .Xc
  95 Compares two thread IDs.
  96 .It Xo
  97 .Ft void
  98 .Fn pthread_exit "void *value_ptr"
  99 .Xc
 100 Terminates the calling thread.
 101 .It Xo
 102 .Ft int
 103 .Fn pthread_join "pthread_t thread" "void **value_ptr"
 104 .Xc
 105 Causes the calling thread to wait for the termination of the specified thread.
 106 .It Xo
 107 .Ft int
 108 .Fn pthread_kill "pthread_t thread" "int sig"
 109 .Xc
 110 Delivers a signal to a specified thread.
 111 .It Xo
 112 .Ft int
 113 .Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]"
 114 .Xc
 115 Calls an initialization routine once.
 116 .It Xo
 117 .Ft pthread_t
 118 .Fn pthread_self void
 119 .Xc
 120 Returns the thread ID of the calling thread.
 121 .It Xo
 122 .Ft int
 123 .Fn pthread_setcancelstate "int state" "int *oldstate"
 124 .Xc
 125 Sets the current thread's cancelability state.
 126 .It Xo
 127 .Ft int
 128 .Fn pthread_setcanceltype "int type" "int *oldtype"
 129 .Xc
 130 Sets the current thread's cancelability type.
 131 .It Xo
 132 .Ft void
 133 .Fn pthread_testcancel void
 134 .Xc
 135 Creates a cancellation point in the calling thread.
 136 .It Xo
 137 .Ft void
 138 .Fn pthread_yield void
 139 .Xc
 140 Allows the scheduler to run another thread instead of the current one.
 141 .El
 142 .Ss Attribute Object Routines
 143 .Bl -tag -width indent
 144 .It Xo
 145 .Ft int
 146 .Fn pthread_attr_destroy "pthread_attr_t *attr"
 147 .Xc
 148 Destroy a thread attributes object.
 149 .It Xo
 150 .Ft int
 151 .Fo pthread_attr_getinheritsched
 152 .Fa "const pthread_attr_t *attr" "int *inheritsched"
 153 .Fc
 154 .Xc
 155 Get the inherit scheduling attribute from a thread attributes object.
 156 .It Xo
 157 .Ft int
 158 .Fo pthread_attr_getschedparam
 159 .Fa "const pthread_attr_t *attr" "struct sched_param *param"
 160 .Fc
 161 .Xc
 162 Get the scheduling parameter attribute from a thread attributes object.
 163 .It Xo
 164 .Ft int
 165 .Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
 166 .Xc
 167 Get the scheduling policy attribute from a thread attributes object.
 168 .It Xo
 169 .Ft int
 170 .Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
 171 .Xc
 172 Get the contention scope attribute from a thread attributes object.
 173 .It Xo
 174 .Ft int
 175 .Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
 176 .Xc
 177 Get the stack size attribute from a thread attributes object.
 178 .It Xo
 179 .Ft int
 180 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
 181 .Xc
 182 Get the stack address attribute from a thread attributes object.
 183 .It Xo
 184 .Ft int
 185 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
 186 .Xc
 187 Get the detach state attribute from a thread attributes object.
 188 .It Xo
 189 .Ft int
 190 .Fn pthread_attr_init "pthread_attr_t *attr"
 191 .Xc
 192 Initialize a thread attributes object with default values.
 193 .It Xo
 194 .Ft int
 195 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 196 .Xc
 197 Set the inherit scheduling attribute in a thread attributes object.
 198 .It Xo
 199 .Ft int
 200 .Fo pthread_attr_setschedparam
 201 .Fa "pthread_attr_t *attr" "const struct sched_param *param"
 202 .Fc
 203 .Xc
 204 Set the scheduling parameter attribute in a thread attributes object.
 205 .It Xo
 206 .Ft int
 207 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 208 .Xc
 209 Set the scheduling policy attribute in a thread attributes object.
 210 .It Xo
 211 .Ft int
 212 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 213 .Xc
 214 Set the contention scope attribute in a thread attributes object.
 215 .It Xo
 216 .Ft int
 217 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
 218 .Xc
 219 Set the stack size attribute in a thread attributes object.
 220 .It Xo
 221 .Ft int
 222 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
 223 .Xc
 224 Set the stack address attribute in a thread attributes object.
 225 .It Xo
 226 .Ft int
 227 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 228 .Xc
 229 Set the detach state in a thread attributes object.
 230 .El
 231 .Ss Mutex Routines
 232 .Bl -tag -width indent
 233 .It Xo
 234 .Ft int
 235 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
 236 .Xc
 237 Destroy a mutex attributes object.
 238 .It Xo
 239 .Ft int
 240 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling"
 241 .Xc
 242 Obtain priority ceiling attribute of mutex attribute object.
 243 .It Xo
 244 .Ft int
 245 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
 246 .Xc
 247 Obtain protocol attribute of mutex attribute object.
 248 .It Xo
 249 .Ft int
 250 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
 251 .Xc
 252 Obtain the mutex type attribute in the specified mutex attributes object.
 253 .It Xo
 254 .Ft int
 255 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
 256 .Xc
 257 Initialize a mutex attributes object with default values.
 258 .It Xo
 259 .Ft int
 260 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
 261 .Xc
 262 Set priority ceiling attribute of mutex attribute object.
 263 .It Xo
 264 .Ft int
 265 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
 266 .Xc
 267 Set protocol attribute of mutex attribute object.
 268 .It Xo
 269 .Ft int
 270 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
 271 .Xc
 272 Set the mutex type attribute that is used when a mutex is created.
 273 .It Xo
 274 .Ft int
 275 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
 276 .Xc
 277 Destroy a mutex.
 278 .It Xo
 279 .Ft int
 280 .Fo pthread_mutex_init
 281 .Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
 282 .Fc
 283 .Xc
 284 Initialize a mutex with specified attributes.
 285 .It Xo
 286 .Ft int
 287 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
 288 .Xc
 289 Lock a mutex and block until it becomes available.
 290 .It Xo
 291 .Ft int
 292 .Fo pthread_mutex_timedlock
 293 .Fa "pthread_mutex_t *mutex" "const struct timespec *abstime"
 294 .Fc
 295 .Xc
 296 Lock a mutex and block until it becomes available or until the timeout expires.
 297 .It Xo
 298 .Ft int
 299 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 300 .Xc
 301 Try to lock a mutex, but do not block if the mutex is locked by another thread,
 302 including the current thread.
 303 .It Xo
 304 .Ft int
 305 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
 306 .Xc
 307 Unlock a mutex.
 308 .El
 309 .Ss Condition Variable Routines
 310 .Bl -tag -width indent
 311 .It Xo
 312 .Ft int
 313 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
 314 .Xc
 315 Destroy a condition variable attributes object.
 316 .It Xo
 317 .Ft int
 318 .Fn pthread_condattr_init "pthread_condattr_t *attr"
 319 .Xc
 320 Initialize a condition variable attributes object with default values.
 321 .It Xo
 322 .Ft int
 323 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
 324 .Xc
 325 Unblock all threads currently blocked on the specified condition variable.
 326 .It Xo
 327 .Ft int
 328 .Fn pthread_cond_destroy "pthread_cond_t *cond"
 329 .Xc
 330 Destroy a condition variable.
 331 .It Xo
 332 .Ft int
 333 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
 334 .Xc
 335 Initialize a condition variable with specified attributes.
 336 .It Xo
 337 .Ft int
 338 .Fn pthread_cond_signal "pthread_cond_t *cond"
 339 .Xc
 340 Unblock at least one of the threads blocked on the specified condition variable.
 341 .It Xo
 342 .Ft int
 343 .Fo pthread_cond_timedwait
 344 .Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex"
 345 .Fa "const struct timespec *abstime"
 346 .Fc
 347 .Xc
 348 Wait no longer than the specified time for a condition
 349 and lock the specified mutex.
 350 .It Xo
 351 .Ft int
 352 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
 353 .Xc
 354 Wait for a condition and lock the specified mutex.
 355 .El
 356 .Ss Read/Write Lock Routines
 357 .Bl -tag -width indent
 358 .It Xo
 359 .Ft int
 360 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 361 .Xc
 362 Destroy a read/write lock object.
 363 .It Xo
 364 .Ft int
 365 .Fo pthread_rwlock_init
 366 .Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
 367 .Fc
 368 .Xc
 369 Initialize a read/write lock object.
 370 .It Xo
 371 .Ft int
 372 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 373 .Xc
 374 Lock a read/write lock for reading, blocking until the lock can be
 375 acquired.
 376 .It Xo
 377 .Ft int
 378 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 379 .Xc
 380 Attempt to lock a read/write lock for reading, without blocking if the
 381 lock is unavailable.
 382 .It Xo
 383 .Ft int
 384 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 385 .Xc
 386 Attempt to lock a read/write lock for writing, without blocking if the
 387 lock is unavailable.
 388 .It Xo
 389 .Ft int
 390 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 391 .Xc
 392 Unlock a read/write lock.
 393 .It Xo
 394 .Ft int
 395 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 396 .Xc
 397 Lock a read/write lock for writing, blocking until the lock can be
 398 acquired.
 399 .It Xo
 400 .Ft int
 401 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 402 .Xc
 403 Destroy a read/write lock attribute object.
 404 .It Xo
 405 .Ft int
 406 .Fo pthread_rwlockattr_getpshared
 407 .Fa "const pthread_rwlockattr_t *attr" "int *pshared"
 408 .Fc
 409 .Xc
 410 Retrieve the process shared setting for the read/write lock attribute
 411 object.
 412 .It Xo
 413 .Ft int
 414 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 415 .Xc
 416 Initialize a read/write lock attribute object.
 417 .It Xo
 418 .Ft int
 419 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
 420 .Xc
 421 Set the process shared setting for the read/write lock attribute object.
 422 .El
 423 .Ss Per-Thread Context Routines
 424 .Bl -tag -width indent
 425 .It Xo
 426 .Ft int
 427 .Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]"
 428 .Xc
 429 Create a thread-specific data key.
 430 .It Xo
 431 .Ft int
 432 .Fn pthread_key_delete "pthread_key_t key"
 433 .Xc
 434 Delete a thread-specific data key.
 435 .It Xo
 436 .Ft "void *"
 437 .Fn pthread_getspecific "pthread_key_t key"
 438 .Xc
 439 Get the thread-specific value for the specified key.
 440 .It Xo
 441 .Ft int
 442 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 443 .Xc
 444 Set the thread-specific value for the specified key.
 445 .El
 446 .Ss Cleanup Routines
 447 .Bl -tag -width indent
 448 .It Xo
 449 .Ft int
 450 .Fo pthread_atfork
 451 .Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]"
 452 .Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]"
 453 .Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]"
 454 .Fc
 455 .Xc
 456 Register fork handlers
 457 .It Xo
 458 .Ft void
 459 .Fn pthread_cleanup_pop "int execute"
 460 .Xc
 461 Remove the routine at the top of the calling thread's cancellation cleanup
 462 stack and optionally invoke it.
 463 .It Xo
 464 .Ft void
 465 .Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg"
 466 .Xc
 467 Push the specified cancellation cleanup handler onto the calling thread's
 468 cancellation stack.
 469 .El
 470 .Sh IMPLEMENTATION NOTES
 471 The current
 472 .Dx
 473 POSIX thread implementation is built in the library
 474 .Fa libc_r
 475 which contains both thread-safe libc functions and the thread functions.
 476 This library replaces
 477 .Fa libc
 478 for threaded applications.
 479 .Pp
 480 By default,
 481 .Fa libc_r
 482 is built as part of a 'make world'.  To disable the build of
 483 .Fa libc_r
 484 you must supply the '-DNOLIBC_R' option to
 485 .Xr make 1 .
 486 .Pp
 487 A
 488 .Fx
 489 and
 490 .Dx
 491 specific option exists in
 492 .Xr gcc 1
 493 to simplify the linking of threaded processes.
 494 .Fa gcc -pthread
 495 links a threaded process against
 496 .Fa libc_r
 497 instead of
 498 .Fa libc .
 499 .Sh SEE ALSO
 500 .Xr pthread_atfork 3 ,
 501 .Xr pthread_cancel 3 ,
 502 .Xr pthread_cleanup_pop 3 ,
 503 .Xr pthread_cleanup_push 3 ,
 504 .Xr pthread_condattr_destroy 3 ,
 505 .Xr pthread_condattr_init 3 ,
 506 .Xr pthread_cond_broadcast 3 ,
 507 .Xr pthread_cond_destroy 3 ,
 508 .Xr pthread_cond_init 3 ,
 509 .Xr pthread_cond_signal 3 ,
 510 .Xr pthread_cond_timedwait 3 ,
 511 .Xr pthread_cond_wait 3 ,
 512 .Xr pthread_create 3 ,
 513 .Xr pthread_detach 3 ,
 514 .Xr pthread_equal 3 ,
 515 .Xr pthread_exit 3 ,
 516 .Xr pthread_getspecific 3 ,
 517 .Xr pthread_join 3 ,
 518 .Xr pthread_key_delete 3 ,
 519 .Xr pthread_kill 3 ,
 520 .Xr pthread_mutexattr_destroy 3 ,
 521 .Xr pthread_mutexattr_getprioceiling 3 ,
 522 .Xr pthread_mutexattr_getprotocol 3 ,
 523 .Xr pthread_mutexattr_gettype 3 ,
 524 .Xr pthread_mutexattr_init 3 ,
 525 .Xr pthread_mutexattr_setprioceiling 3 ,
 526 .Xr pthread_mutexattr_setprotocol 3 ,
 527 .Xr pthread_mutexattr_settype 3 ,
 528 .Xr pthread_mutex_destroy 3 ,
 529 .Xr pthread_mutex_init 3 ,
 530 .Xr pthread_mutex_lock 3 ,
 531 .Xr pthread_mutex_trylock 3 ,
 532 .Xr pthread_mutex_unlock 3 ,
 533 .Xr pthread_once 3 ,
 534 .Xr pthread_rwlockattr_destroy 3 ,
 535 .Xr pthread_rwlockattr_getpshared 3 ,
 536 .Xr pthread_rwlockattr_init 3 ,
 537 .Xr pthread_rwlockattr_setpshared 3 ,
 538 .Xr pthread_rwlock_destroy 3 ,
 539 .Xr pthread_rwlock_init 3 ,
 540 .Xr pthread_rwlock_rdlock 3 ,
 541 .Xr pthread_rwlock_unlock 3 ,
 542 .Xr pthread_rwlock_wrlock 3 ,
 543 .Xr pthread_self 3 ,
 544 .Xr pthread_setcancelstate 3 ,
 545 .Xr pthread_setcanceltype 3 ,
 546 .Xr pthread_setspecific 3 ,
 547 .Xr pthread_testcancel 3
 548 .Sh STANDARDS
 549 The functions with the
 550 .Nm pthread_
 551 prefix and not
 552 .Nm _np
 553 suffix or
 554 .Nm pthread_rwlock
 555 prefix conform to
 556 .St -p1003.1-96 .
 557 .Pp
 558 The functions with the
 559 .Nm pthread_
 560 prefix and
 561 .Nm _np
 562 suffix are non-portable extensions to POSIX threads.
 563 .Pp
 564 The functions with the
 565 .Nm pthread_rwlock
 566 prefix are extensions created by The Open Group as part of the
 567 .St -susv2 .