pthreads/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 Wait no longer than the specified time for a condition and lock the specified mutex.
 276 .It Xo
 277 .Ft int
 278 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
 279 .Xc
 280 Wait for a condition and lock the specified mutex.
 281 .El
 282 .Sh READ/WRITE LOCK ROUTINES
 283 .Bl -tag -width Er
 284 .It Xo
 285 .Ft int
 286 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 287 .Xc
 288 Destroy a read/write lock object.
 289 .It Xo
 290 .Ft int
 291 .Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
 292 .Xc
 293 Initialize a read/write lock object.
 294 .It Xo
 295 .Ft int
 296 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 297 .Xc
 298 Lock a read/write lock for reading, blocking until the lock can be
 299 acquired.
 300 .It Xo
 301 .Ft int
 302 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 303 .Xc
 304 Attempt to lock a read/write lock for reading, without blocking if the
 305 lock is unavailable.
 306 .It Xo
 307 .Ft int
 308 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 309 .Xc
 310 Attempt to lock a read/write lock for writing, without blocking if the
 311 lock is unavailable.
 312 .It Xo
 313 .Ft int
 314 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 315 .Xc
 316 Unlock a read/write lock.
 317 .It Xo
 318 .Ft int
 319 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 320 .Xc
 321 Lock a read/write lock for writing, blocking until the lock can be
 322 acquired.
 323 .It Xo
 324 .Ft int
 325 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 326 .Xc
 327 Destroy a read/write lock attribute object.
 328 .It Xo
 329 .Ft int
 330 .Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared"
 331 .Xc
 332 Retrieve the process shared setting for the read/write lock attribute
 333 object.
 334 .It Xo
 335 .Ft int
 336 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 337 .Xc
 338 Initialize a read/write lock attribute object.
 339 .It Xo
 340 .Ft int
 341 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
 342 .Xc
 343 Set the process shared setting for the read/write lock attribute object.
 344 .El
 345 .Sh PER-THREAD CONTEXT ROUTINES
 346 .Bl -tag -width Er
 347 .It Xo
 348 .Ft int
 349 .Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
 350 .Xc
 351 Create a thread-specific data key.
 352 .It Xo
 353 .Ft int
 354 .Fn pthread_key_delete "pthread_key_t key"
 355 .Xc
 356 Delete a thread-specific data key.
 357 .It Xo
 358 .Ft "void *"
 359 .Fn pthread_getspecific "pthread_key_t key"
 360 .Xc
 361 Get the thread-specific value for the specified key.
 362 .It Xo
 363 .Ft int
 364 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 365 .Xc
 366 Set the thread-specific value for the specified key.
 367 .El
 368 .Sh CLEANUP ROUTINES
 369 .Bl -tag -width Er
 370 .It Xo
 371 .Ft void
 372 .Fn pthread_cleanup_pop "int execute"
 373 .Xc
 374 Remove the routine at the top of the calling thread's cancellation cleanup
 375 stack and optionally invoke it.
 376 .It Xo
 377 .Ft void
 378 .Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
 379 .Xc
 380 Push the specified cancellation cleanup handler onto the calling thread's
 381 cancellation stack.
 382 .El
 383 .Sh INSTALLATION
 384 The default system libraries include
 385 .Nm pthread
 386 functions.
 387 No additional libraries or CFLAGS are necessary to use this API.
 388 .Sh SEE ALSO
 389 .Xr pthread_cleanup_pop 3 ,
 390 .Xr pthread_cleanup_push 3 ,
 391 .Xr pthread_cond_broadcast 3 ,
 392 .Xr pthread_cond_destroy 3 ,
 393 .Xr pthread_cond_init 3 ,
 394 .Xr pthread_cond_signal 3 ,
 395 .Xr pthread_cond_timedwait 3 ,
 396 .Xr pthread_cond_wait 3 ,
 397 .Xr pthread_create 3 ,
 398 .Xr pthread_detach 3 ,
 399 .Xr pthread_equal 3 ,
 400 .Xr pthread_exit 3 ,
 401 .Xr pthread_getspecific 3 ,
 402 .Xr pthread_join 3 ,
 403 .Xr pthread_key_delete 3 ,
 404 .Xr pthread_mutex_destroy 3 ,
 405 .Xr pthread_mutex_init 3 ,
 406 .Xr pthread_mutex_lock 3 ,
 407 .Xr pthread_mutex_trylock 3 ,
 408 .Xr pthread_mutex_unlock 3 ,
 409 .Xr pthread_once 3 ,
 410 .Xr pthread_rwlock_destroy 3 ,
 411 .Xr pthread_rwlock_init 3 ,
 412 .Xr pthread_rwlock_rdlock 3 ,
 413 .Xr pthread_rwlock_unlock 3 ,
 414 .Xr pthread_rwlock_wrlock 3 ,
 415 .Xr pthread_rwlockattr_destroy 3 ,
 416 .Xr pthread_rwlockattr_getpshared 3 ,
 417 .Xr pthread_rwlockattr_init 3 ,
 418 .Xr pthread_rwlockattr_setpshared 3 ,
 419 .Xr pthread_self 3 ,
 420 .Xr pthread_setspecific 3
 421 .Sh STANDARDS
 422 The functions in
 423 .Fa libc
 424 with the
 425 .Fa pthread_
 426 prefix and not
 427 .Fa _np
 428 suffix or
 429 .Fa pthread_rwlock
 430 prefix conform to
 431 .St -p1003.1-96 .
 432 .Pp
 433 The functions in libc with the
 434 .Fa pthread_
 435 prefix and
 436 .Fa _np
 437 suffix are non-portable extensions to POSIX threads.
 438 .Pp
 439 The functions in libc with the
 440 .Fa pthread_rwlock
 441 prefix are extensions created by The Open Group as part of the
 442 .St -susv2 .