--- /dev/null
+.\" Portions Copyright (c) 2001 Apple Computer, Inc. All Rights Reserved.
+.\" 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: 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 <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_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 .
projects / apple / libc.git / blobdiff