diff options
Diffstat (limited to 'static/netbsd/man3/pthread_mutex.3')
| -rw-r--r-- | static/netbsd/man3/pthread_mutex.3 | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/static/netbsd/man3/pthread_mutex.3 b/static/netbsd/man3/pthread_mutex.3 new file mode 100644 index 00000000..9f0c5034 --- /dev/null +++ b/static/netbsd/man3/pthread_mutex.3 @@ -0,0 +1,304 @@ +.\" $NetBSD: pthread_mutex.3,v 1.12 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" 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@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 June 12, 2016 +.Dt PTHREAD_MUTEX 3 +.Os +.Sh NAME +.Nm pthread_mutex , +.Nm pthread_mutex_init , +.Nm pthread_mutex_destroy , +.Nm pthread_mutex_lock , +.Nm pthread_mutex_trylock , +.Nm pthread_mutex_unlock , +.Nm pthread_mutex_timedlock , +.Nm pthread_mutex_getprioceiling , +.Nm pthread_mutex_setprioceiling +.Nd mutual exclusion primitives +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_init "pthread_mutex_t * restrict mutex" \ +"const pthread_mutexattr_t * restrict attr" +.Vt pthread_mutex_t mutex No = Dv PTHREAD_MUTEX_INITIALIZER ; +.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" +.Ft int +.Fn pthread_mutex_timedlock "pthread_mutex_t * restrict mutex" "const struct timespec * restrict timeout" +.Ft int +.Fn pthread_mutex_getprioceiling "const pthread_mutex_t * restrict mutex" "int * restrict prioceiling" +.Ft int +.Fn pthread_mutex_setprioceiling "pthread_mutex_t * restrict mutex" \ +"int prioceiling" "int * restrict old_ceiling" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_mutex_init +function creates a new mutex, with attributes specified with +.Fa attr . +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +.Pp +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. +.Pp +.\" ----- +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. +.Pp +.\" ----- +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. +.Pp +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. +.Pp +.\" ----- +The +.Fn pthread_mutex_unlock +function 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. +.Pp +.\" ----- +The +.Fn pthread_mutex_timedlock +function shall lock the mutex object referenced by +.Fa mutex . +If the mutex is already locked, the calling thread shall block until +the mutex becomes available in the +.Fn pthread_mutex_lock +function. +If the mutex cannot be locked without waiting for another thread to +unlock the mutex, this wait shall be terminated when the specified timeout +expires. +The timeout shall expire when the absolute time specified by +.Fa timeout +passes, as measured by the clock on which timeouts are based. +.Pp +.\" ----- +The +.Fn pthread_mutex_getprioceiling +function shall return the current priority ceiling of the mutex. +.Pp +.\" ----- +The +.Fn pthread_mutex_setprioceiling +function shall either lock the mutex if it is unlocked, or block until +it can successfully lock the mutex, then it shall change the mutex's priority +ceiling and release the mutex. +When the change is successful, the previous value of the priority ceiling +shall be returned +in +.Fa old_ceiling . +The process of locking the mutex need not adhere to the priority +protect protocol. +If +.Fn pthread_mutex_setprioceiling +function fails, the mutex priority ceiling shall not be changed. +.\" ---------------------------------------------------------------------------- +.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: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another mutex. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to initialize another mutex. +.El +.Pp +.\" ----- +.Fn pthread_mutex_destroy +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa Mutex +is locked by another thread. +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_lock +may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +A deadlock would occur if the thread blocked waiting for +.Fa mutex . +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.Fn pthread_mutex_trylock +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa Mutex +is already locked. +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_unlock +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The current thread does not hold a lock on +.Fa mutex . +.El +.Pp +.\" ----- +.Fn pthread_mutex_timedlock +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The mutex was created with the protocol attribute having the value +.Dv PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher than +the mutex current priority ceiling; or +the process or thread would have blocked, and the +.Fa timeout +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1000 million. +.It Bq Er ETIMEDOUT +The mutex could not be locked before the specified timeout expired. +.El +.Pp +.\" ----- +The +.Fn pthread_mutex_getprioceiling +and +.Fn pthread_mutex_setprioceiling +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The priority requested by +.Fa prioceiling +is out of range; or +the value specified by +.Fa mutex +does not refer to a currently existing mutex. +.It Bq Er EPERM +The caller does not have the privilege to perform the operation. +.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 . |