1 .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
31 .\" $FreeBSD: src/share/man/man3/pthread.3,v 1.33 2009/04/01 08:08:25 trhodes Exp $
38 .Nd POSIX thread functions
44 POSIX threads are a set of functions that support applications with
45 requirements for multiple flows of control, called
48 Multithreading is used to improve the performance of a
51 The POSIX thread functions are summarized in this section in the following
54 .Bl -bullet -offset indent -compact
58 Attribute Object Routines
62 Condition Variable Routines
64 Read/Write Lock Routines
68 Per-Thread Context Routines
73 .Bl -tag -width indent
77 .Fa "pthread_t *thread" "const pthread_attr_t *attr"
78 .Fa "void *(*start_routine)(void *)" "void *arg"
81 Creates a new thread of execution.
84 .Fn pthread_cancel "pthread_t thread"
86 Cancels execution of a thread.
89 .Fn pthread_detach "pthread_t thread"
91 Marks a thread for deletion.
94 .Fn pthread_equal "pthread_t t1" "pthread_t t2"
96 Compares two thread IDs.
99 .Fn pthread_exit "void *value_ptr"
101 Terminates the calling thread.
104 .Fn pthread_join "pthread_t thread" "void **value_ptr"
106 Causes the calling thread to wait for the termination of the specified thread.
109 .Fn pthread_kill "pthread_t thread" "int sig"
111 Delivers a signal to a specified thread.
114 .Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
116 Calls an initialization routine once.
119 .Fn pthread_self void
121 Returns the thread ID of the calling thread.
124 .Fn pthread_setcancelstate "int state" "int *oldstate"
126 Sets the current thread's cancelability state.
129 .Fn pthread_setcanceltype "int type" "int *oldtype"
131 Sets the current thread's cancelability type.
134 .Fn pthread_testcancel void
136 Creates a cancellation point in the calling thread.
139 .Fn pthread_yield void
141 Allows the scheduler to run another thread instead of the current one.
143 .Ss Attribute Object Routines
144 .Bl -tag -width indent
147 .Fn pthread_attr_destroy "pthread_attr_t *attr"
149 Destroy a thread attributes object.
152 .Fo pthread_attr_getinheritsched
153 .Fa "const pthread_attr_t *attr" "int *inheritsched"
156 Get the inherit scheduling attribute from a thread attributes object.
159 .Fo pthread_attr_getschedparam
160 .Fa "const pthread_attr_t *attr" "struct sched_param *param"
163 Get the scheduling parameter attribute from a thread attributes object.
166 .Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
168 Get the scheduling policy attribute from a thread attributes object.
171 .Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
173 Get the contention scope attribute from a thread attributes object.
176 .Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
178 Get the stack size attribute from a thread attributes object.
181 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
183 Get the stack address attribute from a thread attributes object.
186 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
188 Get the detach state attribute from a thread attributes object.
191 .Fn pthread_attr_init "pthread_attr_t *attr"
193 Initialize a thread attributes object with default values.
196 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
198 Set the inherit scheduling attribute in a thread attributes object.
201 .Fo pthread_attr_setschedparam
202 .Fa "pthread_attr_t *attr" "const struct sched_param *param"
205 Set the scheduling parameter attribute in a thread attributes object.
208 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
210 Set the scheduling policy attribute in a thread attributes object.
213 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
215 Set the contention scope attribute in a thread attributes object.
218 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
220 Set the stack size attribute in a thread attributes object.
223 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
225 Set the stack address attribute in a thread attributes object.
228 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
230 Set the detach state in a thread attributes object.
233 .Bl -tag -width indent
236 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
238 Destroy a mutex attributes object.
241 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling"
243 Obtain priority ceiling attribute of mutex attribute object.
246 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
248 Obtain protocol attribute of mutex attribute object.
251 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
253 Obtain the mutex type attribute in the specified mutex attributes object.
256 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
258 Initialize a mutex attributes object with default values.
261 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
263 Set priority ceiling attribute of mutex attribute object.
266 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
268 Set protocol attribute of mutex attribute object.
271 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
273 Set the mutex type attribute that is used when a mutex is created.
276 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
281 .Fo pthread_mutex_init
282 .Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
285 Initialize a mutex with specified attributes.
288 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
290 Lock a mutex and block until it becomes available.
293 .Fo pthread_mutex_timedlock
294 .Fa "pthread_mutex_t *mutex" "const struct timespec *abstime"
297 Lock a mutex and block until it becomes available or until the timeout expires.
300 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
302 Try to lock a mutex, but do not block if the mutex is locked by another thread,
303 including the current thread.
306 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
310 .Ss Condition Variable Routines
311 .Bl -tag -width indent
314 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
316 Destroy a condition variable attributes object.
319 .Fn pthread_condattr_init "pthread_condattr_t *attr"
321 Initialize a condition variable attributes object with default values.
324 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
326 Unblock all threads currently blocked on the specified condition variable.
329 .Fn pthread_cond_destroy "pthread_cond_t *cond"
331 Destroy a condition variable.
334 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
336 Initialize a condition variable with specified attributes.
339 .Fn pthread_cond_signal "pthread_cond_t *cond"
341 Unblock at least one of the threads blocked on the specified condition variable.
344 .Fo pthread_cond_timedwait
345 .Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex"
346 .Fa "const struct timespec *abstime"
349 Wait no longer than the specified time for a condition
350 and lock the specified mutex.
353 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
355 Wait for a condition and lock the specified mutex.
357 .Ss Read/Write Lock Routines
358 .Bl -tag -width indent
361 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
363 Destroy a read/write lock object.
366 .Fo pthread_rwlock_init
367 .Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
370 Initialize a read/write lock object.
373 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
375 Lock a read/write lock for reading, blocking until the lock can be
379 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
381 Attempt to lock a read/write lock for reading, without blocking if the
385 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
387 Attempt to lock a read/write lock for writing, without blocking if the
391 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
393 Unlock a read/write lock.
396 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
398 Lock a read/write lock for writing, blocking until the lock can be
402 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
404 Destroy a read/write lock attribute object.
407 .Fo pthread_rwlockattr_getpshared
408 .Fa "const pthread_rwlockattr_t *attr" "int *pshared"
411 Retrieve the process shared setting for the read/write lock attribute
415 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
417 Initialize a read/write lock attribute object.
420 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
422 Set the process shared setting for the read/write lock attribute object.
425 .Bl -tag -width indent
428 .Fn pthread_barrier_destroy "pthread_barrier_t *barrier"
430 Delete a barrier and its resources.
433 .Fn pthread_barrier_init "pthread_barrier_t *barrier" "const pthread_barrierattr_t *attr" "unsigned count"
435 Initialize a barrier with the specified attribute object.
438 .Fn pthread_barrier_wait "pthread_barrier_t *barrier"
440 Block the calling threads until the barrier count is reached.
443 .Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr"
445 Destroy a barrier attribute object.
448 .Fn pthread_barrierattr_getpshared "const pthread_barrierattr_t *attr" "int *pshared"
450 Get the process-shared attribute from a barrier attribute object.
453 .Fn pthread_barrierattr_init "pthread_barrierattr_t *attr"
455 Initialize a barrier attribute object.
458 .Fn pthread_barrierattr_setpshared "pthread_barrierattr_t *attr" "int pshared"
460 Set the process-shared attribute in a barrier attribute object.
462 .Ss Per-Thread Context Routines
463 .Bl -tag -width indent
466 .Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
468 Create a thread-specific data key.
471 .Fn pthread_key_delete "pthread_key_t key"
473 Delete a thread-specific data key.
476 .Fn pthread_getspecific "pthread_key_t key"
478 Get the thread-specific value for the specified key.
481 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
483 Set the thread-specific value for the specified key.
486 .Bl -tag -width indent
490 .Fa "void (*prepare)(void)"
491 .Fa "void (*parent)(void)"
492 .Fa "void (*child)(void)"
495 Register fork handlers
498 .Fn pthread_cleanup_pop "int execute"
500 Remove the routine at the top of the calling thread's cancellation cleanup
501 stack and optionally invoke it.
504 .Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
506 Push the specified cancellation cleanup handler onto the calling thread's
509 .Sh IMPLEMENTATION NOTES
512 POSIX thread implementation is built in the library
514 which contains both thread-safe libc functions and the thread functions.
515 Another thread library,
517 is available for testing purposes.
521 it is possible to switch the threading library used by dynamically linked
522 binaries at execution time by re-linking
523 .Pa /usr/lib/libpthread.so.x
524 to a different library in
525 .Pa /usr/lib/thread .
534 (or a higher major, if there were ABI changes).
537 is usually a symlink to
545 is installed, programs will still continue to use
547 and not follow the symlink
549 to the newer (and possibly incompatible)
553 is approximately the opposite:
555 is not a symlink but nevertheless has its
558 .Pa libpthread.so.0 .
559 .Pa libpthread.so.0 ,
560 however, is a symlink to the threading library of the user's choice.
561 The linker will use the default threading library which
563 is linked to, but the runtime linker will instead follow the symlink.
566 defines all pthread functions as weak symbols except for
568 (which is defined by libpthread.so.x to satisfy
572 will resolve all these references to the strong symbols from the thread
577 is built as part of a 'make buildworld'.
578 To disable the build of
580 you must supply the '-DNO_LIBC_R' option to
589 can be used to override the system's default threading library.
593 specific option exists in
595 to simplify the linking of threaded processes.
597 links a threaded process against
602 .Xr pthread_atfork 3 ,
603 .Xr pthread_barrierattr 3 ,
604 .Xr pthread_barrier_destroy 3 ,
605 .Xr pthread_cancel 3 ,
606 .Xr pthread_cleanup_pop 3 ,
607 .Xr pthread_cleanup_push 3 ,
608 .Xr pthread_condattr_destroy 3 ,
609 .Xr pthread_condattr_init 3 ,
610 .Xr pthread_cond_broadcast 3 ,
611 .Xr pthread_cond_destroy 3 ,
612 .Xr pthread_cond_init 3 ,
613 .Xr pthread_cond_signal 3 ,
614 .Xr pthread_cond_timedwait 3 ,
615 .Xr pthread_cond_wait 3 ,
616 .Xr pthread_create 3 ,
617 .Xr pthread_detach 3 ,
618 .Xr pthread_equal 3 ,
620 .Xr pthread_getspecific 3 ,
622 .Xr pthread_key_delete 3 ,
624 .Xr pthread_mutexattr_destroy 3 ,
625 .Xr pthread_mutexattr_getprioceiling 3 ,
626 .Xr pthread_mutexattr_getprotocol 3 ,
627 .Xr pthread_mutexattr_gettype 3 ,
628 .Xr pthread_mutexattr_init 3 ,
629 .Xr pthread_mutexattr_setprioceiling 3 ,
630 .Xr pthread_mutexattr_setprotocol 3 ,
631 .Xr pthread_mutexattr_settype 3 ,
632 .Xr pthread_mutex_destroy 3 ,
633 .Xr pthread_mutex_init 3 ,
634 .Xr pthread_mutex_lock 3 ,
635 .Xr pthread_mutex_trylock 3 ,
636 .Xr pthread_mutex_unlock 3 ,
638 .Xr pthread_rwlockattr_destroy 3 ,
639 .Xr pthread_rwlockattr_getpshared 3 ,
640 .Xr pthread_rwlockattr_init 3 ,
641 .Xr pthread_rwlockattr_setpshared 3 ,
642 .Xr pthread_rwlock_destroy 3 ,
643 .Xr pthread_rwlock_init 3 ,
644 .Xr pthread_rwlock_rdlock 3 ,
645 .Xr pthread_rwlock_unlock 3 ,
646 .Xr pthread_rwlock_wrlock 3 ,
648 .Xr pthread_setcancelstate 3 ,
649 .Xr pthread_setcanceltype 3 ,
650 .Xr pthread_setspecific 3 ,
651 .Xr pthread_testcancel 3
653 The functions with the
662 The functions with the
666 suffix are non-portable extensions to POSIX threads.
668 The functions with the
670 prefix are extensions created by The Open Group as part of the