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

.\" $NetBSD: pthread_mutexattr.3,v 1.3 2003/07/04 08:36:06 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" 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. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
.\" 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(s), this list of conditions and the following disclaimer as
.\"    the first lines of this file unmodified other than the possible
.\"    addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice(s), this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
.Dd January 30, 2003
.Dt PTHREAD_MUTEXATTR 3
.Os
.Sh NAME
.Nm pthread_mutexattr_init ,
.Nm pthread_mutexattr_destroy ,
.Nm pthread_mutexattr_setprioceiling ,
.Nm pthread_mutexattr_getprioceiling ,
.Nm pthread_mutexattr_setprotocol ,
.Nm pthread_mutexattr_getprotocol ,
.Nm pthread_mutexattr_settype ,
.Nm pthread_mutexattr_gettype
.Nd mutex attribute operations
.Sh SYNOPSIS
.Fd #include <pthread.h>
.Ft int
.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
.Ft int
.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
.Ft int
.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
.Ft int
.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"
.Ft int
.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
.Ft int
.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
.Ft int
.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
.Ft int
.Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
.Sh DESCRIPTION
Mutex attributes are used to specify parameters to
.Fn pthread_mutex_init .
One attribute object can be used in multiple calls to
.Fn pthread_mutex_init ,
with or without modifications between calls.
.Pp
The
.Fn pthread_mutexattr_init
function initializes
.Fa attr
with all the default mutex attributes.
.Pp
The
.Fn pthread_mutexattr_destroy
function destroys
.Fa attr .
.Pp
The
.Fn pthread_mutexattr_settype
functions set the mutex type value of the attribute.  Valid mutex types are:
.Dv PTHREAD_MUTEX_NORMAL ,
.Dv PTHREAD_MUTEX_ERRORCHECK ,
.Dv PTHREAD_MUTEX_RECURSIVE ,
and
.Dv PTHREAD_MUTEX_DEFAULT .
The default mutex type for
.Fn pthread_mutexaddr_init
is
.Dv PTHREAD_MUTEX_DEFAULT .
.Pp
.Dv PTHREAD_MUXEX_NORMAL
mutexes do not check for usage errors.
.Dv PTHREAD_MUTEX_NORMAL
mutexes will deadlock if reentered, and result in undefined behavior if a
locked mutex is unlocked by another thread.  Attempts to unlock an already
unlocked
.Dv PTHREAD_MUTEX_NORMAL
mutex will result in undefined behavior.
.Pp
.Dv PTHREAD_MUTEX_ERRORCHECK
mutexes do check for usage errors.
If an attempt is made to relock a
.Dv PTHREAD_MUTEX_ERRORCHECK
mutex without first dropping the lock an error will be returned.  If a thread
attempts to unlock a
.Dv PTHREAD_MUTEX_ERRORCHECK
mutex that is locked by another thread, an error will be returned.  If a
thread attemps to unlock a
.Dv PTHREAD_MUTEX_ERRORCHECK
thread that is unlocked, an error will be
returned.
.Pp
.Dv PTHREAD_MUTEX_RECURSIVE
mutexes allow recursive locking.
An attempt to relock a
.Dv PTHREAD_MUTEX_RECURSIVE
mutex that is already locked by the same thread succeeds.  An equivalent
number of
.Xr pthread_mutex_unlock 3
calls are needed before the mutex will wake another thread waiting on this
lock.  If a thread attempts to unlock a
.Dv PTHREAD_MUTEX_RECURSIVE
mutex that is locked by another thread, an error will be returned.  If a thread attemps to unlock a
.Dv PTHREAD_MUTEX_RECURSIVE
thread that is unlocked, an error will be returned.
.Pp
.Dv PTHREAD_MUTEX_DEFAULT
mutexes result in undefined behavior if reentered.
Unlocking a
.Dv PTHREAD_MUTEX_DEFAULT
mutex locked by another thread will result in undefined behavior.  Attempts to unlock an already
unlocked
.Dv PTHREAD_MUTEX_DEFAULT
mutex will result in undefined behavior.
.Pp
.Fn pthread_mutexattr_gettype
functions copy the type value of the attribute to the location pointed to by the second parameter.
.Pp
The
.Fn pthread_mutexattr_set*
functions set the attribute that corresponds to each function name.
.Pp
The
.Fn pthread_mutexattr_get*
functions copy the value of the attribute that corresponds to each function name
to the location pointed to by the second function parameter.
.Sh RETURN VALUES
If successful, these functions return 0.
Otherwise, an error number is returned to indicate the error.
.Sh ERRORS
.Fn pthread_mutexattr_init
will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Out of memory.
.El
.Pp
.Fn pthread_mutexattr_destroy
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
.Fn pthread_mutexattr_setprioceiling
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr ,
or invalid value for
.Fa prioceiling .
.El
.Pp
.Fn pthread_mutexattr_getprioceiling
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
.Fn pthread_mutexattr_setprotocol
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr ,
or invalid value for
.Fa protocol .
.El
.Pp
.Fn pthread_mutexattr_getprotocol
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
.Fn pthread_mutexattr_settype
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr ,
or invalid value for
.Fa type .
.El
.Pp
.Fn pthread_mutexattr_gettype
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Sh SEE ALSO
.Xr pthread_mutex_init 3
.Sh STANDARDS
.Fn pthread_mutexattr_init
and
.Fn pthread_mutexattr_destroy
conform to
.St -p1003.1-96
.Pp
.Fn pthread_mutexattr_setprioceiling ,
.Fn pthread_mutexattr_getprioceiling ,
.Fn pthread_mutexattr_setprotocol ,
.Fn pthread_mutexattr_getprotocol ,
.Fn pthread_mutexattr_settype ,
and
.Fn pthread_mutexattr_gettype
conform to
.St -susv2
Commit	Line	Data
9385eb3d A	1	.\" $NetBSD: pthread_mutexattr.3,v 1.3 2003/07/04 08:36:06 wiz Exp $
	2	.\"
	3	.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
	4	.\" All rights reserved.
	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. Neither the name of The NetBSD Foundation nor the names of its
	14	.\" contributors may be used to endorse or promote products derived
	15	.\" from this software without specific prior written permission.
	16	.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
	17	.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
	18	.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	19	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
	20	.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	21	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	22	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	23	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	24	.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	25	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	26	.\" POSSIBILITY OF SUCH DAMAGE.
	27	.\"
5b2abdfb A	28	.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
	29	.\" All rights reserved.
	30	.\"
	31	.\" Redistribution and use in source and binary forms, with or without
	32	.\" modification, are permitted provided that the following conditions
	33	.\" are met:
	34	.\" 1. Redistributions of source code must retain the above copyright
	35	.\" notice(s), this list of conditions and the following disclaimer as
	36	.\" the first lines of this file unmodified other than the possible
	37	.\" addition of one or more copyright notices.
	38	.\" 2. Redistributions in binary form must reproduce the above copyright
	39	.\" notice(s), this list of conditions and the following disclaimer in
	40	.\" the documentation and/or other materials provided with the
	41	.\" distribution.
	42	.\"
	43	.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
	44	.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	45	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	46	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
	47	.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	48	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	49	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
	50	.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
	51	.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
	52	.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
	53	.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	54	.\"
9385eb3d A	55	.\" $FreeBSD: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
9385eb3d A	56	.Dd January 30, 2003
5b2abdfb A	57	.Dt PTHREAD_MUTEXATTR 3
	58	.Os
	59	.Sh NAME
	60	.Nm pthread_mutexattr_init ,
	61	.Nm pthread_mutexattr_destroy ,
	62	.Nm pthread_mutexattr_setprioceiling ,
	63	.Nm pthread_mutexattr_getprioceiling ,
	64	.Nm pthread_mutexattr_setprotocol ,
	65	.Nm pthread_mutexattr_getprotocol ,
	66	.Nm pthread_mutexattr_settype ,
	67	.Nm pthread_mutexattr_gettype
	68	.Nd mutex attribute operations
	69	.Sh SYNOPSIS
	70	.Fd #include <pthread.h>
	71	.Ft int
	72	.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
	73	.Ft int
	74	.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
	75	.Ft int
	76	.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
	77	.Ft int
	78	.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t attr" "int prioceiling"
	79	.Ft int
	80	.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
	81	.Ft int
	82	.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t attr" "int protocol"
	83	.Ft int
	84	.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
	85	.Ft int
	86	.Fn pthread_mutexattr_gettype "pthread_mutexattr_t attr" "int type"
	87	.Sh DESCRIPTION
	88	Mutex attributes are used to specify parameters to
	89	.Fn pthread_mutex_init .
	90	One attribute object can be used in multiple calls to
	91	.Fn pthread_mutex_init ,
	92	with or without modifications between calls.
	93	.Pp
	94	The
	95	.Fn pthread_mutexattr_init
	96	function initializes
	97	.Fa attr
	98	with all the default mutex attributes.
	99	.Pp
	100	The
	101	.Fn pthread_mutexattr_destroy
	102	function destroys
	103	.Fa attr .
	104	.Pp
	105	The
9385eb3d A	106	.Fn pthread_mutexattr_settype
	107	functions set the mutex type value of the attribute. Valid mutex types are:
	108	.Dv PTHREAD_MUTEX_NORMAL ,
	109	.Dv PTHREAD_MUTEX_ERRORCHECK ,
	110	.Dv PTHREAD_MUTEX_RECURSIVE ,
	111	and
	112	.Dv PTHREAD_MUTEX_DEFAULT .
	113	The default mutex type for
	114	.Fn pthread_mutexaddr_init
	115	is
	116	.Dv PTHREAD_MUTEX_DEFAULT .
	117	.Pp
	118	.Dv PTHREAD_MUXEX_NORMAL
	119	mutexes do not check for usage errors.
	120	.Dv PTHREAD_MUTEX_NORMAL
	121	mutexes will deadlock if reentered, and result in undefined behavior if a
	122	locked mutex is unlocked by another thread. Attempts to unlock an already
	123	unlocked
	124	.Dv PTHREAD_MUTEX_NORMAL
	125	mutex will result in undefined behavior.
	126	.Pp
	127	.Dv PTHREAD_MUTEX_ERRORCHECK
	128	mutexes do check for usage errors.
	129	If an attempt is made to relock a
	130	.Dv PTHREAD_MUTEX_ERRORCHECK
	131	mutex without first dropping the lock an error will be returned. If a thread
	132	attempts to unlock a
	133	.Dv PTHREAD_MUTEX_ERRORCHECK
	134	mutex that is locked by another thread, an error will be returned. If a
	135	thread attemps to unlock a
	136	.Dv PTHREAD_MUTEX_ERRORCHECK
	137	thread that is unlocked, an error will be
	138	returned.
	139	.Pp
	140	.Dv PTHREAD_MUTEX_RECURSIVE
	141	mutexes allow recursive locking.
	142	An attempt to relock a
	143	.Dv PTHREAD_MUTEX_RECURSIVE
	144	mutex that is already locked by the same thread succeeds. An equivalent
	145	number of
	146	.Xr pthread_mutex_unlock 3
	147	calls are needed before the mutex will wake another thread waiting on this
	148	lock. If a thread attempts to unlock a
	149	.Dv PTHREAD_MUTEX_RECURSIVE
	150	mutex that is locked by another thread, an error will be returned. If a thread attemps to unlock a
	151	.Dv PTHREAD_MUTEX_RECURSIVE
	152	thread that is unlocked, an error will be returned.
	153	.Pp
	154	.Dv PTHREAD_MUTEX_DEFAULT
	155	mutexes result in undefined behavior if reentered.
	156	Unlocking a
	157	.Dv PTHREAD_MUTEX_DEFAULT
	158	mutex locked by another thread will result in undefined behavior. Attempts to unlock an already
	159	unlocked
	160	.Dv PTHREAD_MUTEX_DEFAULT
	161	mutex will result in undefined behavior.
	162	.Pp
	163	.Fn pthread_mutexattr_gettype
	164	functions copy the type value of the attribute to the location pointed to by the second parameter.
	165	.Pp
	166	The
5b2abdfb A	167	.Fn pthread_mutexattr_set*
	168	functions set the attribute that corresponds to each function name.
	169	.Pp
	170	The
	171	.Fn pthread_mutexattr_get*
	172	functions copy the value of the attribute that corresponds to each function name
	173	to the location pointed to by the second function parameter.
	174	.Sh RETURN VALUES
	175	If successful, these functions return 0.
9385eb3d	176	Otherwise, an error number is returned to indicate the error.
5b2abdfb A	177	.Sh ERRORS
	178	.Fn pthread_mutexattr_init
	179	will fail if:
	180	.Bl -tag -width Er
	181	.It Bq Er ENOMEM
	182	Out of memory.
	183	.El
	184	.Pp
	185	.Fn pthread_mutexattr_destroy
	186	will fail if:
	187	.Bl -tag -width Er
	188	.It Bq Er EINVAL
	189	Invalid value for
	190	.Fa attr .
	191	.El
	192	.Pp
	193	.Fn pthread_mutexattr_setprioceiling
	194	will fail if:
	195	.Bl -tag -width Er
	196	.It Bq Er EINVAL
	197	Invalid value for
	198	.Fa attr ,
	199	or invalid value for
	200	.Fa prioceiling .
	201	.El
	202	.Pp
	203	.Fn pthread_mutexattr_getprioceiling
	204	will fail if:
	205	.Bl -tag -width Er
	206	.It Bq Er EINVAL
	207	Invalid value for
	208	.Fa attr .
	209	.El
	210	.Pp
	211	.Fn pthread_mutexattr_setprotocol
	212	will fail if:
	213	.Bl -tag -width Er
	214	.It Bq Er EINVAL
	215	Invalid value for
	216	.Fa attr ,
	217	or invalid value for
	218	.Fa protocol .
	219	.El
	220	.Pp
	221	.Fn pthread_mutexattr_getprotocol
	222	will fail if:
	223	.Bl -tag -width Er
	224	.It Bq Er EINVAL
	225	Invalid value for
	226	.Fa attr .
	227	.El
	228	.Pp
	229	.Fn pthread_mutexattr_settype
	230	will fail if:
	231	.Bl -tag -width Er
	232	.It Bq Er EINVAL
	233	Invalid value for
	234	.Fa attr ,
	235	or invalid value for
	236	.Fa type .
	237	.El
	238	.Pp
	239	.Fn pthread_mutexattr_gettype
	240	will fail if:
241	.Bl -tag -width Er
242	.It Bq Er EINVAL
243	Invalid value for
244	.Fa attr .
245	.El
246	.Sh SEE ALSO
247	.Xr pthread_mutex_init 3
248	.Sh STANDARDS
249	.Fn pthread_mutexattr_init
250	and
251	.Fn pthread_mutexattr_destroy
252	conform to
253	.St -p1003.1-96
254	.Pp
255	.Fn pthread_mutexattr_setprioceiling ,
256	.Fn pthread_mutexattr_getprioceiling ,
257	.Fn pthread_mutexattr_setprotocol ,
258	.Fn pthread_mutexattr_getprotocol ,
259	.Fn pthread_mutexattr_settype ,
260	and
261	.Fn pthread_mutexattr_gettype
262	conform to
263	.St -susv2