1.\" $NetBSD: pthread_mutex.3,v 1.5 2010/07/09 10:55:11 wiz 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 July 8, 2010 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.Ft int 70.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 71.Ft int 72.Fn pthread_mutex_lock "pthread_mutex_t *mutex" 73.Ft int 74.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 75.Ft int 76.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 77.Pp 78.Va pthread_mutex_t mutex = Dv PTHREAD_MUTEX_INITIALIZER; 79.\" ---------------------------------------------------------------------------- 80.Sh DESCRIPTION 81The 82.Fn pthread_mutex_init 83function creates a new mutex, with attributes specified with 84.Fa attr . 85If 86.Fa attr 87is 88.Dv NULL , 89the default attributes are used. 90.Pp 91The macro 92.Dv PTHREAD_MUTEX_INITIALIZER 93can be used to initialize a mutex when the default attributes are 94appropriate and the mutex can be statically allocated. 95The behavior is similar to 96.Fn pthread_mutex_init 97with 98.Fa attr 99specified as 100.Dv NULL , 101except that no error checking is done. 102.Pp 103.\" ----- 104The 105.Fn pthread_mutex_destroy 106function frees the resources allocated for 107.Fa mutex . 108It is possible to reinitialize a destroyed mutex, but undefined 109behavior may follow if the destroyed object is otherwise referenced. 110.Pp 111.\" ----- 112The 113.Fn pthread_mutex_lock 114function locks 115.Fa mutex . 116If the mutex is already locked, the calling thread will block until the 117mutex becomes available. 118The error conditions may vary depending on the type of the mutex; see 119.Xr pthread_mutexattr 3 120for additional details. 121.Pp 122The 123.Fn pthread_mutex_trylock 124function locks 125.Fa mutex . 126If the mutex is already locked, 127.Fn pthread_mutex_trylock 128will not block waiting for the mutex, but will return an error condition. 129.Pp 130.\" ----- 131The 132.Fn pthread_mutex_unlock 133function unlocks an acquired 134.Fa mutex . 135When operating with the default mutex type, 136undefined behavior follows if a thread tries to unlock a mutex 137that has not been locked by it, or if a thread tries to release 138a mutex that is already unlocked. 139.\" ---------------------------------------------------------------------------- 140.Sh RETURN VALUES 141Upon success all described functions return zero. 142Otherwise, an error number will be returned to indicate the error. 143.Sh ERRORS 144.Fn pthread_mutex_init 145may fail if: 146.Bl -tag -width Er 147.It Bq Er EAGAIN 148The system lacks the resources to initialize another mutex. 149.It Bq Er EINVAL 150The value specified by 151.Fa attr 152is invalid. 153.It Bq Er ENOMEM 154The process cannot allocate enough memory to initialize another mutex. 155.El 156.Pp 157.\" ----- 158.Fn pthread_mutex_destroy 159may fail if: 160.Bl -tag -width Er 161.It Bq Er EBUSY 162.Fa Mutex 163is locked by another thread. 164.It Bq Er EINVAL 165The value specified by 166.Fa mutex 167is invalid. 168.El 169.Pp 170.\" ----- 171.Fn pthread_mutex_lock 172may fail if: 173.Bl -tag -width Er 174.It Bq Er EDEADLK 175A deadlock would occur if the thread blocked waiting for 176.Fa mutex . 177.It Bq Er EINVAL 178The value specified by 179.Fa mutex 180is invalid. 181.El 182.Pp 183.Fn pthread_mutex_trylock 184may fail if: 185.Bl -tag -width Er 186.It Bq Er EBUSY 187.Fa Mutex 188is already locked. 189.It Bq Er EINVAL 190The value specified by 191.Fa mutex 192is invalid. 193.El 194.Pp 195.\" ----- 196.Fn pthread_mutex_unlock 197may fail if: 198.Bl -tag -width Er 199.It Bq Er EINVAL 200The value specified by 201.Fa mutex 202is invalid. 203.It Bq Er EPERM 204The current thread does not hold a lock on 205.Fa mutex . 206.El 207.\" ---------------------------------------------------------------------------- 208.Sh SEE ALSO 209.Xr pthread 3 , 210.Xr pthread_barrier 3 , 211.Xr pthread_cond 3 , 212.Xr pthread_mutexattr 3 , 213.Xr pthread_rwlock 3 , 214.Xr pthread_spin 3 215.\" ---------------------------------------------------------------------------- 216.Sh STANDARDS 217These functions conform to 218.St -p1003.1-2001 . 219