1.\" $NetBSD: pthread_mutexattr.3,v 1.9 2009/04/11 16:51:39 wiz 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 January 30, 2003 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 type value of the attribute. 107Valid mutex types are: 108.Dv PTHREAD_MUTEX_NORMAL , 109.Dv PTHREAD_MUTEX_ERRORCHECK , 110.Dv PTHREAD_MUTEX_RECURSIVE , 111and 112.Dv PTHREAD_MUTEX_DEFAULT . 113The default mutex type for 114.Fn pthread_mutexaddr_init 115is 116.Dv PTHREAD_MUTEX_DEFAULT . 117.Pp 118.Dv PTHREAD_MUTEX_NORMAL 119mutexes do not check for usage errors. 120.Dv PTHREAD_MUTEX_NORMAL 121mutexes will deadlock if reentered, and result in undefined behavior if a 122locked mutex is unlocked by another thread. 123Attempts to unlock an already unlocked 124.Dv PTHREAD_MUTEX_NORMAL 125mutex will result in undefined behavior. 126.Pp 127.Dv PTHREAD_MUTEX_ERRORCHECK 128mutexes do check for usage errors. 129If an attempt is made to relock a 130.Dv PTHREAD_MUTEX_ERRORCHECK 131mutex without first dropping the lock an error will be returned. 132If a thread attempts to unlock a 133.Dv PTHREAD_MUTEX_ERRORCHECK 134mutex that is locked by another thread, an error will be returned. 135If a thread attempts to unlock a 136.Dv PTHREAD_MUTEX_ERRORCHECK 137thread that is unlocked, an error will be 138returned. 139.Pp 140.Dv PTHREAD_MUTEX_RECURSIVE 141mutexes allow recursive locking. 142An attempt to relock a 143.Dv PTHREAD_MUTEX_RECURSIVE 144mutex that is already locked by the same thread succeeds. 145An equivalent number of 146.Xr pthread_mutex_unlock 3 147calls are needed before the mutex will wake another thread waiting 148on this lock. 149If a thread attempts to unlock a 150.Dv PTHREAD_MUTEX_RECURSIVE 151mutex that is locked by another thread, an error will be returned. 152If a thread attempts to unlock a 153.Dv PTHREAD_MUTEX_RECURSIVE 154thread that is unlocked, an error will be returned. 155.Pp 156.Dv PTHREAD_MUTEX_DEFAULT 157mutexes result in undefined behavior if reentered. 158Unlocking a 159.Dv PTHREAD_MUTEX_DEFAULT 160mutex locked by another thread will result in undefined behavior. 161Attempts to unlock an already unlocked 162.Dv PTHREAD_MUTEX_DEFAULT 163mutex will result in undefined behavior. 164.Pp 165.Fn pthread_mutexattr_gettype 166functions copy the type value of the attribute to the location 167pointed to by the second parameter. 168.Sh RETURN VALUES 169If successful, these functions return 0. 170Otherwise, an error number is returned to indicate the error. 171.Sh ERRORS 172.Fn pthread_mutexattr_init 173shall fail if: 174.Bl -tag -width Er 175.It Bq Er ENOMEM 176Insufficient memory exists to initialize the mutex attributes object. 177.El 178.Pp 179.Fn pthread_mutexattr_settype 180shall fail if: 181.Bl -tag -width Er 182.It Bq Er EINVAL 183The value specified by 184.Fa type 185is invalid. 186.El 187.\" .Pp 188.\" .Fn pthread_mutexattr_setprioceiling 189.\" may fail if: 190.\" .Bl -tag -width Er 191.\" .It Bq Er EINVAL 192.\" Invalid value for 193.\" .Fa attr , 194.\" or invalid value for 195.\" .Fa prioceiling . 196.\" .El 197.\" .Pp 198.\" .Fn pthread_mutexattr_getprioceiling 199.\" may fail if: 200.\" .Bl -tag -width Er 201.\" .It Bq Er EINVAL 202.\" Invalid value for 203.\" .Fa attr . 204.\" .El 205.\" .Pp 206.\" .Fn pthread_mutexattr_setprotocol 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 protocol . 214.\" .El 215.\" .Pp 216.\" .Fn pthread_mutexattr_getprotocol 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.Pp 225.Fn pthread_mutexattr_destroy , 226.Fn pthread_mutexattr_settype , 227and 228.Fn pthread_mutexattr_gettype 229may fail if: 230.Bl -tag -width Er 231.It Bq Er EINVAL 232Invalid value for 233.Fa attr . 234.El 235.Sh SEE ALSO 236.Xr pthread_mutex_init 3 237.Sh STANDARDS 238.Fn pthread_mutexattr_init , 239.Fn pthread_mutexattr_destroy , 240.Fn pthread_mutexattr_settype , 241.\" .Fn pthread_mutexattr_setprioceiling , 242.\" .Fn pthread_mutexattr_getprioceiling , 243.\" .Fn pthread_mutexattr_setprotocol , 244.\" .Fn pthread_mutexattr_getprotocol , 245and 246.Fn pthread_mutexattr_gettype 247conform to 248.St -p1003.1-96 . 249