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