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.Dd October 1, 2021 33.Dt PTHREAD_MUTEXATTR 3 34.Os 35.Sh NAME 36.Nm pthread_mutexattr_init , 37.Nm pthread_mutexattr_destroy , 38.Nm pthread_mutexattr_setprioceiling , 39.Nm pthread_mutexattr_getprioceiling , 40.Nm pthread_mutexattr_setprotocol , 41.Nm pthread_mutexattr_getprotocol , 42.Nm pthread_mutexattr_setpshared , 43.Nm pthread_mutexattr_getpshared , 44.Nm pthread_mutexattr_setrobust , 45.Nm pthread_mutexattr_getrobust , 46.Nm pthread_mutexattr_settype , 47.Nm pthread_mutexattr_gettype 48.Nd mutex attribute operations 49.Sh LIBRARY 50.Lb libpthread 51.Sh SYNOPSIS 52.In pthread.h 53.Ft int 54.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 55.Ft int 56.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 57.Ft int 58.Fo pthread_mutexattr_setprioceiling 59.Fa "pthread_mutexattr_t *attr" "int prioceiling" 60.Fc 61.Ft int 62.Fo pthread_mutexattr_getprioceiling 63.Fa "const pthread_mutexattr_t *attr" "int *prioceiling" 64.Fc 65.Ft int 66.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" 67.Ft int 68.Fo pthread_mutexattr_getprotocol 69.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" 70.Fc 71.Ft int 72.Fo pthread_mutexattr_setpshared 73.Fa "pthread_mutexattr_t *attr" "int shared" 74.Fc 75.Ft int 76.Fo pthread_mutexattr_getpshared 77.Fa "const pthread_mutexattr_t *attr" "int *shared" 78.Fc 79.Ft int 80.Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust" 81.Ft int 82.Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust" 83.Ft int 84.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" 85.Ft int 86.Fo pthread_mutexattr_gettype 87.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict type" 88.Fc 89.Sh DESCRIPTION 90Mutex attributes are used to specify parameters to 91.Fn pthread_mutex_init . 92One attribute object can be used in multiple calls to 93.Fn pthread_mutex_init , 94with or without modifications between calls. 95.Pp 96The 97.Fn pthread_mutexattr_init 98function initializes 99.Fa attr 100with all the default mutex attributes. 101.Pp 102The 103.Fn pthread_mutexattr_destroy 104function destroys 105.Fa attr . 106.Pp 107The 108.Fn pthread_mutexattr_setprioceiling 109function sets the priority ceiling for the mutex, used 110by threads executed under the 111.Dv PTHREAD_PRIO_PROTECT 112protocol. 113.Pp 114The 115.Fn pthread_mutexattr_setprotocol 116function specifies the protocol to be followed in utilizing mutexes. 117The 118.Fa protocol 119argument can take one of the following values: 120.Bl -tag -width PTHREAD_PRIO_PROTECT 121.It PTHREAD_PRIO_NONE 122Priority and scheduling of the thread owning this mutex is not 123affected by its mutex ownership. 124.It PTHREAD_PRIO_INHERIT 125Request priority-inheritance protocol, where the thread owning the mutex 126is executed at the highest priority among priorities of all threads waiting 127on any mutex owned by this thread. 128.It PTHREAD_PRIO_PROTECT 129Request priority-inheritance protocol, where the thread owning the mutex 130is executed at highest priority among priorities or priority ceilings of 131all threads waiting on any mutex owned by this thread. 132.El 133.Pp 134The 135.Fn pthread_mutexattr_setrobust 136function specifies robustness attribute of the mutex. 137Possible values for the 138.Fa robust 139argument are 140.Bl -tag -width PTHREAD_MUTEX_STALLED 141.It PTHREAD_MUTEX_STALLED 142No special actions are taken if the thread owning the mutex is terminated 143without unlocking the mutex lock. 144This can lead to deadlocks if no other thread can unlock the mutex. 145This is the default value. 146.It PTHREAD_MUTEX_ROBUST 147If the process containing the owning thread of a robust mutex, or owning 148thread, terminates while holding the mutex lock, the next thread that 149acquires the mutex is notified about the termination 150by the return value 151.Ev EOWNERDEAD 152from the locking function. 153Then, either 154.Xr pthread_mutex_consistent 3 155can be used to repair the mutex lock state, or 156.Xr pthread_mutex_unlock 3 157can unlock the mutex lock but also put it an unusable state, 158where all further attempts to acquire it result in the 159.Ev ENOTRECOVERABLE 160error. 161.El 162.Pp 163The 164.Fn pthread_mutexattr_settype 165function sets the type of the mutex. 166The type affects the behavior of calls which lock and unlock the mutex. 167The possible values for the 168.Fa type 169argument are 170.Bl -tag -width PTHREAD_MUTEX_ERRORCHECK 171.It PTHREAD_MUTEX_NORMAL 172Both recursive locking, and unlocking when the lock is not owned by the current 173thread, cause an error to be returned from the corresponding functions. 174This matches 175.Dv PTHREAD_MUTEX_ERRORCHECK 176but somewhat contradicts the behavior mandated by POSIX. 177.It PTHREAD_MUTEX_ERRORCHECK 178Both recursive locking, and unlocking when the lock is not owned by the current 179thread, cause an error returned from the corresponding functions. 180.It PTHREAD_MUTEX_RECURSIVE 181Recursive locking is allowed. 182Attempt to unlock when current thread is not an owner of the lock causes 183an error to be returned. 184.It PTHREAD_MUTEX_DEFAULT 185The 186.Fx 187implementation maps this type to 188.Dv PTHREAD_MUTEX_ERRORCHECK 189type. 190.El 191.Pp 192The 193.Fn pthread_mutexattr_get* 194functions copy the value of the attribute that corresponds to each function name 195to the location pointed to by the second function parameter. 196.Sh RETURN VALUES 197If successful, these functions return 0. 198Otherwise, an error number is returned to indicate the error. 199.Sh ERRORS 200The 201.Fn pthread_mutexattr_init 202function will fail if: 203.Bl -tag -width Er 204.It Bq Er ENOMEM 205Out of memory. 206.El 207.Pp 208The 209.Fn pthread_mutexattr_destroy 210function will fail if: 211.Bl -tag -width Er 212.It Bq Er EINVAL 213Invalid value for 214.Fa attr . 215.El 216.Pp 217The 218.Fn pthread_mutexattr_setprioceiling 219function will fail if: 220.Bl -tag -width Er 221.It Bq Er EINVAL 222Invalid value for 223.Fa attr , 224or invalid value for 225.Fa prioceiling . 226.El 227.Pp 228The 229.Fn pthread_mutexattr_getprioceiling 230function will fail if: 231.Bl -tag -width Er 232.It Bq Er EINVAL 233Invalid value for 234.Fa attr . 235.El 236.Pp 237The 238.Fn pthread_mutexattr_setprotocol 239function will fail if: 240.Bl -tag -width Er 241.It Bq Er EINVAL 242Invalid value for 243.Fa attr , 244or invalid value for 245.Fa protocol . 246.El 247.Pp 248The 249.Fn pthread_mutexattr_getprotocol 250function will fail if: 251.Bl -tag -width Er 252.It Bq Er EINVAL 253Invalid value for 254.Fa attr . 255.El 256.Pp 257The 258.Fn pthread_mutexattr_setpshared 259function will fail if: 260.Bl -tag -width Er 261.It Bq Er EINVAL 262Invalid value for 263.Fa attr , 264or invalid value for 265.Fa shared . 266.El 267.Pp 268The 269.Fn pthread_mutexattr_getpshared 270function will fail if: 271.Bl -tag -width Er 272.It Bq Er EINVAL 273Invalid value for 274.Fa attr . 275.El 276.Pp 277The 278.Fn pthread_mutexattr_settype 279function will fail if: 280.Bl -tag -width Er 281.It Bq Er EINVAL 282Invalid value for 283.Fa attr , 284or invalid value for 285.Fa type . 286.El 287.Pp 288The 289.Fn pthread_mutexattr_gettype 290function will fail if: 291.Bl -tag -width Er 292.It Bq Er EINVAL 293Invalid value for 294.Fa attr . 295.El 296.Pp 297The 298.Fn pthread_mutexattr_setrobust 299function will fail if: 300.Bl -tag -width Er 301.It Bq Er EINVAL 302Invalid value for 303.Fa attr , 304or invalid value for 305.Fa robust . 306.El 307.Pp 308The 309.Fn pthread_mutexattr_getrobust 310function will fail if: 311.Bl -tag -width Er 312.It Bq Er EINVAL 313Invalid value for 314.Fa attr . 315.El 316.Sh SEE ALSO 317.Xr pthread_mutex_init 3 318.Sh STANDARDS 319The 320.Fn pthread_mutexattr_init 321and 322.Fn pthread_mutexattr_destroy 323functions conform to 324.St -p1003.1-96 325.Pp 326The 327.Fn pthread_mutexattr_setprioceiling , 328.Fn pthread_mutexattr_getprioceiling , 329.Fn pthread_mutexattr_setprotocol , 330.Fn pthread_mutexattr_getprotocol , 331.Fn pthread_mutexattr_setpshared , 332.Fn pthread_mutexattr_getpshared , 333.Fn pthread_mutexattr_settype , 334and 335.Fn pthread_mutexattr_gettype 336functions conform to 337.St -susv2 . 338The 339.Fn pthread_mutexattr_setrobust 340and 341.Fn pthread_mutexattr_getrobust 342functions conform to 343.St -susv4 . 344