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: src/share/man/man3/pthread.3,v 1.12.2.4 2001/08/17 13:08:36 ru Exp $
  33 .\"
  34 .Dd November 5, 2001
  35 .Dt PTHREAD 3
  36 .Os Darwin
  37 .Sh NAME
  38 .Nm pthread
  39 .Nd POSIX thread functions
  40 .Sh SYNOPSIS
  41 .Fd #include <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 .Fa 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 .Bl -bullet -offset indent
  53 .It
  54 Thread Routines
  55 .It
  56 Attribute Object Routines
  57 .It
  58 Mutex Routines
  59 .It
  60 Condition Variable Routines
  61 .It
  62 Read/Write Lock Routines
  63 .It
  64 Per-Thread Context Routines
  65 .It
  66 Cleanup Routines
  67 .El
  68 .Sh THREAD ROUTINES
  69 .Bl -tag -width Er
  70 .It Xo
  71 .Ft int
  72 .Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
  73 .Xc
  74 Creates a new thread of execution.
  75 .It Xo
  76 .Ft int
  77 .Fn pthread_detach "pthread_t thread"
  78 .Xc
  79 Marks a thread for deletion.
  80 .It Xo
  81 .Ft int
  82 .Fn pthread_equal "pthread_t t1" "pthread_t t2"
  83 .Xc
  84 Compares two thread IDs.
  85 .It Xo
  86 .Ft void
  87 .Fn pthread_exit "void *value_ptr"
  88 .Xc
  89 Terminates the calling thread.
  90 .It Xo
  91 .Ft int
  92 .Fn pthread_join "pthread_t thread" "void **value_ptr"
  93 .Xc
  94 Causes the calling thread to wait for the termination of the specified thread.
  95 .It Xo
  96 .Ft int
  97 .Fn pthread_cancel "pthread_t thread"
  98 .Xc
  99 Cancels execution of a thread.
 100 .It Xo
 101 .Ft int
 102 .Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
 103 .Xc
 104 Calls an initialization routine once.
 105 .It Xo
 106 .Ft pthread_t
 107 .Fn pthread_self void
 108 .Xc
 109 Returns the thread ID of the calling thread.
 110 .It Xo
 111 .Ft int
 112 .Fn pthread_atfork "void (*prepare)(void)" "void (*parent)(void)" "void (*child)(void)"
 113 .Xc
 114 Registers handlers to be called before and after
 115 .Fn fork
 116 .El
 117 .Sh ATTRIBUTE OBJECT ROUTINES
 118 .Bl -tag -width Er
 119 .It Xo
 120 .Ft int
 121 .Fn pthread_attr_destroy "pthread_attr_t *attr"
 122 .Xc
 123 Destroy a thread attributes object.
 124 .It Xo
 125 .Ft int
 126 .Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched"
 127 .Xc
 128 Get the inherit scheduling attribute from a thread attributes object.
 129 .It Xo
 130 .Ft int
 131 .Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param"
 132 .Xc
 133 Get the scheduling parameter attribute from a thread attributes object.
 134 .It Xo
 135 .Ft int
 136 .Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
 137 .Xc
 138 Get the scheduling policy attribute from a thread attributes object.
 139 .It Xo
 140 .Ft int
 141 .Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
 142 .Xc
 143 Get the contention scope attribute from a thread attributes object.
 144 .It Xo
 145 .Ft int
 146 .Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
 147 .Xc
 148 Get the stack size attribute from a thread attributes object.
 149 .It Xo
 150 .Ft int
 151 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
 152 .Xc
 153 Get the stack address attribute from a thread attributes object.
 154 .It Xo
 155 .Ft int
 156 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
 157 .Xc
 158 Get the detach state attribute from a thread attributes object.
 159 .It Xo
 160 .Ft int
 161 .Fn pthread_attr_init "pthread_attr_t *attr"
 162 .Xc
 163 Initialize a thread attributes object with default values.
 164 .It Xo
 165 .Ft int
 166 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 167 .Xc
 168 Set the inherit scheduling attribute in a thread attributes object.
 169 .It Xo
 170 .Ft int
 171 .Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
 172 .Xc
 173 Set the scheduling parameter attribute in a thread attributes object.
 174 .It Xo
 175 .Ft int
 176 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 177 .Xc
 178 Set the scheduling policy attribute in a thread attributes object.
 179 .It Xo
 180 .Ft int
 181 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 182 .Xc
 183 Set the contention scope attribute in a thread attributes object.
 184 .It Xo
 185 .Ft int
 186 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
 187 .Xc
 188 Set the stack size attribute in a thread attributes object.
 189 .It Xo
 190 .Ft int
 191 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
 192 .Xc
 193 Set the stack address attribute in a thread attributes object.
 194 .It Xo
 195 .Ft int
 196 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 197 .Xc
 198 Set the detach state in a thread attributes object.
 199 .El
 200 .Sh MUTEX ROUTINES
 201 .Bl -tag -width Er
 202 .It Xo
 203 .Ft int
 204 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
 205 .Xc
 206 Destroy a mutex attributes object.
 207 .It Xo
 208 .Ft int
 209 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
 210 .Xc
 211 Initialize a mutex attributes object with default values.
 212 .It Xo
 213 .Ft int
 214 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
 215 .Xc
 216 Destroy a mutex.
 217 .It Xo
 218 .Ft int
 219 .Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
 220 .Xc
 221 Initialize a mutex with specified attributes.
 222 .It Xo
 223 .Ft int
 224 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
 225 .Xc
 226 Lock a mutex and block until it becomes available.
 227 .It Xo
 228 .Ft int
 229 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 230 .Xc
 231 Try to lock a mutex, but don't block if the mutex is locked by another thread,
 232 including the current thread.
 233 .It Xo
 234 .Ft int
 235 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
 236 .Xc
 237 Unlock a mutex.
 238 .El
 239 .Sh CONDITION VARIABLE ROUTINES
 240 .Bl -tag -width Er
 241 .It Xo
 242 .Ft int
 243 .Fn pthread_condattr_init "pthread_condattr_t *attr"
 244 .Xc
 245 Initialize a condition variable attributes object with default values.
 246 .It Xo
 247 .Ft int
 248 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
 249 .Xc
 250 Destroy a condition variable attributes object.
 251 .It Xo
 252 .Ft int
 253 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
 254 .Xc
 255 Unblock all threads currently blocked on the specified condition variable.
 256 .It Xo
 257 .Ft int
 258 .Fn pthread_cond_destroy "pthread_cond_t *cond"
 259 .Xc
 260 Destroy a condition variable.
 261 .It Xo
 262 .Ft int
 263 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
 264 .Xc
 265 Initialize a condition variable with specified attributes.
 266 .It Xo
 267 .Ft int
 268 .Fn pthread_cond_signal "pthread_cond_t *cond"
 269 .Xc
 270 Unblock at least one of the threads blocked on the specified condition variable.
 271 .It Xo
 272 .Ft int
 273 .Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
 274 .Xc
 275 Atomically unlock the specified mutex and block on a condition
 276 or until the specified time passes.
 277 .It Xo
 278 .Ft int
 279 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
 280 .Xc
 281 Atomically unlock the specified mutex and block on a condition.
 282 .El
 283 .Sh READ/WRITE LOCK ROUTINES
 284 .Bl -tag -width Er
 285 .It Xo
 286 .Ft int
 287 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 288 .Xc
 289 Destroy a read/write lock object.
 290 .It Xo
 291 .Ft int
 292 .Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
 293 .Xc
 294 Initialize a read/write lock object.
 295 .It Xo
 296 .Ft int
 297 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 298 .Xc
 299 Lock a read/write lock for reading, blocking until the lock can be
 300 acquired.
 301 .It Xo
 302 .Ft int
 303 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 304 .Xc
 305 Attempt to lock a read/write lock for reading, without blocking if the
 306 lock is unavailable.
 307 .It Xo
 308 .Ft int
 309 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 310 .Xc
 311 Attempt to lock a read/write lock for writing, without blocking if the
 312 lock is unavailable.
 313 .It Xo
 314 .Ft int
 315 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 316 .Xc
 317 Unlock a read/write lock.
 318 .It Xo
 319 .Ft int
 320 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 321 .Xc
 322 Lock a read/write lock for writing, blocking until the lock can be
 323 acquired.
 324 .It Xo
 325 .Ft int
 326 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 327 .Xc
 328 Destroy a read/write lock attribute object.
 329 .It Xo
 330 .Ft int
 331 .Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared"
 332 .Xc
 333 Retrieve the process shared setting for the read/write lock attribute
 334 object.
 335 .It Xo
 336 .Ft int
 337 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 338 .Xc
 339 Initialize a read/write lock attribute object.
 340 .It Xo
 341 .Ft int
 342 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
 343 .Xc
 344 Set the process shared setting for the read/write lock attribute object.
 345 .El
 346 .Sh PER-THREAD CONTEXT ROUTINES
 347 .Bl -tag -width Er
 348 .It Xo
 349 .Ft int
 350 .Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
 351 .Xc
 352 Create a thread-specific data key.
 353 .It Xo
 354 .Ft int
 355 .Fn pthread_key_delete "pthread_key_t key"
 356 .Xc
 357 Delete a thread-specific data key.
 358 .It Xo
 359 .Ft "void *"
 360 .Fn pthread_getspecific "pthread_key_t key"
 361 .Xc
 362 Get the thread-specific value for the specified key.
 363 .It Xo
 364 .Ft int
 365 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 366 .Xc
 367 Set the thread-specific value for the specified key.
 368 .El
 369 .Sh CLEANUP ROUTINES
 370 .Bl -tag -width Er
 371 .It Xo
 372 .Ft void
 373 .Fn pthread_cleanup_pop "int execute"
 374 .Xc
 375 Remove the routine at the top of the calling thread's cancellation cleanup
 376 stack and optionally invoke it.
 377 .It Xo
 378 .Ft void
 379 .Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
 380 .Xc
 381 Push the specified cancellation cleanup handler onto the calling thread's
 382 cancellation stack.
 383 .El
 384 .Sh INSTALLATION
 385 The default system libraries include
 386 .Nm pthread
 387 functions.
 388 No additional libraries or CFLAGS are necessary to use these interfaces.
 389 .Sh SEE ALSO
 390 .Xr pthread_atfork 3 ,
 391 .Xr pthread_attr 3 ,
 392 .Xr pthread_attr_init_destroy 3 ,
 393 .Xr pthread_attr_getdetachstate 3 ,
 394 .Xr pthread_attr_getinheritsched 3 ,
 395 .Xr pthread_attr_getschedparam 3 ,
 396 .Xr pthread_attr_getschedpolicy 3 ,
 397 .Xr pthread_attr_getscope 3 ,
 398 .Xr pthread_attr_getstackaddr 3 ,
 399 .Xr pthread_attr_getstacksize 3 ,
 400 .Xr pthread_attr_init 3 ,
 401 .Xr pthread_attr_init_destroy 3 ,
 402 .Xr pthread_attr_setdetachstate 3 ,
 403 .Xr pthread_attr_setinheritsched 3 ,
 404 .Xr pthread_attr_setschedparam 3 ,
 405 .Xr pthread_attr_setschedpolicy 3 ,
 406 .Xr pthread_attr_setscope 3 ,
 407 .Xr pthread_attr_setstackaddr 3 ,
 408 .Xr pthread_attr_setstacksize 3 ,
 409 .Xr pthread_cancel 3 ,
 410 .Xr pthread_cleanup_pop 3 ,
 411 .Xr pthread_cleanup_push 3 ,
 412 .Xr pthread_cond_broadcast 3 ,
 413 .Xr pthread_cond_destroy 3 ,
 414 .Xr pthread_cond_init 3 ,
 415 .Xr pthread_cond_signal 3 ,
 416 .Xr pthread_cond_timedwait 3 ,
 417 .Xr pthread_cond_wait 3 ,
 418 .Xr pthread_condattr 3 ,
 419 .Xr pthread_condattr_destroy 3 ,
 420 .Xr pthread_condattr_init 3 ,
 421 .Xr pthread_create 3 ,
 422 .Xr pthread_detach 3 ,
 423 .Xr pthread_equal 3 ,
 424 .Xr pthread_exit 3 ,
 425 .Xr pthread_getschedparam 3 ,
 426 .Xr pthread_getspecific 3 ,
 427 .Xr pthread_join 3 ,
 428 .Xr pthread_key_create 3 ,
 429 .Xr pthread_key_delete 3 ,
 430 .Xr pthread_mutex_destroy 3 ,
 431 .Xr pthread_mutex_init 3 ,
 432 .Xr pthread_mutex_lock 3 ,
 433 .Xr pthread_mutex_trylock 3 ,
 434 .Xr pthread_mutex_unlock 3 ,
 435 .Xr pthread_mutexattr 3 ,
 436 .Xr pthread_mutexattr_destroy 3 ,
 437 .Xr pthread_mutexattr_getprioceiling 3 ,
 438 .Xr pthread_mutexattr_getprotocol 3 ,
 439 .Xr pthread_mutexattr_gettype 3 ,
 440 .Xr pthread_mutexattr_init 3 ,
 441 .Xr pthread_mutexattr_setprioceiling 3 ,
 442 .Xr pthread_mutexattr_setprotocol 3 ,
 443 .Xr pthread_mutexattr_settype 3 ,
 444 .Xr pthread_once 3 ,
 445 .Xr pthread_rwlock_destroy 3 ,
 446 .Xr pthread_rwlock_init 3 ,
 447 .Xr pthread_rwlock_rdlock 3 ,
 448 .Xr pthread_rwlock_tryrdlock 3 ,
 449 .Xr pthread_rwlock_trywrlock 3 ,
 450 .Xr pthread_rwlock_unlock 3 ,
 451 .Xr pthread_rwlock_wrlock 3 ,
 452 .Xr pthread_rwlockattr_destroy 3 ,
 453 .Xr pthread_rwlockattr_getpshared 3 ,
 454 .Xr pthread_rwlockattr_init 3 ,
 455 .Xr pthread_rwlockattr_setpshared 3 ,
 456 .Xr pthread_self 3 ,
 457 .Xr pthread_setcancelstate 3
 458 .Xr pthread_setcanceltype 3
 459 .Xr pthread_setschedparam 3
 460 .Xr pthread_setspecific 3
 461 .Xr pthread_testcancel 3
 462 .Sh STANDARDS
 463 The functions with the
 464 .Fa pthread_
 465 prefix and not
 466 .Fa _np
 467 suffix or
 468 .Fa pthread_rwlock
 469 prefix conform to
 470 .St -p1003.1-96 .
 471 .Pp
 472 The functions with the
 473 .Fa pthread_
 474 prefix and
 475 .Fa _np
 476 suffix are non-portable extensions to POSIX threads.
 477 .Pp
 478 The functions with the
 479 .Fa pthread_rwlock
 480 prefix are extensions created by The Open Group as part of the
 481 .St -susv2 .