xref: /netbsd-src/lib/libpthread/pthread_mutexattr.3 (revision cada2c18c7a0a04a088abbd8904a6820c6bbcbf5)
1.\" $NetBSD: pthread_mutexattr.3,v 1.14 2017/02/02 10:48:22 njoly Exp $
2.\"
3.\" Copyright (c) 2002, 2010 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.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
14.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
17.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
23.\" POSSIBILITY OF SUCH DAMAGE.
24.\"
25.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
26.\" All rights reserved.
27.\"
28.\" Redistribution and use in source and binary forms, with or without
29.\" modification, are permitted provided that the following conditions
30.\" are met:
31.\" 1. Redistributions of source code must retain the above copyright
32.\"    notice(s), this list of conditions and the following disclaimer as
33.\"    the first lines of this file unmodified other than the possible
34.\"    addition of one or more copyright notices.
35.\" 2. Redistributions in binary form must reproduce the above copyright
36.\"    notice(s), this list of conditions and the following disclaimer in
37.\"    the documentation and/or other materials provided with the
38.\"    distribution.
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
41.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
44.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
45.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
46.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
47.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
48.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
49.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
50.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
51.\"
52.\" $FreeBSD: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
53.Dd June 12, 2016
54.Dt PTHREAD_MUTEXATTR 3
55.Os
56.Sh NAME
57.Nm pthread_mutexattr_init ,
58.Nm pthread_mutexattr_destroy ,
59.Nm pthread_mutexattr_setprioceiling ,
60.Nm pthread_mutexattr_getprioceiling ,
61.Nm pthread_mutexattr_setprotocol ,
62.Nm pthread_mutexattr_getprotocol ,
63.Nm pthread_mutexattr_settype ,
64.Nm pthread_mutexattr_gettype ,
65.Nm pthread_mutexattr_getpshared ,
66.Nm pthread_mutexattr_setpshared
67.Nd mutex attribute operations
68.Sh LIBRARY
69.Lb libpthread
70.Sh SYNOPSIS
71.In pthread.h
72.Ft int
73.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
74.Ft int
75.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
76.Ft int
77.Fn pthread_mutexattr_setprioceiling \
78"pthread_mutexattr_t *attr" "int prioceiling"
79.Ft int
80.Fn pthread_mutexattr_getprioceiling \
81"pthread_mutexattr_t *attr" "int *prioceiling"
82.Ft int
83.Fn pthread_mutexattr_setprotocol \
84"pthread_mutexattr_t *attr" "int protocol"
85.Ft int
86.Fn pthread_mutexattr_getprotocol \
87"pthread_mutexattr_t *attr" "int *protocol"
88.Ft int
89.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
90.Ft int
91.Fn pthread_mutexattr_gettype \
92"pthread_mutexattr_t * restrict attr" "int * restrict type"
93.Ft int
94.Fn pthread_mutexattr_getpshared \
95"const pthread_mutexattr_t * __restrict attr" "int * __restrict pshared"
96.Ft int
97.Fn pthread_mutexattr_setpshared \
98"pthread_mutexattr_t * attr" "int pshared"
99.Sh DESCRIPTION
100Mutex attributes are used to specify parameters to
101.Fn pthread_mutex_init .
102Like with thread attributes,
103one attribute object can be used in multiple calls to
104.Xr pthread_mutex_init 3 ,
105with or without modifications between calls.
106.Pp
107The
108.Fn pthread_mutexattr_init
109function initializes
110.Fa attr
111with all the default mutex attributes.
112.Pp
113The
114.Fn pthread_mutexattr_destroy
115function destroys
116.Fa attr .
117.Pp
118The
119.Fn pthread_mutexattr_settype
120functions set the mutex
121.Fa type
122value of the attribute.
123Valid mutex types are:
124.Bl -tag -width "XXX" -offset 2n
125.It Dv PTHREAD_MUTEX_NORMAL
126This type of mutex does not check for usage errors.
127It will deadlock if reentered, and result in undefined behavior if a
128locked mutex is unlocked by another thread.
129Attempts to unlock an already unlocked
130.Dv PTHREAD_MUTEX_NORMAL
131mutex will result in undefined behavior.
132.It Dv PTHREAD_MUTEX_ERRORCHECK
133These mutexes do check for usage errors.
134If an attempt is made to relock a
135.Dv PTHREAD_MUTEX_ERRORCHECK
136mutex without first dropping the lock, an error will be returned.
137If a thread attempts to unlock a
138.Dv PTHREAD_MUTEX_ERRORCHECK
139mutex that is locked by another thread, an error will be returned.
140If a thread attempts to unlock a
141.Dv PTHREAD_MUTEX_ERRORCHECK
142thread that is unlocked, an error will be returned.
143.It Dv PTHREAD_MUTEX_RECURSIVE
144These mutexes allow recursive locking.
145An attempt to relock a
146.Dv PTHREAD_MUTEX_RECURSIVE
147mutex that is already locked by the same thread succeeds.
148An equivalent number of
149.Xr pthread_mutex_unlock 3
150calls are needed before the mutex will wake another thread waiting
151on this lock.
152If a thread attempts to unlock a
153.Dv PTHREAD_MUTEX_RECURSIVE
154mutex that is locked by another thread, an error will be returned.
155If a thread attempts to unlock a
156.Dv PTHREAD_MUTEX_RECURSIVE
157thread that is unlocked, an error will be returned.
158.Pp
159It is advised that
160.Dv PTHREAD_MUTEX_RECURSIVE
161mutexes are not used with condition variables.
162This is because of the implicit unlocking done by
163.Xr pthread_cond_wait 3
164and
165.Xr pthread_cond_timedwait 3 .
166.It Dv PTHREAD_MUTEX_DEFAULT
167Also this type of mutex will cause undefined behavior if reentered.
168Unlocking a
169.Dv PTHREAD_MUTEX_DEFAULT
170mutex locked by another thread will result in undefined behavior.
171Attempts to unlock an already unlocked
172.Dv PTHREAD_MUTEX_DEFAULT
173mutex will result in undefined behavior.
174.Pp
175This is the default mutex type for
176.Fn pthread_mutexattr_init .
177.El
178.Pp
179The
180.Fn pthread_mutexattr_gettype
181functions copy the type value of the attribute to the location
182pointed to by the second parameter.
183.Pp
184The
185.Fn pthread_mutexattr_getpshared
186function obtains the value of the process-shared attribute from
187the attributes object referenced by
188.Fa attr .
189.Pp
190The
191.Fn pthread_mutexattr_setpshared
192function is used to set the process-shared attribute in an initialised
193attributes object referenced by
194.Fa attr .
195.Pp
196The
197.Fn pthread_mutexattr_getprotocol
198and
199.Fn pthread_mutexattr_setprotocol
200functions shall get and set the protocol attribute of a mutex attributes
201object pointed to by
202.Fa attr
203which was previously created by the function
204.Fn pthread_mutexattr_init .
205.Pp
206The
207.Fn pthread_mutexattr_getprioceiling
208and
209.Fn pthread_mutexattr_setprioceiling
210functions, shall get and set the priority ceiling attribute of a mutex attributes
211object pointed to by
212.Fa attr
213which was previously created by the function
214.Fn pthread_mutexattr_init .
215.Sh RETURN VALUES
216If successful, these functions return 0.
217Otherwise, an error number is returned to indicate the error.
218.Sh ERRORS
219The
220.Fn pthread_mutexattr_init
221function shall fail if:
222.Bl -tag -width Er
223.It Bq Er ENOMEM
224Insufficient memory exists to initialize the mutex attributes object.
225.El
226.Pp
227The
228.Fn pthread_mutexattr_settype
229function shall fail if:
230.Bl -tag -width Er
231.It Bq Er EINVAL
232The value specified either by
233.Fa type
234or
235.Fa attr
236is invalid.
237.El
238.Pp
239No error numbers are defined for the
240.Fn pthread_mutexattr_destroy
241and
242.Fn pthread_mutexattr_gettype
243functions.
244.Pp
245.Fn pthread_mutexattr_setprioceiling
246may fail if:
247.Bl -tag -width Er
248.It Bq Er EINVAL
249Invalid value for
250.Fa attr ,
251or invalid value for
252.Fa prioceiling .
253.El
254.Pp
255.Fn pthread_mutexattr_getprioceiling
256may fail if:
257.Bl -tag -width Er
258.It Bq Er EINVAL
259Invalid value for
260.Fa attr .
261.El
262.Pp
263.Fn pthread_mutexattr_setprotocol
264may fail if:
265.Bl -tag -width Er
266.It Bq Er EINVAL
267Invalid value for
268.Fa attr ,
269or invalid value for
270.Fa protocol .
271.El
272.Pp
273.Fn pthread_mutexattr_getprotocol
274may fail if:
275.Bl -tag -width Er
276.It Bq Er EINVAL
277Invalid value for
278.Fa attr .
279.El
280.Pp
281.Fn pthread_mutexattr_getpshared
282and
283.Fn pthread_mutexattr_setpshared
284may fail if:
285.Bl -tag -width Er
286.It Bq Er EINVAL
287the value specified by
288.Fa attr
289is invalid.
290.El
291.Sh SEE ALSO
292.Xr pthread_mutex_init 3
293.Sh STANDARDS
294These functions conform to
295.St -p1003.1-2001 .
296.Sh BUGS
297The
298.Fn pthread_mutexattr_getpshared
299and
300.Fn pthread_mutexattr_setpshared
301functions are hidden by default since only thread shared attributes
302are supported.
303