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$
  32 .\"
  33 .Dd September 10, 1998
  34 .Dt PTHREAD 3
  35 .Os BSD 4
  36 .Sh NAME
  37 .Nm pthread
  38 .Nd POSIX thread functions
  39 .Sh DESCRIPTION
  40 POSIX threads are a set of functions that support applications with
  41 requirements for multiple flows of control, called
  42 .Fa threads ,
  43 within a process. Multithreading is used to improve the performance of a
  44 program.
  45 .Pp
  46 The POSIX thread functions are summarized in this section in the following
  47 groups:
  48 .Bl -bullet -offset indent
  49 .It
  50 Thread Routines
  51 .It
  52 Attribute Object Routines
  53 .It
  54 Mutex Routines
  55 .It
  56 Condition Variable Routines
  57 .It
  58 Read/Write Lock Routines
  59 .It
  60 Per-Thread Context Routines
  61 .It
  62 Cleanup Routines
  63 .El
  64 .Sh THREAD ROUTINES
  65 .Bl -tag -width Er
  66 .It int Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
  67 Creates a new thread of execution.
  68 .It int Fn pthread_detach "pthread_t thread"
  69 Marks a thread for deletion.
  70 .It int Fn pthread_equal "pthread_t t1" "pthread_t t2"
  71 Compares two thread IDs.
  72 .It void Fn pthread_exit "void *value_ptr"
  73 Terminates the calling thread.
  74 .It int Fn pthread_join "pthread_t thread" "void **value_ptr"
  75 Causes the calling thread to wait for the termination of the specified thread.
  76 .It int Fn pthread_cancel "pthread_t thread"
  77 Cancels execution of a thread.
  78 .It int Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
  79 Calls an initialization routine once.
  80 .It pthread_t Fn pthread_self void
  81 Returns the thread ID of the calling thread.
  82 .El
  83 .Sh ATTRIBUTE OBJECT ROUTINES
  84 .Bl -tag -width Er
  85 .It int Fn pthread_attr_destroy "pthread_attr_t *attr"
  86 Destroy a thread attributes object.
  87 .It int Fn pthread_attr_getinheritsched "pthread_attr_t *attr" "int *inheritsched"
  88 Get the inherit scheduling attribute from a thread attributes object.
  89 .It int Fn pthread_attr_getschedparam "pthread_attr_t *attr" "struct sched_param *param"
  90 Get the scheduling parameter attribute from a thread attributes object.
  91 .It int Fn pthread_attr_getschedpolicy "pthread_attr_t *attr" "int *policy"
  92 Get the scheduling policy attribute from a thread attributes object.
  93 .It int Fn pthread_attr_getscope "pthread_attr_t *attr" "int *contentionscope"
  94 Get the contention scope attribute from a thread attributes object.
  95 .It int Fn pthread_attr_getstacksize "pthread_attr_t *attr" "size_t *stacksize"
  96 Get the stack size attribute from a thread attributes object.
  97 .It int Fn pthread_attr_getstackaddr "pthread_attr_t *attr" "void **stackaddr"
  98 Get the stack address attribute from a thread attributes object.
  99 .It int Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate"
 100 Get the detach state attribute from a thread attributes object.
 101 .It int Fn pthread_attr_init "pthread_attr_t *attr"
 102 Initialize a thread attributes object with default values.
 103 .It int Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 104 Set the inherit scheduling attribute in a thread attributes object.
 105 .It int Fn pthread_attr_setschedparam "pthread_attr_t *attr" "struct sched_param *param"
 106 Set the scheduling parameter attribute in a thread attributes object.
 107 .It int Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 108 Set the scheduling policy attribute in a thread attributes object.
 109 .It int Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 110 Set the contention scope attribute in a thread attributes object.
 111 .It int Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
 112 Set the stack size attribute in a thread attributes object.
 113 .It int Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
 114 Set the stack address attribute in a thread attributes object.
 115 .It int Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 116 Set the detach state in a thread attributes object.
 117 .El
 118 .Sh MUTEX ROUTINES
 119 .Bl -tag -width Er
 120 .It int Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
 121 Destroy a mutex attributes object.
 122 .It int Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
 123 Initialize a mutex attributes object with default values.
 124 .It int Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
 125 Destroy a mutex.
 126 .It int Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
 127 Initialize a mutex with specified attributes.
 128 .It int Fn pthread_mutex_lock "pthread_mutex_t *mutex"
 129 Lock a mutex and block until it becomes available.
 130 .It int Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 131 Try to lock a mutex, but don't block if the mutex is locked by another thread,
 132 including the current thread.
 133 .It int Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
 134 Unlock a mutex.
 135 .El
 136 .Sh CONDITION VARIABLE ROUTINES
 137 .Bl -tag -width Er
 138 .It int Fn pthread_condattr_init "pthread_condattr_t *attr"
 139 Initialize a condition variable attributes object with default values.
 140 .It int Fn pthread_condattr_destroy "pthread_condattr_t *attr"
 141 Destroy a condition variable attributes object.
 142 .It int Fn pthread_cond_broadcast "pthread_cond_t *cond"
 143 Unblock all threads currently blocked on the specified condition variable.
 144 .It int Fn pthread_cond_destroy "pthread_cond_t *cond"
 145 Destroy a condition variable.
 146 .It int Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
 147 Initialize a condition variable with specified attributes.
 148 .It int Fn pthread_cond_signal "pthread_cond_t *cond"
 149 Unblock at least one of the threads blocked on the specified condition variable.
 150 .It int Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
 151 Wait no longer than the specified time for a condition and lock the specified mutex.
 152 .It int Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
 153 Wait for a condition and lock the specified mutex.
 154 .El
 155 .Sh READ/WRITE LOCK ROUTINES
 156 .Bl -tag -width Er
 157 .It int Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
 158 Destroy a read/write lock object.
 159 .It int Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
 160 Initialize a read/write lock object.
 161 .It int Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 162 Lock a read/write lock for reading, blocking until the lock can be
 163 acquired.
 164 .It int Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 165 Attempt to lock a read/write lock for reading, without blocking if the
 166 lock is unavailable.
 167 .It int Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
 168 Attempt to lock a read/write lock for writing, without blocking if the
 169 lock is unavailable.
 170 .It int Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
 171 Unlock a read/write lock.
 172 .It int Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
 173 Lock a read/write lock for writing, blocking until the lock can be
 174 acquired.
 175 .It int Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
 176 Destroy a read/write lock attribute object.
 177 .It int Fn pthread_rwlockattr_getpshared "pthread_rwlockattr_t *attr" "int *pshared"
 178 Retrieve the process shared setting for the read/write lock attribute
 179 object.
 180 .It int Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
 181 Initialize a read/write lock attribute object.
 182 .It int Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int *pshared"
 183 Set the process shared setting for the read/write lock attribute object.
 184 .El
 185 .Sh PER-THREAD CONTEXT ROUTINES
 186 .Bl -tag -width Er
 187 .It int Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
 188 Create a thread-specific data key.
 189 .It int Fn pthread_key_delete "pthread_key_t key"
 190 Delete a thread-specific data key.
 191 .It void * Fn pthread_getspecific "pthread_key_t key" "void **value_ptr"
 192 Get the thread-specific value for the specified key.
 193 .It int Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
 194 Set the thread-specific value for the specified key.
 195 .El
 196 .Sh CLEANUP ROUTINES
 197 .Bl -tag -width Er
 198 .It void Fn pthread_cleanup_pop "int execute"
 199 Remove the routine at the top of the calling thread's cancellation cleanup
 200 stack and optionally invoke it.
 201 .It void Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
 202 Push the specified cancellation cleanup handler onto the calling thread's
 203 cancellation stack.
 204 .El
 205 .Sh INSTALLATION
 206 The current FreeBSD POSIX thread implementation is built in the library
 207 .Fa libc_r
 208 which contains both thread-safe libc functions and the thread functions.
 209 This library replaces
 210 .Fa libc
 211 for threaded applications.
 212 .Pp
 213 By default,
 214 .Fa libc_r
 215 is built as part of a 'make world'.  To disable the build of
 216 .Fa libc_r
 217 you must supply the '-DNOLIBC_R' option to
 218 .Xr make 1 .
 219 .Pp
 220 A FreeBSD specific option has been added to gcc to make linking
 221 threaded processes simple.
 222 .Fa gcc -pthread
 223 links a threaded process against
 224 .Fa libc_r
 225 instead of
 226 .Fa libc.
 227 .Sh STANDARDS
 228 The functions in
 229 .Fa libc_r
 230 with the
 231 .Fa pthread_
 232 prefix and not
 233 .Fa _np
 234 suffix or
 235 .Fa pthread_rwlock
 236 prefix conform to IEEE
 237 .Pq Dq Tn POSIX
 238 Std 1003.1 Second Edition 1996-07-12
 239 .Pp
 240 The functions in libc_r with the
 241 .Fa pthread_
 242 prefix and
 243 .Fa _np
 244 suffix are non-portable extensions to POSIX threads.
 245 .Pp
 246 The functions in libc_r with the
 247 .Fa pthread_rwlock
 248 prefix are extensions created by The Open Group as part of the Single
 249 UNIX Specification, Version 2.