+++ /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.
-.It Xo
-.Ft int
-.Fn pthread_atfork "void (*prepare)(void)" "void (*parent)(void)" "void (*child)(void)"
-.Xc
-Registers handlers to be called before and after
-.Fn fork
-.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 pthread
-functions.
-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_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_rwlockattr_destroy 3 ,
-.Xr pthread_rwlockattr_getpshared 3 ,
-.Xr pthread_rwlockattr_init 3 ,
-.Xr pthread_rwlockattr_setpshared 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