Copyright (c) 2002, 2010 The NetBSD Foundation, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Copyright (c) 1997 Brian Cully <shmit (at] kublai.com>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the author nor the names of any co-contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
----------------------------------------------------------------------------
.Dd July 8, 2010 .Dt PTHREAD_MUTEX 3 .Os .Sh NAME .Nm pthread_mutex .Nd mutual exclusion primitives .Sh LIBRARY .Lb libpthread ----------------------------------------------------------------------------
.Sh SYNOPSIS n pthread.h .Ft int .Fn pthread_mutex_init "pthread_mutex_t * restrict mutex" \ "const pthread_mutexattr_t * restrict attr" .Ft int .Fn pthread_mutex_destroy "pthread_mutex_t *mutex" .Ft int .Fn pthread_mutex_lock "pthread_mutex_t *mutex" .Ft int .Fn pthread_mutex_trylock "pthread_mutex_t *mutex" .Ft int .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
p
.Va pthread_mutex_t mutex = Dv PTHREAD_MUTEX_INITIALIZER;
----------------------------------------------------------------------------
.Sh DESCRIPTION
The
.Fn pthread_mutex_init
function creates a new mutex, with attributes specified with
.Fa attr .
If
.Fa attr
is NULL the default attributes are used.
p The macro .Dv PTHREAD_MUTEX_INITIALIZER can be used to initialize a mutex when the default attributes are appropriate and the mutex can be statically allocated. The behavior is similar to .Fn pthread_mutex_init with .Fa attr specified as .Dv NULL , except that no error checking is done.
p
-----
The
.Fn pthread_mutex_destroy
function frees the resources allocated for
.Fa mutex .
It is possible to reinitialize a destroyed mutex, but undefined
behavior may follow if the destroyed object is otherwise referenced.
p
-----
The
.Fn pthread_mutex_lock
function locks
.Fa mutex .
If the mutex is already locked, the calling thread will block until the
mutex becomes available.
The error conditions may vary depending on the type of the mutex; see
.Xr pthread_mutexattr 3
for additional details.
p The .Fn pthread_mutex_trylock function locks .Fa mutex . If the mutex is already locked, .Fn pthread_mutex_trylock will not block waiting for the mutex, but will return an error condition.
p
-----
The
.Fn pthread_mutex_unlock
unlocks an acquired
.Fa mutex .
When operating with the default mutex type,
undefined behavior follows if a thread tries to unlock a mutex
that has not been locked by it, or if a thread tries to release
a mutex that is already unlocked.
----------------------------------------------------------------------------
.Sh RETURN VALUES
Upon success all described functions return zero.
Otherwise, an error number will be returned to indicate the error.
.Sh ERRORS
.Fn pthread_mutex_init
may fail if:
l -tag -width Er t Bq Er EAGAIN The system lacks the resources to initialize another mutex.
t Bq Er ENOMEM The process cannot allocate enough memory to initialize another mutex.
t Bq Er EINVAL The value specified by
.Fa attr
is invalid.
.El
p
-----
.Fn pthread_mutex_destroy
may fail if:
l -tag -width Er t Bq Er EBUSY .Fa Mutex
is locked by another thread.
t Bq Er EINVAL The value specified by
.Fa mutex
is invalid.
.El
p
-----
.Fn pthread_mutex_lock
may fail if:
l -tag -width Er t Bq Er EDEADLK A deadlock would occur if the thread blocked waiting for
.Fa mutex .
t Bq Er EINVAL The value specified by
.Fa mutex
is invalid.
.El
p .Fn pthread_mutex_trylock may fail if: l -tag -width Er t Bq Er EBUSY .Fa Mutex is already locked. t Bq Er EINVAL The value specified by .Fa mutex is invalid. .El
p
-----
.Fn pthread_mutex_unlock
may fail if:
l -tag -width Er t Bq Er EINVAL The value specified by
.Fa mutex
is invalid.
t Bq Er EPERM The current thread does not hold a lock on
.Fa mutex .
.El
----------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pthread 3 ,
.Xr pthread_barrier 3 ,
.Xr pthread_cond 3 ,
.Xr pthread_mutexattr 3
.Xr pthread_rwlock 3 ,
.Xr pthread_spin 3
----------------------------------------------------------------------------
.Sh STANDARDS
These functions conform to
.St -p1003.1-2001 .
Indexes created Sun Sep 21 19:09:51 GMT 2025