1.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice(s), this list of conditions and the following disclaimer as
9.\"    the first lines of this file unmodified other than the possible
10.\"    addition of one or more copyright notices.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice(s), this list of conditions and the following disclaimer in
13.\"    the documentation and/or other materials provided with the
14.\"    distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
20.\" 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
23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\"
28.\" $FreeBSD: src/share/man/man3/pthread_mutexattr.3,v 1.13 2007/10/22 10:08:00 ru Exp $
29.\"
30.Dd March 3, 2018
31.Dt PTHREAD_MUTEXATTR 3
32.Os
33.Sh NAME
34.Nm pthread_mutexattr_init ,
35.Nm pthread_mutexattr_destroy ,
36.Nm pthread_mutexattr_setprioceiling ,
37.Nm pthread_mutexattr_getprioceiling ,
38.Nm pthread_mutexattr_setprotocol ,
39.Nm pthread_mutexattr_getprotocol ,
40.Nm pthread_mutexattr_settype ,
41.Nm pthread_mutexattr_gettype ,
42.Nm pthread_mutexattr_getpshared ,
43.Nm pthread_mutexattr_setpshared
44.Nd mutex attribute operations
45.Sh LIBRARY
46.Lb libpthread
47.Sh SYNOPSIS
48.In pthread.h
49.Ft int
50.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
51.Ft int
52.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
53.Ft int
54.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
55.Ft int
56.Fn pthread_mutexattr_getprioceiling "const pthread_mutexattr_t * restrict attr" "int * restrict prioceiling"
57.Ft int
58.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
59.Ft int
60.Fn pthread_mutexattr_getprotocol "const pthread_mutexattr_t * restrict attr" "int * restrict protocol"
61.Ft int
62.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
63.Ft int
64.Fn pthread_mutexattr_gettype "const pthread_mutexattr_t * restrict attr" "int * restrict type"
65.Ft int
66.Fn pthread_mutexattr_setpshared "pthread_mutexattr_t *attr" "int pshared"
67.Ft int
68.Fn pthread_mutexattr_getpshared "const pthread_mutexattr_t * restrict attr" "int * restrict pshared"
69.Sh DESCRIPTION
70Mutex attributes are used to specify parameters to
71.Fn pthread_mutex_init .
72One attribute object can be used in multiple calls to
73.Fn pthread_mutex_init ,
74with or without modifications between calls.
75.Pp
76The
77.Fn pthread_mutexattr_init
78function initializes
79.Fa attr
80with all the default mutex attributes.
81.Pp
82The
83.Fn pthread_mutexattr_destroy
84function destroys
85.Fa attr .
86.Pp
87The
88.Fn pthread_mutexattr_set*
89functions set the attribute that corresponds to each function name.
90Note that the
91.Fn pthread_mutexattr_setpshared
92function only supports
93.Dv PTHREAD_PROCESS_PRIVATE
94at the moment.
95.Pp
96The
97.Fn pthread_mutexattr_get*
98functions copy the value of the attribute that corresponds to each function name
99to the location pointed to by the second function parameter.
100.Sh RETURN VALUES
101If successful, these functions return 0.
102Otherwise, an error number is returned to indicate the error.
103.Sh ERRORS
104The
105.Fn pthread_mutexattr_init
106function will fail if:
107.Bl -tag -width Er
108.It Bq Er ENOMEM
109Out of memory.
110.El
111.Pp
112The
113.Fn pthread_mutexattr_destroy
114function will fail if:
115.Bl -tag -width Er
116.It Bq Er EINVAL
117Invalid value for
118.Fa attr .
119.El
120.Pp
121The
122.Fn pthread_mutexattr_setprioceiling
123function will fail if:
124.Bl -tag -width Er
125.It Bq Er EINVAL
126Invalid value for
127.Fa attr ,
128or invalid value for
129.Fa prioceiling .
130.El
131.Pp
132The
133.Fn pthread_mutexattr_getprioceiling
134function will fail if:
135.Bl -tag -width Er
136.It Bq Er EINVAL
137Invalid value for
138.Fa attr .
139.El
140.Pp
141The
142.Fn pthread_mutexattr_setprotocol
143function will fail if:
144.Bl -tag -width Er
145.It Bq Er EINVAL
146Invalid value for
147.Fa attr ,
148or invalid value for
149.Fa protocol .
150.El
151.Pp
152The
153.Fn pthread_mutexattr_getprotocol
154function will fail if:
155.Bl -tag -width Er
156.It Bq Er EINVAL
157Invalid value for
158.Fa attr .
159.El
160.Pp
161The
162.Fn pthread_mutexattr_getpshared
163and
164.Fn pthread_mutexattr_setpshared
165functions will fail if:
166.Bl -tag -width Er
167.It Bq Er EINVAL
168The value specified by
169.Fa attr
170is invalid.
171.El
172.Pp
173The
174.Fn pthread_mutexattr_settype
175function will fail if:
176.Bl -tag -width Er
177.It Bq Er EINVAL
178Invalid value for
179.Fa attr ,
180or invalid value for
181.Fa type .
182.El
183.Pp
184The
185.Fn pthread_mutexattr_gettype
186function will fail if:
187.Bl -tag -width Er
188.It Bq Er EINVAL
189Invalid value for
190.Fa attr .
191.El
192.Sh SEE ALSO
193.Xr pthread_mutex_init 3
194.Sh STANDARDS
195The
196.Fn pthread_mutexattr_init
197and
198.Fn pthread_mutexattr_destroy
199functions conform to
200.St -p1003.1-96 .
201.Pp
202The
203.Fn pthread_mutexattr_setprioceiling ,
204.Fn pthread_mutexattr_getprioceiling ,
205.Fn pthread_mutexattr_setprotocol ,
206.Fn pthread_mutexattr_getprotocol ,
207.Fn pthread_mutexattr_settype ,
208and
209.Fn pthread_mutexattr_gettype
210functions conform to
211.St -susv2 .
212