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