1.\" $NetBSD: pthread_mutex.3,v 1.9 2016/10/30 23:26:33 kamil Exp $ 2.\" 3.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> 28.\" All rights reserved. 29.\" 30.\" Redistribution and use in source and binary forms, with or without 31.\" modification, are permitted provided that the following conditions 32.\" are met: 33.\" 1. Redistributions of source code must retain the above copyright 34.\" notice, this list of conditions and the following disclaimer. 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in the 37.\" documentation and/or other materials provided with the distribution. 38.\" 3. Neither the name of the author nor the names of any co-contributors 39.\" may be used to endorse or promote products derived from this software 40.\" without specific prior written permission. 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 43.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 45.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 46.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 47.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 48.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 50.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 51.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 52.\" SUCH DAMAGE. 53.\" 54.\" ---------------------------------------------------------------------------- 55.Dd June 12, 2016 56.Dt PTHREAD_MUTEX 3 57.Os 58.Sh NAME 59.Nm pthread_mutex 60.Nd mutual exclusion primitives 61.Sh LIBRARY 62.Lb libpthread 63.\" ---------------------------------------------------------------------------- 64.Sh SYNOPSIS 65.In pthread.h 66.Ft int 67.Fn pthread_mutex_init "pthread_mutex_t * restrict mutex" \ 68"const pthread_mutexattr_t * restrict attr" 69.Vt pthread_mutex_t mutex No = Dv PTHREAD_MUTEX_INITIALIZER ; 70.Ft int 71.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 72.Ft int 73.Fn pthread_mutex_lock "pthread_mutex_t *mutex" 74.Ft int 75.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 76.Ft int 77.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 78.Ft int 79.Fn pthread_mutex_timedlock "pthread_mutex_t *__restrict mutex" "const struct timespec *__restrict timeout" 80.Ft int 81.Fn pthread_mutex_getprioceiling "const pthread_mutex_t * __restrict mutex" "int * __restrict prioceiling" 82.Ft int 83.Fn pthread_mutex_setprioceiling "pthread_mutex_t * __restrict mutex" \ 84"int prioceiling" "int * __restrict old_ceiling" 85.\" ---------------------------------------------------------------------------- 86.Sh DESCRIPTION 87The 88.Fn pthread_mutex_init 89function creates a new mutex, with attributes specified with 90.Fa attr . 91If 92.Fa attr 93is 94.Dv NULL , 95the default attributes are used. 96.Pp 97The macro 98.Dv PTHREAD_MUTEX_INITIALIZER 99can be used to initialize a mutex when the default attributes are 100appropriate and the mutex can be statically allocated. 101The behavior is similar to 102.Fn pthread_mutex_init 103with 104.Fa attr 105specified as 106.Dv NULL , 107except that no error checking is done. 108.Pp 109.\" ----- 110The 111.Fn pthread_mutex_destroy 112function frees the resources allocated for 113.Fa mutex . 114It is possible to reinitialize a destroyed mutex, but undefined 115behavior may follow if the destroyed object is otherwise referenced. 116.Pp 117.\" ----- 118The 119.Fn pthread_mutex_lock 120function locks 121.Fa mutex . 122If the mutex is already locked, the calling thread will block until the 123mutex becomes available. 124The error conditions may vary depending on the type of the mutex; see 125.Xr pthread_mutexattr 3 126for additional details. 127.Pp 128The 129.Fn pthread_mutex_trylock 130function locks 131.Fa mutex . 132If the mutex is already locked, 133.Fn pthread_mutex_trylock 134will not block waiting for the mutex, but will return an error condition. 135.Pp 136.\" ----- 137The 138.Fn pthread_mutex_unlock 139function unlocks an acquired 140.Fa mutex . 141When operating with the default mutex type, 142undefined behavior follows if a thread tries to unlock a mutex 143that has not been locked by it, or if a thread tries to release 144a mutex that is already unlocked. 145.Pp 146.\" ----- 147The 148.Fn pthread_mutex_timedlock 149function shall lock the mutex object referenced by 150.Fa mutex . 151If the mutex is already locked, the calling thread shall block until 152the mutex becomes available in the 153.Fn pthread_mutex_lock 154function. 155If the mutex cannot be locked without waiting for another thread to 156unlock the mutex, this wait shall be terminated when the specified timeout 157expires. 158The timeout shall expire when the absolute time specified by 159.Fa timeout 160passes, as measured by the clock on which timeouts are based. 161.Pp 162.\" ----- 163The 164.Fn pthread_mutex_getprioceiling 165function shall return the current priority ceiling of the mutex. 166.Pp 167.\" ----- 168The 169.Fn pthread_mutex_setprioceiling 170function shall either lock the mutex if it is unlocked, or block until 171it can sucessfully lock the mutex, then it shall change the mutex's priority 172ceiling and release the mutex. 173When the change is successful, the previous value of the priority ceiling 174shall be returned 175in 176.Fa old_ceiling . 177The process of locking the mutex need not adhere to the priority 178protect protocol. 179If 180.Fn pthread_mutex_setprioceiling 181function fails, the mutex priority ceiling shall not be changed. 182.\" ---------------------------------------------------------------------------- 183.Sh RETURN VALUES 184Upon success all described functions return zero. 185Otherwise, an error number will be returned to indicate the error. 186.Sh ERRORS 187.Fn pthread_mutex_init 188may fail if: 189.Bl -tag -width Er 190.It Bq Er EAGAIN 191The system lacks the resources to initialize another mutex. 192.It Bq Er EINVAL 193The value specified by 194.Fa attr 195is invalid. 196.It Bq Er ENOMEM 197The process cannot allocate enough memory to initialize another mutex. 198.El 199.Pp 200.\" ----- 201.Fn pthread_mutex_destroy 202may fail if: 203.Bl -tag -width Er 204.It Bq Er EBUSY 205.Fa Mutex 206is locked by another thread. 207.It Bq Er EINVAL 208The value specified by 209.Fa mutex 210is invalid. 211.El 212.Pp 213.\" ----- 214.Fn pthread_mutex_lock 215may fail if: 216.Bl -tag -width Er 217.It Bq Er EDEADLK 218A deadlock would occur if the thread blocked waiting for 219.Fa mutex . 220.It Bq Er EINVAL 221The value specified by 222.Fa mutex 223is invalid. 224.El 225.Pp 226.Fn pthread_mutex_trylock 227may fail if: 228.Bl -tag -width Er 229.It Bq Er EBUSY 230.Fa Mutex 231is already locked. 232.It Bq Er EINVAL 233The value specified by 234.Fa mutex 235is invalid. 236.El 237.Pp 238.\" ----- 239.Fn pthread_mutex_unlock 240may fail if: 241.Bl -tag -width Er 242.It Bq Er EINVAL 243The value specified by 244.Fa mutex 245is invalid. 246.It Bq Er EPERM 247The current thread does not hold a lock on 248.Fa mutex . 249.El 250.Pp 251.\" ----- 252.Fn pthread_mutex_timedlock 253may fail if: 254.Bl -tag -width Er 255.It Bq Er EINVAL 256The mutex was created with the protocol attribute having the value 257.Dv PTHREAD_PRIO_PROTECT 258and the calling thread's priority is higher than 259the mutex current priority ceiling; or 260the process or thread would have blocked, and the 261.Fa timeout 262parameter specified a nanoseconds field value less than zero or greater 263than or equal to 1000 million. 264.It Bq Er ETIMEDOUT 265The mutex could not be locked before the specified timeout expired. 266.El 267.Pp 268.\" ----- 269The 270.Fn pthread_mutex_getprioceiling 271and 272.Fn pthread_mutex_setprioceiling 273functions may fail if: 274.Bl -tag -width Er 275.It Bq Er EINVAL 276The priority requested by 277.Fa prioceiling 278is out of range; or 279the value specified by 280.Fa mutex 281does not refer to a currently existing mutex. 282.It Bq Er EPERM 283The caller does not have the privilege to perform the operation. 284.El 285.\" ---------------------------------------------------------------------------- 286.Sh SEE ALSO 287.Xr pthread 3 , 288.Xr pthread_barrier 3 , 289.Xr pthread_cond 3 , 290.Xr pthread_mutexattr 3 , 291.Xr pthread_rwlock 3 , 292.Xr pthread_spin 3 293.\" ---------------------------------------------------------------------------- 294.Sh STANDARDS 295These functions conform to 296.St -p1003.1-2001 . 297