[apple/libc.git] / pthreads / pthread.3

.\" 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 .
Commit	Line	Data
5b2abdfb A	1	.\" Portions Copyright (c) 2001 Apple Computer, Inc. All Rights Reserved.
	2	.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
	3	.\" All rights reserved.
	4	.\"
	5	.\" Redistribution and use in source and binary forms, with or without
	6	.\" modification, are permitted provided that the following conditions
	7	.\" are met:
	8	.\" 1. Redistributions of source code must retain the above copyright
	9	.\" notice, this list of conditions and the following disclaimer.
	10	.\" 2. Redistributions in binary form must reproduce the above copyright
	11	.\" notice, this list of conditions and the following disclaimer in the
	12	.\" documentation and/or other materials provided with the distribution.
	13	.\" 3. All advertising materials mentioning features or use of this software
	14	.\" must display the following acknowledgement:
	15	.\" This product includes software developed by John Birrell.
	16	.\" 4. Neither the name of the author nor the names of any co-contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" $FreeBSD: src/share/man/man3/pthread.3,v 1.12.2.4 2001/08/17 13:08:36 ru Exp $
	33	.\"
	34	.Dd November 5, 2001
	35	.Dt PTHREAD 3
	36	.Os Darwin
	37	.Sh NAME
	38	.Nm pthread
	39	.Nd POSIX thread functions
	40	.Sh SYNOPSIS
	41	.Fd #include <pthread.h>
	42	.Sh DESCRIPTION
	43	POSIX threads are a set of functions that support applications with
	44	requirements for multiple flows of control, called
	45	.Fa threads ,
	46	within a process.
	47	Multithreading is used to improve the performance of a
	48	program.
	49	.Pp
	50	The POSIX thread functions are summarized in this section in the following
	51	groups:
	52	.Bl -bullet -offset indent
	53	.It
	54	Thread Routines
	55	.It
	56	Attribute Object Routines
	57	.It
	58	Mutex Routines
	59	.It
	60	Condition Variable Routines
	61	.It
	62	Read/Write Lock Routines
	63	.It
	64	Per-Thread Context Routines
65	.It
66	Cleanup Routines
67	.El
68	.Sh THREAD ROUTINES
69	.Bl -tag -width Er
70	.It Xo
71	.Ft int
72	.Fn pthread_create "pthread_t thread" "const pthread_attr_t attr" "void (start_routine)(void )" "void arg"
73	.Xc
74	Creates a new thread of execution.
75	.It Xo
76	.Ft int
77	.Fn pthread_detach "pthread_t thread"
78	.Xc
79	Marks a thread for deletion.
80	.It Xo
81	.Ft int
82	.Fn pthread_equal "pthread_t t1" "pthread_t t2"
83	.Xc
84	Compares two thread IDs.
85	.It Xo
86	.Ft void
87	.Fn pthread_exit "void *value_ptr"
88	.Xc
89	Terminates the calling thread.
90	.It Xo
91	.Ft int
92	.Fn pthread_join "pthread_t thread" "void **value_ptr"
93	.Xc
94	Causes the calling thread to wait for the termination of the specified thread.
95	.It Xo
96	.Ft int
97	.Fn pthread_cancel "pthread_t thread"
98	.Xc
99	Cancels execution of a thread.
100	.It Xo
101	.Ft int
102	.Fn pthread_once "pthread_once_t once_control" "void (init_routine)(void)"
103	.Xc
104	Calls an initialization routine once.
105	.It Xo
106	.Ft pthread_t
107	.Fn pthread_self void
108	.Xc
109	Returns the thread ID of the calling thread.
3d9156a7 A	110	.It Xo
	111	.Ft int
	112	.Fn pthread_atfork "void (prepare)(void)" "void (parent)(void)" "void (*child)(void)"
	113	.Xc
	114	Registers handlers to be called before and after
	115	.Fn fork
5b2abdfb A	116	.El
	117	.Sh ATTRIBUTE OBJECT ROUTINES
	118	.Bl -tag -width Er
	119	.It Xo
	120	.Ft int
	121	.Fn pthread_attr_destroy "pthread_attr_t *attr"
	122	.Xc
	123	Destroy a thread attributes object.
	124	.It Xo
	125	.Ft int
	126	.Fn pthread_attr_getinheritsched "const pthread_attr_t attr" "int inheritsched"
	127	.Xc
	128	Get the inherit scheduling attribute from a thread attributes object.
	129	.It Xo
	130	.Ft int
	131	.Fn pthread_attr_getschedparam "const pthread_attr_t attr" "struct sched_param param"
	132	.Xc
	133	Get the scheduling parameter attribute from a thread attributes object.
	134	.It Xo
	135	.Ft int
	136	.Fn pthread_attr_getschedpolicy "const pthread_attr_t attr" "int policy"
	137	.Xc
	138	Get the scheduling policy attribute from a thread attributes object.
	139	.It Xo
	140	.Ft int
	141	.Fn pthread_attr_getscope "const pthread_attr_t attr" "int contentionscope"
	142	.Xc
	143	Get the contention scope attribute from a thread attributes object.
	144	.It Xo
	145	.Ft int
	146	.Fn pthread_attr_getstacksize "const pthread_attr_t attr" "size_t stacksize"
	147	.Xc
	148	Get the stack size attribute from a thread attributes object.
	149	.It Xo
	150	.Ft int
	151	.Fn pthread_attr_getstackaddr "const pthread_attr_t attr" "void *stackaddr"
	152	.Xc
	153	Get the stack address attribute from a thread attributes object.
	154	.It Xo
	155	.Ft int
	156	.Fn pthread_attr_getdetachstate "const pthread_attr_t attr" "int detachstate"
	157	.Xc
	158	Get the detach state attribute from a thread attributes object.
	159	.It Xo
	160	.Ft int
	161	.Fn pthread_attr_init "pthread_attr_t *attr"
	162	.Xc
	163	Initialize a thread attributes object with default values.
	164	.It Xo
	165	.Ft int
	166	.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
	167	.Xc
	168	Set the inherit scheduling attribute in a thread attributes object.
	169	.It Xo
	170	.Ft int
	171	.Fn pthread_attr_setschedparam "pthread_attr_t attr" "const struct sched_param param"
	172	.Xc
	173	Set the scheduling parameter attribute in a thread attributes object.
	174	.It Xo
	175	.Ft int
	176	.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
	177	.Xc
	178	Set the scheduling policy attribute in a thread attributes object.
	179	.It Xo
180	.Ft int
181	.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
182	.Xc
183	Set the contention scope attribute in a thread attributes object.
184	.It Xo
185	.Ft int
186	.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
187	.Xc
188	Set the stack size attribute in a thread attributes object.
189	.It Xo
190	.Ft int
191	.Fn pthread_attr_setstackaddr "pthread_attr_t attr" "void stackaddr"
192	.Xc
193	Set the stack address attribute in a thread attributes object.
194	.It Xo
195	.Ft int
196	.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
197	.Xc
198	Set the detach state in a thread attributes object.
199	.El
200	.Sh MUTEX ROUTINES
201	.Bl -tag -width Er
202	.It Xo
203	.Ft int
204	.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
205	.Xc
206	Destroy a mutex attributes object.
207	.It Xo
208	.Ft int
209	.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
210	.Xc
211	Initialize a mutex attributes object with default values.
212	.It Xo
213	.Ft int
214	.Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
215	.Xc
216	Destroy a mutex.
217	.It Xo
218	.Ft int
219	.Fn pthread_mutex_init "pthread_mutex_t mutex" "const pthread_mutexattr_t attr"
220	.Xc
221	Initialize a mutex with specified attributes.
222	.It Xo
223	.Ft int
224	.Fn pthread_mutex_lock "pthread_mutex_t *mutex"
225	.Xc
226	Lock a mutex and block until it becomes available.
227	.It Xo
228	.Ft int
229	.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
230	.Xc
231	Try to lock a mutex, but don't block if the mutex is locked by another thread,
232	including the current thread.
233	.It Xo
234	.Ft int
235	.Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
236	.Xc
237	Unlock a mutex.
238	.El
239	.Sh CONDITION VARIABLE ROUTINES
240	.Bl -tag -width Er
241	.It Xo
242	.Ft int
243	.Fn pthread_condattr_init "pthread_condattr_t *attr"
244	.Xc
245	Initialize a condition variable attributes object with default values.
246	.It Xo
247	.Ft int
248	.Fn pthread_condattr_destroy "pthread_condattr_t *attr"
249	.Xc
250	Destroy a condition variable attributes object.
251	.It Xo
252	.Ft int
253	.Fn pthread_cond_broadcast "pthread_cond_t *cond"
254	.Xc
255	Unblock all threads currently blocked on the specified condition variable.
256	.It Xo
257	.Ft int
258	.Fn pthread_cond_destroy "pthread_cond_t *cond"
259	.Xc
260	Destroy a condition variable.
261	.It Xo
262	.Ft int
263	.Fn pthread_cond_init "pthread_cond_t cond" "const pthread_condattr_t attr"
264	.Xc
265	Initialize a condition variable with specified attributes.
266	.It Xo
267	.Ft int
268	.Fn pthread_cond_signal "pthread_cond_t *cond"
269	.Xc
270	Unblock at least one of the threads blocked on the specified condition variable.
271	.It Xo
272	.Ft int
273	.Fn pthread_cond_timedwait "pthread_cond_t cond" "pthread_mutex_t mutex" "const struct timespec *abstime"
274	.Xc
275	Wait no longer than the specified time for a condition and lock the specified mutex.
276	.It Xo
277	.Ft int
278	.Fn pthread_cond_wait "pthread_cond_t " "pthread_mutex_t mutex"
279	.Xc
280	Wait for a condition and lock the specified mutex.
281	.El
282	.Sh READ/WRITE LOCK ROUTINES
283	.Bl -tag -width Er
284	.It Xo
285	.Ft int
286	.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
287	.Xc
288	Destroy a read/write lock object.
289	.It Xo
290	.Ft int
291	.Fn pthread_rwlock_init "pthread_rwlock_t lock" "const pthread_rwlockattr_t attr"
292	.Xc
293	Initialize a read/write lock object.
294	.It Xo
295	.Ft int
296	.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
297	.Xc
298	Lock a read/write lock for reading, blocking until the lock can be
299	acquired.
300	.It Xo
301	.Ft int
302	.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
303	.Xc
304	Attempt to lock a read/write lock for reading, without blocking if the
305	lock is unavailable.
306	.It Xo
307	.Ft int
308	.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
309	.Xc
310	Attempt to lock a read/write lock for writing, without blocking if the
311	lock is unavailable.
312	.It Xo
313	.Ft int
314	.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
315	.Xc
316	Unlock a read/write lock.
317	.It Xo
318	.Ft int
319	.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
320	.Xc
321	Lock a read/write lock for writing, blocking until the lock can be
322	acquired.
323	.It Xo
324	.Ft int
325	.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
326	.Xc
327	Destroy a read/write lock attribute object.
328	.It Xo
329	.Ft int
330	.Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t attr" "int pshared"
331	.Xc
332	Retrieve the process shared setting for the read/write lock attribute
333	object.
334	.It Xo
335	.Ft int
336	.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
337	.Xc
338	Initialize a read/write lock attribute object.
339	.It Xo
340	.Ft int
341	.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
342	.Xc
343	Set the process shared setting for the read/write lock attribute object.
344	.El
345	.Sh PER-THREAD CONTEXT ROUTINES
346	.Bl -tag -width Er
347	.It Xo
348	.Ft int
349	.Fn pthread_key_create "pthread_key_t key" "void (routine)(void *)"
350	.Xc
351	Create a thread-specific data key.
352	.It Xo
353	.Ft int
354	.Fn pthread_key_delete "pthread_key_t key"
355	.Xc
356	Delete a thread-specific data key.
357	.It Xo
358	.Ft "void *"
359	.Fn pthread_getspecific "pthread_key_t key"
360	.Xc
361	Get the thread-specific value for the specified key.
362	.It Xo
363	.Ft int
364	.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
365	.Xc
366	Set the thread-specific value for the specified key.
367	.El
368	.Sh CLEANUP ROUTINES
369	.Bl -tag -width Er
370	.It Xo
371	.Ft void
372	.Fn pthread_cleanup_pop "int execute"
373	.Xc
374	Remove the routine at the top of the calling thread's cancellation cleanup
375	stack and optionally invoke it.
376	.It Xo
377	.Ft void
378	.Fn pthread_cleanup_push "void (routine)(void )" "void *routine_arg"
379	.Xc
380	Push the specified cancellation cleanup handler onto the calling thread's
381	cancellation stack.
382	.El
383	.Sh INSTALLATION
384	The default system libraries include
224c7076 A	385	.Nm pthread
	386	functions.
	387	No additional libraries or CFLAGS are necessary to use this API.
5b2abdfb A	388	.Sh SEE ALSO
	389	.Xr pthread_cleanup_pop 3 ,
	390	.Xr pthread_cleanup_push 3 ,
	391	.Xr pthread_cond_broadcast 3 ,
	392	.Xr pthread_cond_destroy 3 ,
	393	.Xr pthread_cond_init 3 ,
	394	.Xr pthread_cond_signal 3 ,
	395	.Xr pthread_cond_timedwait 3 ,
	396	.Xr pthread_cond_wait 3 ,
	397	.Xr pthread_create 3 ,
	398	.Xr pthread_detach 3 ,
	399	.Xr pthread_equal 3 ,
	400	.Xr pthread_exit 3 ,
	401	.Xr pthread_getspecific 3 ,
	402	.Xr pthread_join 3 ,
	403	.Xr pthread_key_delete 3 ,
	404	.Xr pthread_mutex_destroy 3 ,
	405	.Xr pthread_mutex_init 3 ,
	406	.Xr pthread_mutex_lock 3 ,
	407	.Xr pthread_mutex_trylock 3 ,
	408	.Xr pthread_mutex_unlock 3 ,
	409	.Xr pthread_once 3 ,
5b2abdfb A	410	.Xr pthread_rwlock_destroy 3 ,
	411	.Xr pthread_rwlock_init 3 ,
	412	.Xr pthread_rwlock_rdlock 3 ,
	413	.Xr pthread_rwlock_unlock 3 ,
	414	.Xr pthread_rwlock_wrlock 3 ,
224c7076 A	415	.Xr pthread_rwlockattr_destroy 3 ,
	416	.Xr pthread_rwlockattr_getpshared 3 ,
	417	.Xr pthread_rwlockattr_init 3 ,
	418	.Xr pthread_rwlockattr_setpshared 3 ,
5b2abdfb A	419	.Xr pthread_self 3 ,
	420	.Xr pthread_setspecific 3
	421	.Sh STANDARDS
	422	The functions in
	423	.Fa libc
	424	with the
	425	.Fa pthread_
	426	prefix and not
	427	.Fa _np
	428	suffix or
	429	.Fa pthread_rwlock
	430	prefix conform to
	431	.St -p1003.1-96 .
	432	.Pp
	433	The functions in libc with the
	434	.Fa pthread_
	435	prefix and
	436	.Fa _np
	437	suffix are non-portable extensions to POSIX threads.
	438	.Pp
	439	The functions in libc with the
	440	.Fa pthread_rwlock
	441	prefix are extensions created by The Open Group as part of the
	442	.St -susv2 .