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