X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/3b2a1fe8d3d02703ddca1b0ead469074d4e47820..5b2abdfbf4211b6592cdd02b9507555a0ecbb04b:/pthreads/pthread.3 diff --git a/pthreads/pthread.3 b/pthreads/pthread.3 new file mode 100644 index 0000000..444e361 --- /dev/null +++ b/pthreads/pthread.3 @@ -0,0 +1,435 @@ +.\" Portions Copyright (c) 2001 Apple Computer, Inc. All Rights Reserved. +.\" Copyright (c) 1996 John Birrell . +.\" 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: src/share/man/man3/pthread.3,v 1.12.2.4 2001/08/17 13:08:36 ru Exp $ +.\" +.Dd November 5, 2001 +.Dt PTHREAD 3 +.Os Darwin +.Sh NAME +.Nm pthread +.Nd POSIX thread functions +.Sh SYNOPSIS +.Fd #include +.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_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_cancel "pthread_t thread" +.Xc +Cancels execution of a 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. +.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_init "pthread_mutexattr_t *attr" +.Xc +Initialize a mutex attributes object with default values. +.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_init "pthread_condattr_t *attr" +.Xc +Initialize a condition variable attributes object with default values. +.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_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 default system libraries include +.Nm +funcitons. No additional libraries or CFLAGS are necessary to use this API. +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 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_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_setspecific 3 +.Sh STANDARDS +The functions in +.Fa libc +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 with the +.Fa pthread_ +prefix and +.Fa _np +suffix are non-portable extensions to POSIX threads. +.Pp +The functions in libc with the +.Fa pthread_rwlock +prefix are extensions created by The Open Group as part of the +.St -susv2 .