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