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