526 lines
14 KiB
Groff
526 lines
14 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
|
|
.Sh NAME
|
|
.Nm pthread
|
|
.Nd POSIX thread functions
|
|
.Sh SYNOPSIS
|
|
.In pthread.h
|
|
.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 Xo
|
|
.Ft int
|
|
.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
|
|
.Xc
|
|
Creates a new thread of execution.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cancel "pthread_t thread"
|
|
.Xc
|
|
Cancels execution of a thread.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_detach "pthread_t thread"
|
|
.Xc
|
|
Marks a thread for deletion.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_equal "pthread_t t1" "pthread_t t2"
|
|
.Xc
|
|
Compares two thread IDs.
|
|
.It Xo
|
|
.Ft void
|
|
.Fn pthread_exit "void *value_ptr"
|
|
.Xc
|
|
Terminates the calling thread.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_join "pthread_t thread" "void **value_ptr"
|
|
.Xc
|
|
Causes the calling thread to wait for the termination of the specified thread.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_kill "pthread_t thread" "int sig"
|
|
.Xc
|
|
Delivers a signal to a specified thread.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
|
|
.Xc
|
|
Calls an initialization routine once.
|
|
.It Xo
|
|
.Ft pthread_t
|
|
.Fn pthread_self void
|
|
.Xc
|
|
Returns the thread ID of the calling thread.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_setcancelstate "int state" "int *oldstate"
|
|
.Xc
|
|
Sets the current thread's cancelability state.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_setcanceltype "int type" "int *oldtype"
|
|
.Xc
|
|
Sets the current thread's cancelability type.
|
|
.It Xo
|
|
.Ft void
|
|
.Fn pthread_testcancel void
|
|
.Xc
|
|
Creates a cancellation point in the calling thread.
|
|
.It Xo
|
|
.Ft void
|
|
.Fn pthread_yield void
|
|
.Xc
|
|
Allows the scheduler to run another thread instead of the current one.
|
|
.El
|
|
.Sh ATTRIBUTE OBJECT ROUTINES
|
|
.Bl -tag -width Er
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_destroy "pthread_attr_t *attr"
|
|
.Xc
|
|
Destroy a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched"
|
|
.Xc
|
|
Get the inherit scheduling attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param"
|
|
.Xc
|
|
Get the scheduling parameter attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
|
|
.Xc
|
|
Get the scheduling policy attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
|
|
.Xc
|
|
Get the contention scope attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
|
|
.Xc
|
|
Get the stack size attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
|
|
.Xc
|
|
Get the stack address attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
|
|
.Xc
|
|
Get the detach state attribute from a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_init "pthread_attr_t *attr"
|
|
.Xc
|
|
Initialize a thread attributes object with default values.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
|
|
.Xc
|
|
Set the inherit scheduling attribute in a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
|
|
.Xc
|
|
Set the scheduling parameter attribute in a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
|
|
.Xc
|
|
Set the scheduling policy attribute in a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
|
|
.Xc
|
|
Set the contention scope attribute in a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
|
|
.Xc
|
|
Set the stack size attribute in a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
|
|
.Xc
|
|
Set the stack address attribute in a thread attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
|
|
.Xc
|
|
Set the detach state in a thread attributes object.
|
|
.El
|
|
.Sh MUTEX ROUTINES
|
|
.Bl -tag -width Er
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
|
|
.Xc
|
|
Destroy a mutex attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling"
|
|
.Xc
|
|
Obtain priority ceiling attribute of mutex attribute object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
|
|
.Xc
|
|
Obtain protocol attribute of mutex attribute object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
|
|
.Xc
|
|
Obtain the mutex type attribute in the specified mutex attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
|
|
.Xc
|
|
Initialize a mutex attributes object with default values.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
|
|
.Xc
|
|
Set priority ceiling attribute of mutex attribute object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
|
|
.Xc
|
|
Set protocol attribute of mutex attribute object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
|
|
.Xc
|
|
Set the mutex type attribute that is used when a mutex is created.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
|
|
.Xc
|
|
Destroy a mutex.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
|
|
.Xc
|
|
Initialize a mutex with specified attributes.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutex_lock "pthread_mutex_t *mutex"
|
|
.Xc
|
|
Lock a mutex and block until it becomes available.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
|
|
.Xc
|
|
Try to lock a mutex, but don't block if the mutex is locked by another thread,
|
|
including the current thread.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
|
|
.Xc
|
|
Unlock a mutex.
|
|
.El
|
|
.Sh CONDITION VARIABLE ROUTINES
|
|
.Bl -tag -width Er
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_condattr_destroy "pthread_condattr_t *attr"
|
|
.Xc
|
|
Destroy a condition variable attributes object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_condattr_init "pthread_condattr_t *attr"
|
|
.Xc
|
|
Initialize a condition variable attributes object with default values.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cond_broadcast "pthread_cond_t *cond"
|
|
.Xc
|
|
Unblock all threads currently blocked on the specified condition variable.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cond_destroy "pthread_cond_t *cond"
|
|
.Xc
|
|
Destroy a condition variable.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
|
|
.Xc
|
|
Initialize a condition variable with specified attributes.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cond_signal "pthread_cond_t *cond"
|
|
.Xc
|
|
Unblock at least one of the threads blocked on the specified condition variable.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
|
|
.Xc
|
|
Wait no longer than the specified time for a condition and lock the specified mutex.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
|
|
.Xc
|
|
Wait for a condition and lock the specified mutex.
|
|
.El
|
|
.Sh READ/WRITE LOCK ROUTINES
|
|
.Bl -tag -width Er
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
|
|
.Xc
|
|
Destroy a read/write lock object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
|
|
.Xc
|
|
Initialize a read/write lock object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
|
|
.Xc
|
|
Lock a read/write lock for reading, blocking until the lock can be
|
|
acquired.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
|
|
.Xc
|
|
Attempt to lock a read/write lock for reading, without blocking if the
|
|
lock is unavailable.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
|
|
.Xc
|
|
Attempt to lock a read/write lock for writing, without blocking if the
|
|
lock is unavailable.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
|
|
.Xc
|
|
Unlock a read/write lock.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
|
|
.Xc
|
|
Lock a read/write lock for writing, blocking until the lock can be
|
|
acquired.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
|
|
.Xc
|
|
Destroy a read/write lock attribute object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared"
|
|
.Xc
|
|
Retrieve the process shared setting for the read/write lock attribute
|
|
object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
|
|
.Xc
|
|
Initialize a read/write lock attribute object.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
|
|
.Xc
|
|
Set the process shared setting for the read/write lock attribute object.
|
|
.El
|
|
.Sh PER-THREAD CONTEXT ROUTINES
|
|
.Bl -tag -width Er
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
|
|
.Xc
|
|
Create a thread-specific data key.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_key_delete "pthread_key_t key"
|
|
.Xc
|
|
Delete a thread-specific data key.
|
|
.It Xo
|
|
.Ft "void *"
|
|
.Fn pthread_getspecific "pthread_key_t key"
|
|
.Xc
|
|
Get the thread-specific value for the specified key.
|
|
.It Xo
|
|
.Ft int
|
|
.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
|
|
.Xc
|
|
Set the thread-specific value for the specified key.
|
|
.El
|
|
.Sh CLEANUP ROUTINES
|
|
.Bl -tag -width Er
|
|
.It Xo
|
|
.Ft void
|
|
.Fn pthread_cleanup_pop "int execute"
|
|
.Xc
|
|
Remove the routine at the top of the calling thread's cancellation cleanup
|
|
stack and optionally invoke it.
|
|
.It Xo
|
|
.Ft void
|
|
.Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
|
|
.Xc
|
|
Push the specified cancellation cleanup handler onto the calling thread's
|
|
cancellation stack.
|
|
.El
|
|
.Sh INSTALLATION
|
|
The current
|
|
.Fx
|
|
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
|
|
.Fx
|
|
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 SEE ALSO
|
|
.Xr pthread_cleanup_pop 3 ,
|
|
.Xr pthread_cleanup_push 3 ,
|
|
.Xr pthread_condattr_destroy 3 ,
|
|
.Xr pthread_condattr_init 3 ,
|
|
.Xr pthread_cond_broadcast 3 ,
|
|
.Xr pthread_cond_destroy 3 ,
|
|
.Xr pthread_cond_init 3 ,
|
|
.Xr pthread_cond_signal 3 ,
|
|
.Xr pthread_cond_timedwait 3 ,
|
|
.Xr pthread_cond_wait 3 ,
|
|
.Xr pthread_create 3 ,
|
|
.Xr pthread_detach 3 ,
|
|
.Xr pthread_equal 3 ,
|
|
.Xr pthread_exit 3 ,
|
|
.Xr pthread_getspecific 3 ,
|
|
.Xr pthread_join 3 ,
|
|
.Xr pthread_key_delete 3 ,
|
|
.Xr pthread_kill 3 ,
|
|
.Xr pthread_mutexattr_destroy 3 ,
|
|
.Xr pthread_mutexattr_getprioceiling 3 ,
|
|
.Xr pthread_mutexattr_getprotocol 3 ,
|
|
.Xr pthread_mutexattr_gettype 3 ,
|
|
.Xr pthread_mutexattr_init 3 ,
|
|
.Xr pthread_mutexattr_setprioceiling 3 ,
|
|
.Xr pthread_mutexattr_setprotocol 3 ,
|
|
.Xr pthread_mutexattr_settype 3 ,
|
|
.Xr pthread_mutex_destroy 3 ,
|
|
.Xr pthread_mutex_init 3 ,
|
|
.Xr pthread_mutex_lock 3 ,
|
|
.Xr pthread_mutex_trylock 3 ,
|
|
.Xr pthread_mutex_unlock 3 ,
|
|
.Xr pthread_once 3 ,
|
|
.Xr pthread_rwlockattr_destroy 3 ,
|
|
.Xr pthread_rwlockattr_getpshared 3 ,
|
|
.Xr pthread_rwlockattr_init 3 ,
|
|
.Xr pthread_rwlockattr_setpshared 3 ,
|
|
.Xr pthread_rwlock_destroy 3 ,
|
|
.Xr pthread_rwlock_init 3 ,
|
|
.Xr pthread_rwlock_rdlock 3 ,
|
|
.Xr pthread_rwlock_unlock 3 ,
|
|
.Xr pthread_rwlock_wrlock 3 ,
|
|
.Xr pthread_self 3 ,
|
|
.Xr pthread_setcancelstate 3 ,
|
|
.Xr pthread_setcanceltype 3 ,
|
|
.Xr pthread_setspecific 3 ,
|
|
.Xr pthread_testcancel 3
|
|
.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
|
|
.St -p1003.1-96 .
|
|
.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
|
|
.St -susv2 .
|