1.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. 2.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" Part of this documentation was written by 6.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 7.\" from the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice(s), this list of conditions and the following disclaimer as 14.\" the first lines of this file unmodified other than the possible 15.\" addition of one or more copyright notices. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice(s), this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 22.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 24.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 25.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 28.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 29.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 30.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 31.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" $FreeBSD$ 34.Dd October 1, 2021 35.Dt PTHREAD_MUTEXATTR 3 36.Os 37.Sh NAME 38.Nm pthread_mutexattr_init , 39.Nm pthread_mutexattr_destroy , 40.Nm pthread_mutexattr_setprioceiling , 41.Nm pthread_mutexattr_getprioceiling , 42.Nm pthread_mutexattr_setprotocol , 43.Nm pthread_mutexattr_getprotocol , 44.Nm pthread_mutexattr_setpshared , 45.Nm pthread_mutexattr_getpshared , 46.Nm pthread_mutexattr_setrobust , 47.Nm pthread_mutexattr_getrobust , 48.Nm pthread_mutexattr_settype , 49.Nm pthread_mutexattr_gettype 50.Nd mutex attribute operations 51.Sh LIBRARY 52.Lb libpthread 53.Sh SYNOPSIS 54.In pthread.h 55.Ft int 56.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 57.Ft int 58.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 59.Ft int 60.Fo pthread_mutexattr_setprioceiling 61.Fa "pthread_mutexattr_t *attr" "int prioceiling" 62.Fc 63.Ft int 64.Fo pthread_mutexattr_getprioceiling 65.Fa "const pthread_mutexattr_t *attr" "int *prioceiling" 66.Fc 67.Ft int 68.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" 69.Ft int 70.Fo pthread_mutexattr_getprotocol 71.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" 72.Fc 73.Ft int 74.Fo pthread_mutexattr_setpshared 75.Fa "pthread_mutexattr_t *attr" "int shared" 76.Fc 77.Ft int 78.Fo pthread_mutexattr_getpshared 79.Fa "const pthread_mutexattr_t *attr" "int *shared" 80.Fc 81.Ft int 82.Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust" 83.Ft int 84.Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust" 85.Ft int 86.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" 87.Ft int 88.Fo pthread_mutexattr_gettype 89.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict type" 90.Fc 91.Sh DESCRIPTION 92Mutex attributes are used to specify parameters to 93.Fn pthread_mutex_init . 94One attribute object can be used in multiple calls to 95.Fn pthread_mutex_init , 96with or without modifications between calls. 97.Pp 98The 99.Fn pthread_mutexattr_init 100function initializes 101.Fa attr 102with all the default mutex attributes. 103.Pp 104The 105.Fn pthread_mutexattr_destroy 106function destroys 107.Fa attr . 108.Pp 109The 110.Fn pthread_mutexattr_setprioceiling 111function sets the priority ceiling for the mutex, used 112by threads executed under the 113.Dv PTHREAD_PRIO_PROTECT 114protocol. 115.Pp 116The 117.Fn pthread_mutexattr_setprotocol 118function specifies the protocol to be followed in utilizing mutexes. 119The 120.Fa protocol 121argument can take one of the following values: 122.Bl -tag -width PTHREAD_PRIO_PROTECT 123.It PTHREAD_PRIO_NONE 124Priority and scheduling of the thread owning this mutex is not 125affected by its mutex ownership. 126.It PTHREAD_PRIO_INHERIT 127Request priority-inheritance protocol, where the thread owning the mutex 128is executed at the highest priority among priorities of all threads waiting 129on any mutex owned by this thread. 130.It PTHREAD_PRIO_PROTECT 131Request priority-inheritance protocol, where the thread owning the mutex 132is executed at highest priority among priorities or priority ceilings of 133all threads waiting on any mutex owned by this thread. 134.El 135.Pp 136The 137.Fn pthread_mutexattr_setrobust 138function specifies robustness attribute of the mutex. 139Possible values for the 140.Fa robust 141argument are 142.Bl -tag -width PTHREAD_MUTEX_STALLED 143.It PTHREAD_MUTEX_STALLED 144No special actions are taken if the thread owning the mutex is terminated 145without unlocking the mutex lock. 146This can lead to deadlocks if no other thread can unlock the mutex. 147This is the default value. 148.It PTHREAD_MUTEX_ROBUST 149If the process containing the owning thread of a robust mutex, or owning 150thread, terminates while holding the mutex lock, the next thread that 151acquires the mutex is notified about the termination 152by the return value 153.Ev EOWNERDEAD 154from the locking function. 155Then, either 156.Xr pthread_mutex_consistent 3 157can be used to repair the mutex lock state, or 158.Xr pthread_mutex_unlock 3 159can unlock the mutex lock but also put it an unusable state, 160where all further attempts to acquire it result in the 161.Ev ENOTRECOVERABLE 162error. 163.El 164.Pp 165The 166.Fn pthread_mutexattr_settype 167function sets the type of the mutex. 168The type affects the behavior of calls which lock and unlock the mutex. 169The possible values for the 170.Fa type 171argument are 172.Bl -tag -width PTHREAD_MUTEX_ERRORCHECK 173.It PTHREAD_MUTEX_NORMAL 174Both recursive locking, and unlocking when the lock is not owned by the current 175thread, cause an error to be returned from the corresponding functions. 176This matches 177.Dv PTHREAD_MUTEX_ERRORCHECK 178but somewhat contradicts the behavior mandated by POSIX. 179.It PTHREAD_MUTEX_ERRORCHECK 180Both recursive locking, and unlocking when the lock is not owned by the current 181thread, cause an error returned from the corresponding functions. 182.It PTHREAD_MUTEX_RECURSIVE 183Recursive locking is allowed. 184Attempt to unlock when current thread is not an owner of the lock causes 185an error to be returned. 186.It PTHREAD_MUTEX_DEFAULT 187The 188.Fx 189implementation maps this type to 190.Dv PTHREAD_MUTEX_ERRORCHECK 191type. 192.El 193.Pp 194The 195.Fn pthread_mutexattr_get* 196functions copy the value of the attribute that corresponds to each function name 197to the location pointed to by the second function parameter. 198.Sh RETURN VALUES 199If successful, these functions return 0. 200Otherwise, an error number is returned to indicate the error. 201.Sh ERRORS 202The 203.Fn pthread_mutexattr_init 204function will fail if: 205.Bl -tag -width Er 206.It Bq Er ENOMEM 207Out of memory. 208.El 209.Pp 210The 211.Fn pthread_mutexattr_destroy 212function will fail if: 213.Bl -tag -width Er 214.It Bq Er EINVAL 215Invalid value for 216.Fa attr . 217.El 218.Pp 219The 220.Fn pthread_mutexattr_setprioceiling 221function will fail if: 222.Bl -tag -width Er 223.It Bq Er EINVAL 224Invalid value for 225.Fa attr , 226or invalid value for 227.Fa prioceiling . 228.El 229.Pp 230The 231.Fn pthread_mutexattr_getprioceiling 232function will fail if: 233.Bl -tag -width Er 234.It Bq Er EINVAL 235Invalid value for 236.Fa attr . 237.El 238.Pp 239The 240.Fn pthread_mutexattr_setprotocol 241function will fail if: 242.Bl -tag -width Er 243.It Bq Er EINVAL 244Invalid value for 245.Fa attr , 246or invalid value for 247.Fa protocol . 248.El 249.Pp 250The 251.Fn pthread_mutexattr_getprotocol 252function will fail if: 253.Bl -tag -width Er 254.It Bq Er EINVAL 255Invalid value for 256.Fa attr . 257.El 258.Pp 259The 260.Fn pthread_mutexattr_setpshared 261function will fail if: 262.Bl -tag -width Er 263.It Bq Er EINVAL 264Invalid value for 265.Fa attr , 266or invalid value for 267.Fa shared . 268.El 269.Pp 270The 271.Fn pthread_mutexattr_getpshared 272function will fail if: 273.Bl -tag -width Er 274.It Bq Er EINVAL 275Invalid value for 276.Fa attr . 277.El 278.Pp 279The 280.Fn pthread_mutexattr_settype 281function will fail if: 282.Bl -tag -width Er 283.It Bq Er EINVAL 284Invalid value for 285.Fa attr , 286or invalid value for 287.Fa type . 288.El 289.Pp 290The 291.Fn pthread_mutexattr_gettype 292function will fail if: 293.Bl -tag -width Er 294.It Bq Er EINVAL 295Invalid value for 296.Fa attr . 297.El 298.Pp 299The 300.Fn pthread_mutexattr_setrobust 301function will fail if: 302.Bl -tag -width Er 303.It Bq Er EINVAL 304Invalid value for 305.Fa attr , 306or invalid value for 307.Fa robust . 308.El 309.Pp 310The 311.Fn pthread_mutexattr_getrobust 312function will fail if: 313.Bl -tag -width Er 314.It Bq Er EINVAL 315Invalid value for 316.Fa attr . 317.El 318.Sh SEE ALSO 319.Xr pthread_mutex_init 3 320.Sh STANDARDS 321The 322.Fn pthread_mutexattr_init 323and 324.Fn pthread_mutexattr_destroy 325functions conform to 326.St -p1003.1-96 327.Pp 328The 329.Fn pthread_mutexattr_setprioceiling , 330.Fn pthread_mutexattr_getprioceiling , 331.Fn pthread_mutexattr_setprotocol , 332.Fn pthread_mutexattr_getprotocol , 333.Fn pthread_mutexattr_setpshared , 334.Fn pthread_mutexattr_getpshared , 335.Fn pthread_mutexattr_settype , 336and 337.Fn pthread_mutexattr_gettype 338functions conform to 339.St -susv2 . 340The 341.Fn pthread_mutexattr_setrobust 342and 343.Fn pthread_mutexattr_getrobust 344functions conform to 345.St -susv4 . 346