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 27, 2023 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_setpshared 136function sets the process-shared attribute of 137.Fa attr 138to the value specified in 139.Fa pshared . 140The argument 141.Fa pshared 142may have one of the following values: 143.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" 144.It Dv PTHREAD_PROCESS_PRIVATE 145The mutex may only be used by threads in the same process as the one 146that created the object. 147.It Dv PTHREAD_PROCESS_SHARED 148The mutex may be used by 149threads in processes other than the one that created the object, 150assuming other processes share access to the memory where the mutex 151was allocated. 152.El 153See 154.Xr libthr 3 155for details of the implementation of the shared mutexes, 156and their limitations. 157.Pp 158The 159.Fn pthread_mutexattr_setrobust 160function specifies robustness attribute of the mutex. 161Possible values for the 162.Fa robust 163argument are 164.Bl -tag -width PTHREAD_MUTEX_STALLED 165.It PTHREAD_MUTEX_STALLED 166No special actions are taken if the thread owning the mutex is terminated 167without unlocking the mutex lock. 168This can lead to deadlocks if no other thread can unlock the mutex. 169This is the default value. 170.It PTHREAD_MUTEX_ROBUST 171If the process containing the owning thread of a robust mutex, or owning 172thread, terminates while holding the mutex lock, the next thread that 173acquires the mutex is notified about the termination 174by the return value 175.Ev EOWNERDEAD 176from the locking function. 177Then, either 178.Xr pthread_mutex_consistent 3 179can be used to repair the mutex lock state, or 180.Xr pthread_mutex_unlock 3 181can unlock the mutex lock but also put it an unusable state, 182where all further attempts to acquire it result in the 183.Ev ENOTRECOVERABLE 184error. 185.El 186.Pp 187The 188.Fn pthread_mutexattr_settype 189function sets the type of the mutex. 190The type affects the behavior of calls which lock and unlock the mutex. 191The possible values for the 192.Fa type 193argument are 194.Bl -tag -width PTHREAD_MUTEX_ERRORCHECK 195.It PTHREAD_MUTEX_NORMAL 196Both recursive locking, and unlocking when the lock is not owned by the current 197thread, cause an error to be returned from the corresponding functions. 198This matches 199.Dv PTHREAD_MUTEX_ERRORCHECK 200but somewhat contradicts the behavior mandated by POSIX. 201.It PTHREAD_MUTEX_ERRORCHECK 202Both recursive locking, and unlocking when the lock is not owned by the current 203thread, cause an error returned from the corresponding functions. 204.It PTHREAD_MUTEX_RECURSIVE 205Recursive locking is allowed. 206Attempt to unlock when current thread is not an owner of the lock causes 207an error to be returned. 208.It PTHREAD_MUTEX_DEFAULT 209The 210.Fx 211implementation maps this type to 212.Dv PTHREAD_MUTEX_ERRORCHECK 213type. 214.El 215.Pp 216The 217.Fn pthread_mutexattr_get* 218functions copy the value of the attribute that corresponds to each function name 219to the location pointed to by the second function parameter. 220.Sh RETURN VALUES 221If successful, these functions return 0. 222Otherwise, an error number is returned to indicate the error. 223.Sh ERRORS 224The 225.Fn pthread_mutexattr_init 226function will fail if: 227.Bl -tag -width Er 228.It Bq Er ENOMEM 229Out of memory. 230.El 231.Pp 232The 233.Fn pthread_mutexattr_destroy 234function will fail if: 235.Bl -tag -width Er 236.It Bq Er EINVAL 237Invalid value for 238.Fa attr . 239.El 240.Pp 241The 242.Fn pthread_mutexattr_setprioceiling 243function will fail if: 244.Bl -tag -width Er 245.It Bq Er EINVAL 246Invalid value for 247.Fa attr , 248or invalid value for 249.Fa prioceiling . 250.El 251.Pp 252The 253.Fn pthread_mutexattr_getprioceiling 254function will fail if: 255.Bl -tag -width Er 256.It Bq Er EINVAL 257Invalid value for 258.Fa attr . 259.El 260.Pp 261The 262.Fn pthread_mutexattr_setprotocol 263function will fail if: 264.Bl -tag -width Er 265.It Bq Er EINVAL 266Invalid value for 267.Fa attr , 268or invalid value for 269.Fa protocol . 270.El 271.Pp 272The 273.Fn pthread_mutexattr_getprotocol 274function will fail if: 275.Bl -tag -width Er 276.It Bq Er EINVAL 277Invalid value for 278.Fa attr . 279.El 280.Pp 281The 282.Fn pthread_mutexattr_setpshared 283function will fail if: 284.Bl -tag -width Er 285.It Bq Er EINVAL 286Invalid value for 287.Fa attr , 288or invalid value for 289.Fa shared . 290.El 291.Pp 292The 293.Fn pthread_mutexattr_getpshared 294function will fail if: 295.Bl -tag -width Er 296.It Bq Er EINVAL 297Invalid value for 298.Fa attr . 299.El 300.Pp 301The 302.Fn pthread_mutexattr_settype 303function will fail if: 304.Bl -tag -width Er 305.It Bq Er EINVAL 306Invalid value for 307.Fa attr , 308or invalid value for 309.Fa type . 310.El 311.Pp 312The 313.Fn pthread_mutexattr_gettype 314function will fail if: 315.Bl -tag -width Er 316.It Bq Er EINVAL 317Invalid value for 318.Fa attr . 319.El 320.Pp 321The 322.Fn pthread_mutexattr_setrobust 323function will fail if: 324.Bl -tag -width Er 325.It Bq Er EINVAL 326Invalid value for 327.Fa attr , 328or invalid value for 329.Fa robust . 330.El 331.Pp 332The 333.Fn pthread_mutexattr_getrobust 334function will fail if: 335.Bl -tag -width Er 336.It Bq Er EINVAL 337Invalid value for 338.Fa attr . 339.El 340.Sh SEE ALSO 341.Xr libthr 3 , 342.Xr pthread_mutex_init 3 343.Sh STANDARDS 344The 345.Fn pthread_mutexattr_init 346and 347.Fn pthread_mutexattr_destroy 348functions conform to 349.St -p1003.1-96 350.Pp 351The 352.Fn pthread_mutexattr_setprioceiling , 353.Fn pthread_mutexattr_getprioceiling , 354.Fn pthread_mutexattr_setprotocol , 355.Fn pthread_mutexattr_getprotocol , 356.Fn pthread_mutexattr_setpshared , 357.Fn pthread_mutexattr_getpshared , 358.Fn pthread_mutexattr_settype , 359and 360.Fn pthread_mutexattr_gettype 361functions conform to 362.St -susv2 . 363The 364.Fn pthread_mutexattr_setrobust 365and 366.Fn pthread_mutexattr_getrobust 367functions conform to 368.St -susv4 . 369