1.\" $NetBSD: pthread_mutexattr.3,v 1.10 2010/05/20 05:19:29 jruoho Exp $ 2.\" 3.\" Copyright (c) 2002 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 May 20, 2010 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.Nd mutex attribute operations 66.Sh LIBRARY 67.Lb libpthread 68.Sh SYNOPSIS 69.In pthread.h 70.Ft int 71.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 72.Ft int 73.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 74.\" .Ft int 75.\" .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling" 76.\" .Ft int 77.\" .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling" 78.\" .Ft int 79.\" .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" 80.\" .Ft int 81.\" .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol" 82.Ft int 83.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" 84.Ft int 85.Fn pthread_mutexattr_gettype "pthread_mutexattr_t * restrict attr" "int * restrict type" 86.Sh DESCRIPTION 87Mutex attributes are used to specify parameters to 88.Fn pthread_mutex_init . 89One attribute object can be used in multiple calls to 90.Fn pthread_mutex_init , 91with or without modifications between calls. 92.Pp 93The 94.Fn pthread_mutexattr_init 95function initializes 96.Fa attr 97with all the default mutex attributes. 98.Pp 99The 100.Fn pthread_mutexattr_destroy 101function destroys 102.Fa attr . 103.Pp 104The 105.Fn pthread_mutexattr_settype 106functions set the mutex 107.Fa type 108value of the attribute. 109Valid mutex types are: 110.Bl -tag -width "XXX" -offset 2n 111.It Dv PTHREAD_MUTEX_NORMAL 112This type of mutex does not check for usage errors. 113It will deadlock if reentered, and result in undefined behavior if a 114locked mutex is unlocked by another thread. 115Attempts to unlock an already unlocked 116.Dv PTHREAD_MUTEX_NORMAL 117mutex will result in undefined behavior. 118.It Dv PTHREAD_MUTEX_ERRORCHECK 119These mutexes do check for usage errors. 120If an attempt is made to relock a 121.Dv PTHREAD_MUTEX_ERRORCHECK 122mutex without first dropping the lock, an error will be returned. 123If a thread attempts to unlock a 124.Dv PTHREAD_MUTEX_ERRORCHECK 125mutex that is locked by another thread, an error will be returned. 126If a thread attempts to unlock a 127.Dv PTHREAD_MUTEX_ERRORCHECK 128thread that is unlocked, an error will be returned. 129.It Dv PTHREAD_MUTEX_RECURSIVE 130These mutexes allow recursive locking. 131An attempt to relock a 132.Dv PTHREAD_MUTEX_RECURSIVE 133mutex that is already locked by the same thread succeeds. 134An equivalent number of 135.Xr pthread_mutex_unlock 3 136calls are needed before the mutex will wake another thread waiting 137on this lock. 138If a thread attempts to unlock a 139.Dv PTHREAD_MUTEX_RECURSIVE 140mutex that is locked by another thread, an error will be returned. 141If a thread attempts to unlock a 142.Dv PTHREAD_MUTEX_RECURSIVE 143thread that is unlocked, an error will be returned. 144.Pp 145It is advised that 146.Dv PTHREAD_MUTEX_RECURSIVE 147mutexes are not used with condition variables. 148This is because of the implicit unlocking done by 149.Xr pthread_cond_wait 3 150and 151.Xr pthread_cond_timedwait 3 . 152.It Dv PTHREAD_MUTEX_DEFAULT 153Also this type of mutex will cause undefined behavior if reentered. 154Unlocking a 155.Dv PTHREAD_MUTEX_DEFAULT 156mutex locked by another thread will result in undefined behavior. 157Attempts to unlock an already unlocked 158.Dv PTHREAD_MUTEX_DEFAULT 159mutex will result in undefined behavior. 160.Pp 161This is the default mutex type for 162.Fn pthread_mutexaddr_init . 163.El 164.Pp 165The 166.Fn pthread_mutexattr_gettype 167functions copy the type value of the attribute to the location 168pointed to by the second parameter. 169.Sh RETURN VALUES 170If successful, these functions return 0. 171Otherwise, an error number is returned to indicate the error. 172.Sh ERRORS 173.Fn pthread_mutexattr_init 174shall fail if: 175.Bl -tag -width Er 176.It Bq Er ENOMEM 177Insufficient memory exists to initialize the mutex attributes object. 178.El 179.Pp 180.Fn pthread_mutexattr_settype 181shall fail if: 182.Bl -tag -width Er 183.It Bq Er EINVAL 184The value specified by 185.Fa type 186is invalid. 187.El 188.\" .Pp 189.\" .Fn pthread_mutexattr_setprioceiling 190.\" may fail if: 191.\" .Bl -tag -width Er 192.\" .It Bq Er EINVAL 193.\" Invalid value for 194.\" .Fa attr , 195.\" or invalid value for 196.\" .Fa prioceiling . 197.\" .El 198.\" .Pp 199.\" .Fn pthread_mutexattr_getprioceiling 200.\" may fail if: 201.\" .Bl -tag -width Er 202.\" .It Bq Er EINVAL 203.\" Invalid value for 204.\" .Fa attr . 205.\" .El 206.\" .Pp 207.\" .Fn pthread_mutexattr_setprotocol 208.\" may fail if: 209.\" .Bl -tag -width Er 210.\" .It Bq Er EINVAL 211.\" Invalid value for 212.\" .Fa attr , 213.\" or invalid value for 214.\" .Fa protocol . 215.\" .El 216.\" .Pp 217.\" .Fn pthread_mutexattr_getprotocol 218.\" may fail if: 219.\" .Bl -tag -width Er 220.\" .It Bq Er EINVAL 221.\" Invalid value for 222.\" .Fa attr . 223.\" .El 224.\" .Pp 225.Pp 226.Fn pthread_mutexattr_destroy , 227.Fn pthread_mutexattr_settype , 228and 229.Fn pthread_mutexattr_gettype 230may fail if: 231.Bl -tag -width Er 232.It Bq Er EINVAL 233Invalid value for 234.Fa attr . 235.El 236.Sh SEE ALSO 237.Xr pthread_mutex_init 3 238.Sh STANDARDS 239.Fn pthread_mutexattr_init , 240.Fn pthread_mutexattr_destroy , 241.Fn pthread_mutexattr_settype , 242.\" .Fn pthread_mutexattr_setprioceiling , 243.\" .Fn pthread_mutexattr_getprioceiling , 244.\" .Fn pthread_mutexattr_setprotocol , 245.\" .Fn pthread_mutexattr_getprotocol , 246and 247.Fn pthread_mutexattr_gettype 248conform to 249.St -p1003.1-96 . 250