Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 244 insertions, 0 deletions

diff --git a/man/man3/pthread_mutex_init.3 b/man/man3/pthread_mutex_init.3
new file mode 100644
index 0000000..0b05459
--- /dev/null
+++ b/man/man3/pthread_mutex_init.3
@@ -0,0 +1,244 @@
+.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr>
+.\" Copyright 2023, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_mutex_init 3 2024-05-19 "Linux man-pages (unreleased)"
+.
+.
+.SH NAME
+pthread_mutex_init,
+pthread_mutex_lock,
+pthread_mutex_trylock,
+pthread_mutex_unlock,
+pthread_mutex_destroy
+\-
+operations on mutexes
+.
+.
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.P
+.BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;"
+.BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;"
+.BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;"
+.P
+.BI "int pthread_mutex_init(pthread_mutex_t *" mutex ,
+.BI "                       const pthread_mutexattr_t *" mutexattr );
+.BI "int pthread_mutex_lock(pthread_mutex_t *" mutex );
+.BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex );
+.BI "int pthread_mutex_unlock(pthread_mutex_t *" mutex );
+.BI "int pthread_mutex_destroy(pthread_mutex_t *" mutex );
+.fi
+.
+.
+.SH DESCRIPTION
+A mutex is a MUTual EXclusion device,
+and is useful for
+protecting shared data structures from concurrent modifications,
+and implementing critical sections and monitors.
+.P
+A mutex has two possible states:
+unlocked (not owned by any thread),
+and locked (owned by one thread).
+A mutex can never be owned by two different threads simultaneously.
+A thread attempting to lock a mutex
+that is already locked by another thread
+is suspended until the owning thread unlocks the mutex first.
+.P
+\fBpthread_mutex_init\fP initializes the mutex object pointed to by \fImutex\fP
+according to the mutex attributes specified in \fImutexattr\fP.
+If \fImutexattr\fP is \fBNULL\fP,
+default attributes are used instead.
+.P
+The LinuxThreads implementation supports only one mutex attributes,
+the \fImutex kind\fP,
+which is either ``fast'',
+``recursive'',
+or ``error checking''.
+The kind of a mutex determines
+whether it can be locked again by a thread that already owns it.
+The default kind is ``fast''.
+See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes.
+.P
+Variables of type \fBpthread_mutex_t\fP can also be initialized statically,
+using the constants
+\fBPTHREAD_MUTEX_INITIALIZER\fP
+(for fast mutexes),
+\fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP
+(for recursive mutexes),
+and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP
+(for error checking mutexes).
+.P
+\fBpthread_mutex_lock\fP locks the given mutex.
+If the mutex is currently unlocked,
+it becomes locked and owned by the calling thread,
+and \fBpthread_mutex_lock\fP returns immediately.
+If the mutex is already locked by another thread,
+\fBpthread_mutex_lock\fP suspends the calling thread
+until the mutex is unlocked.
+.P
+If the mutex is already locked by the calling thread,
+the behavior of \fBpthread_mutex_lock\fP depends on the kind of the mutex.
+If the mutex is of the ``fast'' kind,
+the calling thread is suspended until the mutex is unlocked,
+thus effectively causing the calling thread to deadlock.
+If the mutex is of the ``error checking'' kind,
+\fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP.
+If the mutex is of the ``recursive'' kind,
+\fBpthread_mutex_lock\fP succeeds and returns immediately,
+recording the number of times the calling thread has locked the mutex.
+An equal number of \fBpthread_mutex_unlock\fP operations
+must be performed before the mutex returns to the unlocked state.
+.P
+\fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP,
+except that it does not block the calling thread
+if the mutex is already locked by another thread
+(or by the calling thread in the case of a ``fast'' mutex).
+Instead,
+\fBpthread_mutex_trylock\fP returns immediately
+with the error code \fBEBUSY\fP.
+.P
+\fBpthread_mutex_unlock\fP unlocks the given mutex.
+The mutex is assumed to be locked and owned by the calling thread
+on entrance to \fBpthread_mutex_unlock\fP.
+If the mutex is of the ``fast'' kind,
+\fBpthread_mutex_unlock\fP always returns it to the unlocked state.
+If it is of the ``recursive'' kind,
+it decrements the locking count of the mutex
+(number of \fBpthread_mutex_lock\fP operations
+performed on it by the calling thread),
+and only when this count reaches zero is the mutex actually unlocked.
+.P
+On ``error checking'' and ``recursive'' mutexes,
+\fBpthread_mutex_unlock\fP actually checks at run-time
+that the mutex is locked on entrance,
+and that it was locked by the same thread
+that is now calling \fBpthread_mutex_unlock\fP.
+If these conditions are not met,
+an error code is returned and the mutex remains unchanged.
+``Fast'' mutexes perform no such checks,
+thus allowing a locked mutex to be
+unlocked by a thread other than its owner.
+This is non-portable behavior and must not be relied upon.
+.P
+\fBpthread_mutex_destroy\fP destroys a mutex object,
+freeing the resources it might hold.
+The mutex must be unlocked on entrance.
+In the LinuxThreads implementation,
+no resources are associated with mutex objects,
+thus \fBpthread_mutex_destroy\fP actually does nothing
+except checking that the mutex is unlocked.
+.
+.
+.SH CANCELLATION
+None of the mutex functions is a cancelation point,
+not even \fBpthread_mutex_lock\fP,
+in spite of the fact that it can suspend a thread for arbitrary durations.
+This way,
+the status of mutexes at cancelation points is predictable,
+allowing cancelation handlers
+to unlock precisely those mutexes that need to be unlocked
+before the thread stops executing.
+Consequently,
+threads using deferred cancelation
+should never hold a mutex for extended periods of time.
+.
+.
+.SH "ASYNC-SIGNAL SAFETY"
+The mutex functions are not async-signal safe.
+What this means is that they should not be called from a signal handler.
+In particular,
+calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP
+from a signal handler
+may deadlock the calling thread.
+.
+.
+.SH "RETURN VALUE"
+\fBpthread_mutex_init\fP always returns 0.
+The other mutex functions
+return 0 on success and a non-zero error code on error.
+.
+.
+.SH ERRORS
+The \fBpthread_mutex_lock\fP function returns
+the following error code on error:
+.RS
+.TP
+\fBEINVAL\fP
+The mutex has not been properly initialized.
+.TP
+\fBEDEADLK\fP
+The mutex is already locked by the calling thread
+(``error checking'' mutexes only).
+.RE
+.P
+The \fBpthread_mutex_trylock\fP function returns
+the following error codes on error:
+.RS
+.TP
+\fBEBUSY\fP
+The mutex could not be acquired because it was currently locked.
+.TP
+\fBEINVAL\fP
+The mutex has not been properly initialized.
+.RE
+.P
+The \fBpthread_mutex_unlock\fP function returns
+the following error code on error:
+.RS
+.TP
+\fBEINVAL\fP
+The mutex has not been properly initialized.
+.TP
+\fBEPERM\fP
+The calling thread does not own the mutex
+(``error checking'' mutexes only).
+.RE
+.P
+The \fBpthread_mutex_destroy\fP function returns
+the following error code on error:
+.RS
+.TP
+\fBEBUSY\fP
+The mutex is currently locked.
+.RE
+.
+.
+.SH "SEE ALSO"
+\fBpthread_mutexattr_init\fP(3),
+\fBpthread_mutexattr_setkind_np\fP(3),
+\fBpthread_cancel\fP(3).
+.
+.
+.SH EXAMPLE
+A shared global variable \fIx\fP can be protected by a mutex as follows:
+.P
+.RS
+.ft 3
+.nf
+.sp
+int x;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+.ft
+.P
+.RE
+.fi
+.P
+All accesses and modifications to \fIx\fP
+should be bracketed by calls to
+\fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP
+as follows:
+.P
+.RS
+.ft 3
+.nf
+.sp
+pthread_mutex_lock(&mut);
+/* operate on x */
+pthread_mutex_unlock(&mut);
+.ft
+.P
+.RE
+.fi