250 lines
11 KiB
Groff
250 lines
11 KiB
Groff
.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by John Birrell.
|
|
.\" 4. Neither the name of the author nor the names of any co-contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 10, 1998
|
|
.Dt PTHREAD 3
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm pthread
|
|
.Nd POSIX thread functions
|
|
.Sh DESCRIPTION
|
|
POSIX threads are a set of functions that support applications with
|
|
requirements for multiple flows of control, called
|
|
.Fa threads ,
|
|
within a process. Multithreading is used to improve the performance of a
|
|
program.
|
|
.Pp
|
|
The POSIX thread functions are summarized in this section in the following
|
|
groups:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
Thread Routines
|
|
.It
|
|
Attribute Object Routines
|
|
.It
|
|
Mutex Routines
|
|
.It
|
|
Condition Variable Routines
|
|
.It
|
|
Read/Write Lock Routines
|
|
.It
|
|
Per-Thread Context Routines
|
|
.It
|
|
Cleanup Routines
|
|
.El
|
|
.Sh THREAD ROUTINES
|
|
.Bl -tag -width Er
|
|
.It int Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
|
|
Creates a new thread of execution.
|
|
.It int Fn pthread_detach "pthread_t thread"
|
|
Marks a thread for deletion.
|
|
.It int Fn pthread_equal "pthread_t t1" "pthread_t t2"
|
|
Compares two thread IDs.
|
|
.It void Fn pthread_exit "void *value_ptr"
|
|
Terminates the calling thread.
|
|
.It int Fn pthread_join "pthread_t thread" "void **value_ptr"
|
|
Causes the calling thread to wait for the termination of the specified thread.
|
|
.It int Fn pthread_cancel "pthread_t thread"
|
|
Cancels execution of a thread.
|
|
.It int Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
|
|
Calls an initialization routine once.
|
|
.It pthread_t Fn pthread_self void
|
|
Returns the thread ID of the calling thread.
|
|
.El
|
|
.Sh ATTRIBUTE OBJECT ROUTINES
|
|
.Bl -tag -width Er
|
|
.It int Fn pthread_attr_destroy "pthread_attr_t *attr"
|
|
Destroy a thread attributes object.
|
|
.It int Fn pthread_attr_getinheritsched "pthread_attr_t *attr" "int *inheritsched"
|
|
Get the inherit scheduling attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_getschedparam "pthread_attr_t *attr" "struct sched_param *param"
|
|
Get the scheduling parameter attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_getschedpolicy "pthread_attr_t *attr" "int *policy"
|
|
Get the scheduling policy attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_getscope "pthread_attr_t *attr" "int *contentionscope"
|
|
Get the contention scope attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_getstacksize "pthread_attr_t *attr" "size_t *stacksize"
|
|
Get the stack size attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_getstackaddr "pthread_attr_t *attr" "void **stackaddr"
|
|
Get the stack address attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate"
|
|
Get the detach state attribute from a thread attributes object.
|
|
.It int Fn pthread_attr_init "pthread_attr_t *attr"
|
|
Initialize a thread attributes object with default values.
|
|
.It int Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
|
|
Set the inherit scheduling attribute in a thread attributes object.
|
|
.It int Fn pthread_attr_setschedparam "pthread_attr_t *attr" "struct sched_param *param"
|
|
Set the scheduling parameter attribute in a thread attributes object.
|
|
.It int Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
|
|
Set the scheduling policy attribute in a thread attributes object.
|
|
.It int Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
|
|
Set the contention scope attribute in a thread attributes object.
|
|
.It int Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
|
|
Set the stack size attribute in a thread attributes object.
|
|
.It int Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
|
|
Set the stack address attribute in a thread attributes object.
|
|
.It int Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
|
|
Set the detach state in a thread attributes object.
|
|
.El
|
|
.Sh MUTEX ROUTINES
|
|
.Bl -tag -width Er
|
|
.It int Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
|
|
Destroy a mutex attributes object.
|
|
.It int Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
|
|
Initialize a mutex attributes object with default values.
|
|
.It int Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
|
|
Destroy a mutex.
|
|
.It int Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
|
|
Initialize a mutex with specified attributes.
|
|
.It int Fn pthread_mutex_lock "pthread_mutex_t *mutex"
|
|
Lock a mutex and block until it becomes available.
|
|
.It int Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
|
|
Try to lock a mutex, but don't block if the mutex is locked by another thread,
|
|
including the current thread.
|
|
.It int Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
|
|
Unlock a mutex.
|
|
.El
|
|
.Sh CONDITION VARIABLE ROUTINES
|
|
.Bl -tag -width Er
|
|
.It int Fn pthread_condattr_init "pthread_condattr_t *attr"
|
|
Initialize a condition variable attributes object with default values.
|
|
.It int Fn pthread_condattr_destroy "pthread_condattr_t *attr"
|
|
Destroy a condition variable attributes object.
|
|
.It int Fn pthread_cond_broadcast "pthread_cond_t *cond"
|
|
Unblock all threads currently blocked on the specified condition variable.
|
|
.It int Fn pthread_cond_destroy "pthread_cond_t *cond"
|
|
Destroy a condition variable.
|
|
.It int Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
|
|
Initialize a condition variable with specified attributes.
|
|
.It int Fn pthread_cond_signal "pthread_cond_t *cond"
|
|
Unblock at least one of the threads blocked on the specified condition variable.
|
|
.It int Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
|
|
Wait no longer than the specified time for a condition and lock the specified mutex.
|
|
.It int Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
|
|
Wait for a condition and lock the specified mutex.
|
|
.El
|
|
.Sh READ/WRITE LOCK ROUTINES
|
|
.Bl -tag -width Er
|
|
.It int Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
|
|
Destroy a read/write lock object.
|
|
.It int Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
|
|
Initialize a read/write lock object.
|
|
.It int Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
|
|
Lock a read/write lock for reading, blocking until the lock can be
|
|
acquired.
|
|
.It int Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
|
|
Attempt to lock a read/write lock for reading, without blocking if the
|
|
lock is unavailable.
|
|
.It int Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
|
|
Attempt to lock a read/write lock for writing, without blocking if the
|
|
lock is unavailable.
|
|
.It int Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
|
|
Unlock a read/write lock.
|
|
.It int Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
|
|
Lock a read/write lock for writing, blocking until the lock can be
|
|
acquired.
|
|
.It int Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
|
|
Destroy a read/write lock attribute object.
|
|
.It int Fn pthread_rwlockattr_getpshared "pthread_rwlockattr_t *attr" "int *pshared"
|
|
Retrieve the process shared setting for the read/write lock attribute
|
|
object.
|
|
.It int Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
|
|
Initialize a read/write lock attribute object.
|
|
.It int Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int *pshared"
|
|
Set the process shared setting for the read/write lock attribute object.
|
|
.El
|
|
.Sh PER-THREAD CONTEXT ROUTINES
|
|
.Bl -tag -width Er
|
|
.It int Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
|
|
Create a thread-specific data key.
|
|
.It int Fn pthread_key_delete "pthread_key_t key"
|
|
Delete a thread-specific data key.
|
|
.It void * Fn pthread_getspecific "pthread_key_t key" "void **value_ptr"
|
|
Get the thread-specific value for the specified key.
|
|
.It int Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
|
|
Set the thread-specific value for the specified key.
|
|
.El
|
|
.Sh CLEANUP ROUTINES
|
|
.Bl -tag -width Er
|
|
.It void Fn pthread_cleanup_pop "int execute"
|
|
Remove the routine at the top of the calling thread's cancellation cleanup
|
|
stack and optionally invoke it.
|
|
.It void Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
|
|
Push the specified cancellation cleanup handler onto the calling thread's
|
|
cancellation stack.
|
|
.El
|
|
.Sh INSTALLATION
|
|
The current FreeBSD POSIX thread implementation is built in the library
|
|
.Fa libc_r
|
|
which contains both thread-safe libc functions and the thread functions.
|
|
This library replaces
|
|
.Fa libc
|
|
for threaded applications.
|
|
.Pp
|
|
By default,
|
|
.Fa libc_r
|
|
is built as part of a 'make world'. To disable the build of
|
|
.Fa libc_r
|
|
you must supply the '-DNOLIBC_R' option to
|
|
.Xr make 1 .
|
|
.Pp
|
|
A FreeBSD specific option has been added to gcc to make linking
|
|
threaded processes simple.
|
|
.Fa gcc -pthread
|
|
links a threaded process against
|
|
.Fa libc_r
|
|
instead of
|
|
.Fa libc.
|
|
.Sh STANDARDS
|
|
The functions in
|
|
.Fa libc_r
|
|
with the
|
|
.Fa pthread_
|
|
prefix and not
|
|
.Fa _np
|
|
suffix or
|
|
.Fa pthread_rwlock
|
|
prefix conform to IEEE
|
|
.Pq Dq Tn POSIX
|
|
Std 1003.1 Second Edition 1996-07-12
|
|
.Pp
|
|
The functions in libc_r with the
|
|
.Fa pthread_
|
|
prefix and
|
|
.Fa _np
|
|
suffix are non-portable extensions to POSIX threads.
|
|
.Pp
|
|
The functions in libc_r with the
|
|
.Fa pthread_rwlock
|
|
prefix are extensions created by The Open Group as part of the Single
|
|
UNIX Specification, Version 2.
|