man/pthread.3

   1 .\" Portions Copyright (c) 2001 Apple Computer, Inc. All Rights Reserved.
   2 .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by John Birrell.
  16 .\" 4. Neither the name of the author nor the names of any co-contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd August 12, 2014
  35 .Dt PTHREAD 3
  36 .Os Darwin
  37 .Sh NAME
  38 .Nm pthread
  39 .Nd POSIX thread functions
  40 .Sh SYNOPSIS
  41 .In pthread.h
  42 .Sh DESCRIPTION
  43 POSIX threads are a set of functions that support applications with
  44 requirements for multiple flows of control, called
  45 .Em threads ,
  46 within a process.
  47 Multithreading is used to improve the performance of a
  48 program.
  49 .Pp
  50 The POSIX thread functions are summarized in this section in the following
  51 groups:
  52 .Pp
  53 .Bl -bullet -offset indent -compact
  54 .It
  55 Thread Routines
  56 .It
  57 Attribute Object Routines
  58 .It
  59 Mutex Routines
  60 .It
  61 Condition Variable Routines
  62 .It
  63 Read/Write Lock Routines
  64 .It
  65 Per-Thread Context Routines
  66 .It
  67 Cleanup Routines
  68 .El
  69 .Ss Thread Routines
  70 .Bl -tag -width indent
  71 .It Xo
  72 .Ft int
  73 .Fo pthread_create
  74 .Fa "pthread_t *thread" "const pthread_attr_t *attr"
  75 .Fa "void *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "void *arg"
  76 .Fc
  77 .Xc
  78 Creates a new thread of execution.
  79 .It Xo
  80 .Ft int
  81 .Fn pthread_cancel "pthread_t thread"
  82 .Xc
  83 Cancels execution of a thread.
  84 .It Xo
  85 .Ft int
  86 .Fn pthread_detach "pthread_t thread"
  87 .Xc
  88 Marks a thread for deletion.
  89 .It Xo
  90 .Ft int
  91 .Fn pthread_equal "pthread_t t1" "pthread_t t2"
  92 .Xc
  93 Compares two thread IDs.
  94 .It Xo
  95 .Ft void
  96 .Fn pthread_exit "void *value_ptr"
  97 .Xc
  98 Terminates the calling thread.
  99 .It Xo
 100 .Ft int
 101 .Fn pthread_join "pthread_t thread" "void **value_ptr"
 102 .Xc
 103 Causes the calling thread to wait for the termination of the specified thread.
 104 .It Xo
 105 .Ft int
 106 .Fn pthread_kill "pthread_t thread" "int sig"
 107 .Xc
 108 Delivers a signal to a specified thread.
 109 .It Xo
 110 .Ft int
 111 .Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]"
 112 .Xc
 113 Calls an initialization routine once.
 114 .It Xo
 115 .Ft pthread_t
 116 .Fn pthread_self void
 117 .Xc
 118 Returns the thread ID of the calling thread.
 119 .It Xo
 120 .Ft int
 121 .Fn pthread_setcancelstate "int state" "int *oldstate"
 122 .Xc
 123 Sets the current thread's cancelability state.
 124 .It Xo
 125 .Ft int
 126 .Fn pthread_setcanceltype "int type" "int *oldtype"
 127 .Xc
 128 Sets the current thread's cancelability type.
 129 .It Xo
 130 .Ft void
 131 .Fn pthread_testcancel void
 132 .Xc
 133 Creates a cancellation point in the calling thread.
 134 .El
 135 .Ss Attribute Object Routines
 136 .Bl -tag -width indent
 137 .It Xo
 138 .Ft int
 139 .Fn pthread_attr_destroy "pthread_attr_t *attr"
 140 .Xc
 141 Destroy a thread attributes object.
 142 .It Xo
 143 .Ft int
 144 .Fo pthread_attr_getinheritsched
 145 .Fa "const pthread_attr_t *attr" "int *inheritsched"
 146 .Fc
 147 .Xc
 148 Get the inherit scheduling attribute from a thread attributes object.
 149 .It Xo
 150 .Ft int
 151 .Fo pthread_attr_getschedparam
 152 .Fa "const pthread_attr_t *attr" "struct sched_param *param"
 153 .Fc
 154 .Xc
 155 Get the scheduling parameter attribute from a thread attributes object.
 156 .It Xo
 157 .Ft int
 158 .Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
 159 .Xc
 160 Get the scheduling policy attribute from a thread attributes object.
 161 .It Xo
 162 .Ft int
 163 .Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
 164 .Xc
 165 Get the contention scope attribute from a thread attributes object.
 166 .It Xo
 167 .Ft int
 168 .Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
 169 .Xc
 170 Get the stack size attribute from a thread attributes object.
 171 .It Xo
 172 .Ft int
 173 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
 174 .Xc
 175 Get the stack address attribute from a thread attributes object.
 176 .It Xo
 177 .Ft int
 178 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
 179 .Xc
 180 Get the detach state attribute from a thread attributes object.
 181 .It Xo
 182 .Ft int
 183 .Fn pthread_attr_init "pthread_attr_t *attr"
 184 .Xc
 185 Initialize a thread attributes object with default values.
 186 .It Xo
 187 .Ft int
 188 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 189 .Xc
 190 Set the inherit scheduling attribute in a thread attributes object.
 191 .It Xo
 192 .Ft int
 193 .Fo pthread_attr_setschedparam
 194 .Fa "pthread_attr_t *attr" "const struct sched_param *param"
 195 .Fc
 196 .Xc
 197 Set the scheduling parameter attribute in a thread attributes object.
 198 .It Xo
 199 .Ft int
 200 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 201 .Xc
 202 Set the scheduling policy attribute in a thread attributes object.
 203 .It Xo
 204 .Ft int
 205 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 206 .Xc
 207 Set the contention scope attribute in a thread attributes object.
 208 .It Xo
 209 .Ft int
 210 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
 211 .Xc
 212 Set the stack size attribute in a thread attributes object.
 213 .It Xo
 214 .Ft int
 215 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
 216 .Xc
 217 Set the stack address attribute in a thread attributes object.
 218 .It Xo
 219 .Ft int
 220 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 221 .Xc
 222 Set the detach state in a thread attributes object.
 223 .El
 224 .Ss Mutex Routines
 225 .Bl -tag -width indent
 226 .It Xo
 227 .Ft int
 228 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
 229 .Xc
 230 Destroy a mutex attributes object.
 231 .It Xo
 232 .Ft int
 233 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling"
 234 .Xc
 235 Obtain priority ceiling attribute of mutex attribute object.
 236 .It Xo
 237 .Ft int
 238 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
 239 .Xc
 240 Obtain protocol attribute of mutex attribute object.
 241 .It Xo
 242 .Ft int
 243 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
 244 .Xc
 245 Obtain the mutex type attribute in the specified mutex attributes object.
 246 .It Xo
 247 .Ft int
 248 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
 249 .Xc
 250 Initialize a mutex attributes object with default values.
 251 .It Xo
 252 .Ft int
 253 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
 254 .Xc
 255 Set priority ceiling attribute of mutex attribute object.
 256 .It Xo
 257 .Ft int
 258 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
 259 .Xc
 260 Set protocol attribute of mutex attribute object.
 261 .It Xo
 262 .Ft int
 263 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
 264 .Xc
 265 Set the mutex type attribute that is used when a mutex is created.
 266 .It Xo
 267 .Ft int
 268 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
 269 .Xc
 270 Destroy a mutex.
 271 .It Xo
 272 .Ft int
 273 .Fo pthread_mutex_init
 274 .Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
 275 .Fc
 276 .Xc
 277 Initialize a mutex with specified attributes.
 278 .It Xo
 279 .Ft int
 280 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
 281 .Xc
 282 Lock a mutex and block until it becomes available.
 283 .It Xo
 284 .Ft int
 285 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 286 .Xc
 287 Try to lock a mutex, but do not block if the mutex is locked by another thread,
 288 including the current thread.
 289 .It Xo
 290 .Ft int
 291 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
 292 .Xc
 293 Unlock a mutex.
 294 .El
 295 .Ss Condition Variable Routines
 296 .Bl -tag -width indent
 297 .It Xo
 298 .Ft int
 299 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
 300 .Xc
 301 Destroy a condition variable attributes object.
 302 .It Xo
 303 .Ft int
 304 .Fn pthread_condattr_init "pthread_condattr_t *attr"
 305 .Xc
 306 Initialize a condition variable attributes object with default values.
 307 .It Xo
 308 .Ft int
 309 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
 310 .Xc
 311 Unblock all threads currently blocked on the specified condition variable.
 312 .It Xo
 313 .Ft int
 314 .Fn pthread_cond_destroy "pthread_cond_t *cond"
 315 .Xc
 316 Destroy a condition variable.
 317 .It Xo
 318 .Ft int
 319 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
 320 .Xc
 321 Initialize a condition variable with specified attributes.
 322 .It Xo
 323 .Ft int
 324 .Fn pthread_cond_signal "pthread_cond_t *cond"
 325 .Xc
 326 Unblock at least one of the threads blocked on the specified condition variable.
 327 .It Xo
 328 .Ft int
 329 .Fo pthread_cond_timedwait
 330 .Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex"
 331 .Fa "const struct timespec *abstime"
 332 .Fc
 333 .Xc
 334 Unlock the specified mutex, wait no longer than the specified time for
 335 a condition, and then relock the mutex.
 336 .It Xo
 337 .Ft int
 338 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
 339 .Xc
 340 Unlock the specified mutex, wait for a condition, and relock the mutex.
 341 .El
 342 .Ss Read/Write Lock Routines
 343 .Bl -tag -width indent
 344 .It Xo
 345 .Ft int
 346 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 347 .Xc
 348 Destroy a read/write lock object.
 349 .It Xo
 350 .Ft int
 351 .Fo pthread_rwlock_init
 352 .Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
 353 .Fc
 354 .Xc
 355 Initialize a read/write lock object.
 356 .It Xo
 357 .Ft int
 358 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 359 .Xc
 360 Lock a read/write lock for reading, blocking until the lock can be
 361 acquired.
 362 .It Xo
 363 .Ft int
 364 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 365 .Xc
 366 Attempt to lock a read/write lock for reading, without blocking if the
 367 lock is unavailable.
 368 .It Xo
 369 .Ft int
 370 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 371 .Xc
 372 Attempt to lock a read/write lock for writing, without blocking if the
 373 lock is unavailable.
 374 .It Xo
 375 .Ft int
 376 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 377 .Xc
 378 Unlock a read/write lock.
 379 .It Xo
 380 .Ft int
 381 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 382 .Xc
 383 Lock a read/write lock for writing, blocking until the lock can be
 384 acquired.
 385 .It Xo
 386 .Ft int
 387 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 388 .Xc
 389 Destroy a read/write lock attribute object.
 390 .It Xo
 391 .Ft int
 392 .Fo pthread_rwlockattr_getpshared
 393 .Fa "const pthread_rwlockattr_t *attr" "int *pshared"
 394 .Fc
 395 .Xc
 396 Retrieve the process shared setting for the read/write lock attribute
 397 object.
 398 .It Xo
 399 .Ft int
 400 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 401 .Xc
 402 Initialize a read/write lock attribute object.
 403 .It Xo
 404 .Ft int
 405 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
 406 .Xc
 407 Set the process shared setting for the read/write lock attribute object.
 408 .El
 409 .Ss Per-Thread Context Routines
 410 .Bl -tag -width indent
 411 .It Xo
 412 .Ft int
 413 .Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]"
 414 .Xc
 415 Create a thread-specific data key.
 416 .It Xo
 417 .Ft int
 418 .Fn pthread_key_delete "pthread_key_t key"
 419 .Xc
 420 Delete a thread-specific data key.
 421 .It Xo
 422 .Ft "void *"
 423 .Fn pthread_getspecific "pthread_key_t key"
 424 .Xc
 425 Get the thread-specific value for the specified key.
 426 .It Xo
 427 .Ft int
 428 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 429 .Xc
 430 Set the thread-specific value for the specified key.
 431 .El
 432 .Ss Cleanup Routines
 433 .Bl -tag -width indent
 434 .It Xo
 435 .Ft int
 436 .Fo pthread_atfork
 437 .Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]"
 438 .Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]"
 439 .Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]"
 440 .Fc
 441 .Xc
 442 Register fork handlers.
 443 .It Xo
 444 .Ft void
 445 .Fn pthread_cleanup_pop "int execute"
 446 .Xc
 447 Remove the routine at the top of the calling thread's cancellation cleanup
 448 stack and optionally invoke it.
 449 .It Xo
 450 .Ft void
 451 .Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg"
 452 .Xc
 453 Push the specified cancellation cleanup handler onto the calling thread's
 454 cancellation stack.
 455 .El
 456 .Sh INSTALLATION
 457 The default system libraries include
 458 .Nm pthread
 459 functions.
 460 No additional libraries or CFLAGS are necessary to use these interfaces.
 461 .Sh SEE ALSO
 462 .Xr pthread_atfork 3 ,
 463 .Xr pthread_attr 3 ,
 464 .Xr pthread_cancel 3 ,
 465 .Xr pthread_cleanup_pop 3 ,
 466 .Xr pthread_cleanup_push 3 ,
 467 .Xr pthread_cond_broadcast 3 ,
 468 .Xr pthread_cond_destroy 3 ,
 469 .Xr pthread_cond_init 3 ,
 470 .Xr pthread_cond_signal 3 ,
 471 .Xr pthread_cond_timedwait 3 ,
 472 .Xr pthread_cond_wait 3 ,
 473 .Xr pthread_condattr 3 ,
 474 .Xr pthread_condattr_destroy 3 ,
 475 .Xr pthread_condattr_init 3 ,
 476 .Xr pthread_create 3 ,
 477 .Xr pthread_detach 3 ,
 478 .Xr pthread_equal 3 ,
 479 .Xr pthread_exit 3 ,
 480 .Xr pthread_getschedparam 3 ,
 481 .Xr pthread_getspecific 3 ,
 482 .Xr pthread_join 3 ,
 483 .Xr pthread_key_create 3 ,
 484 .Xr pthread_key_delete 3 ,
 485 .Xr pthread_kill 3 ,
 486 .Xr pthread_mutex_destroy 3 ,
 487 .Xr pthread_mutex_init 3 ,
 488 .Xr pthread_mutex_lock 3 ,
 489 .Xr pthread_mutex_trylock 3 ,
 490 .Xr pthread_mutex_unlock 3 ,
 491 .Xr pthread_mutexattr 3 ,
 492 .Xr pthread_mutexattr_destroy 3 ,
 493 .Xr pthread_mutexattr_getprioceiling 3 ,
 494 .Xr pthread_mutexattr_getprotocol 3 ,
 495 .Xr pthread_mutexattr_gettype 3 ,
 496 .Xr pthread_mutexattr_init 3 ,
 497 .Xr pthread_mutexattr_setprioceiling 3 ,
 498 .Xr pthread_mutexattr_setprotocol 3 ,
 499 .Xr pthread_mutexattr_settype 3 ,
 500 .Xr pthread_once 3 ,
 501 .Xr pthread_rwlock_destroy 3 ,
 502 .Xr pthread_rwlock_init 3 ,
 503 .Xr pthread_rwlock_rdlock 3 ,
 504 .Xr pthread_rwlock_tryrdlock 3 ,
 505 .Xr pthread_rwlock_trywrlock 3 ,
 506 .Xr pthread_rwlock_unlock 3 ,
 507 .Xr pthread_rwlock_wrlock 3 ,
 508 .Xr pthread_rwlockattr_destroy 3 ,
 509 .Xr pthread_rwlockattr_getpshared 3 ,
 510 .Xr pthread_rwlockattr_init 3 ,
 511 .Xr pthread_rwlockattr_setpshared 3 ,
 512 .Xr pthread_self 3 ,
 513 .Xr pthread_setcancelstate 3 ,
 514 .Xr pthread_setcanceltype 3 ,
 515 .Xr pthread_setspecific 3 ,
 516 .Xr pthread_testcancel 3
 517 .Sh STANDARDS
 518 The functions with the
 519 .Nm pthread_
 520 prefix and not
 521 .Nm _np
 522 suffix or
 523 .Nm pthread_rwlock
 524 prefix conform to
 525 .St -p1003.1-96 .
 526 .Pp
 527 The functions with the
 528 .Nm pthread_
 529 prefix and
 530 .Nm _np
 531 suffix are non-portable extensions to POSIX threads.
 532 .Pp
 533 The functions with the
 534 .Nm pthread_rwlock
 535 prefix are extensions created by The Open Group as part of the
 536 .St -susv2 .