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 .El
 111 .Sh ATTRIBUTE OBJECT ROUTINES
 112 .Bl -tag -width Er
 113 .It Xo
 114 .Ft int
 115 .Fn pthread_attr_destroy "pthread_attr_t *attr"
 116 .Xc
 117 Destroy a thread attributes object.
 118 .It Xo
 119 .Ft int
 120 .Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched"
 121 .Xc
 122 Get the inherit scheduling attribute from a thread attributes object.
 123 .It Xo
 124 .Ft int
 125 .Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param"
 126 .Xc
 127 Get the scheduling parameter attribute from a thread attributes object.
 128 .It Xo
 129 .Ft int
 130 .Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
 131 .Xc
 132 Get the scheduling policy attribute from a thread attributes object.
 133 .It Xo
 134 .Ft int
 135 .Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
 136 .Xc
 137 Get the contention scope attribute from a thread attributes object.
 138 .It Xo
 139 .Ft int
 140 .Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
 141 .Xc
 142 Get the stack size attribute from a thread attributes object.
 143 .It Xo
 144 .Ft int
 145 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
 146 .Xc
 147 Get the stack address attribute from a thread attributes object.
 148 .It Xo
 149 .Ft int
 150 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
 151 .Xc
 152 Get the detach state attribute from a thread attributes object.
 153 .It Xo
 154 .Ft int
 155 .Fn pthread_attr_init "pthread_attr_t *attr"
 156 .Xc
 157 Initialize a thread attributes object with default values.
 158 .It Xo
 159 .Ft int
 160 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 161 .Xc
 162 Set the inherit scheduling attribute in a thread attributes object.
 163 .It Xo
 164 .Ft int
 165 .Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
 166 .Xc
 167 Set the scheduling parameter attribute in a thread attributes object.
 168 .It Xo
 169 .Ft int
 170 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 171 .Xc
 172 Set the scheduling policy attribute in a thread attributes object.
 173 .It Xo
 174 .Ft int
 175 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 176 .Xc
 177 Set the contention scope attribute in a thread attributes object.
 178 .It Xo
 179 .Ft int
 180 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
 181 .Xc
 182 Set the stack size attribute in a thread attributes object.
 183 .It Xo
 184 .Ft int
 185 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
 186 .Xc
 187 Set the stack address attribute in a thread attributes object.
 188 .It Xo
 189 .Ft int
 190 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 191 .Xc
 192 Set the detach state in a thread attributes object.
 193 .El
 194 .Sh MUTEX ROUTINES
 195 .Bl -tag -width Er
 196 .It Xo
 197 .Ft int
 198 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
 199 .Xc
 200 Destroy a mutex attributes object.
 201 .It Xo
 202 .Ft int
 203 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
 204 .Xc
 205 Initialize a mutex attributes object with default values.
 206 .It Xo
 207 .Ft int
 208 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
 209 .Xc
 210 Destroy a mutex.
 211 .It Xo
 212 .Ft int
 213 .Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
 214 .Xc
 215 Initialize a mutex with specified attributes.
 216 .It Xo
 217 .Ft int
 218 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
 219 .Xc
 220 Lock a mutex and block until it becomes available.
 221 .It Xo
 222 .Ft int
 223 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 224 .Xc
 225 Try to lock a mutex, but don't block if the mutex is locked by another thread,
 226 including the current thread.
 227 .It Xo
 228 .Ft int
 229 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
 230 .Xc
 231 Unlock a mutex.
 232 .El
 233 .Sh CONDITION VARIABLE ROUTINES
 234 .Bl -tag -width Er
 235 .It Xo
 236 .Ft int
 237 .Fn pthread_condattr_init "pthread_condattr_t *attr"
 238 .Xc
 239 Initialize a condition variable attributes object with default values.
 240 .It Xo
 241 .Ft int
 242 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
 243 .Xc
 244 Destroy a condition variable attributes object.
 245 .It Xo
 246 .Ft int
 247 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
 248 .Xc
 249 Unblock all threads currently blocked on the specified condition variable.
 250 .It Xo
 251 .Ft int
 252 .Fn pthread_cond_destroy "pthread_cond_t *cond"
 253 .Xc
 254 Destroy a condition variable.
 255 .It Xo
 256 .Ft int
 257 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
 258 .Xc
 259 Initialize a condition variable with specified attributes.
 260 .It Xo
 261 .Ft int
 262 .Fn pthread_cond_signal "pthread_cond_t *cond"
 263 .Xc
 264 Unblock at least one of the threads blocked on the specified condition variable.
 265 .It Xo
 266 .Ft int
 267 .Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
 268 .Xc
 269 Wait no longer than the specified time for a condition and lock the specified mutex.
 270 .It Xo
 271 .Ft int
 272 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
 273 .Xc
 274 Wait for a condition and lock the specified mutex.
 275 .El
 276 .Sh READ/WRITE LOCK ROUTINES
 277 .Bl -tag -width Er
 278 .It Xo
 279 .Ft int
 280 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 281 .Xc
 282 Destroy a read/write lock object.
 283 .It Xo
 284 .Ft int
 285 .Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
 286 .Xc
 287 Initialize a read/write lock object.
 288 .It Xo
 289 .Ft int
 290 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 291 .Xc
 292 Lock a read/write lock for reading, blocking until the lock can be
 293 acquired.
 294 .It Xo
 295 .Ft int
 296 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 297 .Xc
 298 Attempt to lock a read/write lock for reading, without blocking if the
 299 lock is unavailable.
 300 .It Xo
 301 .Ft int
 302 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 303 .Xc
 304 Attempt to lock a read/write lock for writing, without blocking if the
 305 lock is unavailable.
 306 .It Xo
 307 .Ft int
 308 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 309 .Xc
 310 Unlock a read/write lock.
 311 .It Xo
 312 .Ft int
 313 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 314 .Xc
 315 Lock a read/write lock for writing, blocking until the lock can be
 316 acquired.
 317 .It Xo
 318 .Ft int
 319 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 320 .Xc
 321 Destroy a read/write lock attribute object.
 322 .It Xo
 323 .Ft int
 324 .Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared"
 325 .Xc
 326 Retrieve the process shared setting for the read/write lock attribute
 327 object.
 328 .It Xo
 329 .Ft int
 330 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 331 .Xc
 332 Initialize a read/write lock attribute object.
 333 .It Xo
 334 .Ft int
 335 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
 336 .Xc
 337 Set the process shared setting for the read/write lock attribute object.
 338 .El
 339 .Sh PER-THREAD CONTEXT ROUTINES
 340 .Bl -tag -width Er
 341 .It Xo
 342 .Ft int
 343 .Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
 344 .Xc
 345 Create a thread-specific data key.
 346 .It Xo
 347 .Ft int
 348 .Fn pthread_key_delete "pthread_key_t key"
 349 .Xc
 350 Delete a thread-specific data key.
 351 .It Xo
 352 .Ft "void *"
 353 .Fn pthread_getspecific "pthread_key_t key"
 354 .Xc
 355 Get the thread-specific value for the specified key.
 356 .It Xo
 357 .Ft int
 358 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 359 .Xc
 360 Set the thread-specific value for the specified key.
 361 .El
 362 .Sh CLEANUP ROUTINES
 363 .Bl -tag -width Er
 364 .It Xo
 365 .Ft void
 366 .Fn pthread_cleanup_pop "int execute"
 367 .Xc
 368 Remove the routine at the top of the calling thread's cancellation cleanup
 369 stack and optionally invoke it.
 370 .It Xo
 371 .Ft void
 372 .Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
 373 .Xc
 374 Push the specified cancellation cleanup handler onto the calling thread's
 375 cancellation stack.
 376 .El
 377 .Sh INSTALLATION
 378 The default system libraries include
 379 .Nm
 380 funcitons. No additional libraries or CFLAGS are necessary to use this API.
 381 .Sh SEE ALSO
 382 .Xr pthread_cleanup_pop 3 ,
 383 .Xr pthread_cleanup_push 3 ,
 384 .Xr pthread_cond_broadcast 3 ,
 385 .Xr pthread_cond_destroy 3 ,
 386 .Xr pthread_cond_init 3 ,
 387 .Xr pthread_cond_signal 3 ,
 388 .Xr pthread_cond_timedwait 3 ,
 389 .Xr pthread_cond_wait 3 ,
 390 .Xr pthread_create 3 ,
 391 .Xr pthread_detach 3 ,
 392 .Xr pthread_equal 3 ,
 393 .Xr pthread_exit 3 ,
 394 .Xr pthread_getspecific 3 ,
 395 .Xr pthread_join 3 ,
 396 .Xr pthread_key_delete 3 ,
 397 .Xr pthread_mutex_destroy 3 ,
 398 .Xr pthread_mutex_init 3 ,
 399 .Xr pthread_mutex_lock 3 ,
 400 .Xr pthread_mutex_trylock 3 ,
 401 .Xr pthread_mutex_unlock 3 ,
 402 .Xr pthread_once 3 ,
 403 .Xr pthread_rwlockattr_destroy 3 ,
 404 .Xr pthread_rwlockattr_getpshared 3 ,
 405 .Xr pthread_rwlockattr_init 3 ,
 406 .Xr pthread_rwlockattr_setpshared 3 ,
 407 .Xr pthread_rwlock_destroy 3 ,
 408 .Xr pthread_rwlock_init 3 ,
 409 .Xr pthread_rwlock_rdlock 3 ,
 410 .Xr pthread_rwlock_unlock 3 ,
 411 .Xr pthread_rwlock_wrlock 3 ,
 412 .Xr pthread_self 3 ,
 413 .Xr pthread_setspecific 3
 414 .Sh STANDARDS
 415 The functions in
 416 .Fa libc
 417 with the
 418 .Fa pthread_
 419 prefix and not
 420 .Fa _np
 421 suffix or
 422 .Fa pthread_rwlock
 423 prefix conform to
 424 .St -p1003.1-96 .
 425 .Pp
 426 The functions in libc with the
 427 .Fa pthread_
 428 prefix and
 429 .Fa _np
 430 suffix are non-portable extensions to POSIX threads.
 431 .Pp
 432 The functions in libc with the
 433 .Fa pthread_rwlock
 434 prefix are extensions created by The Open Group as part of the
 435 .St -susv2 .