summaryrefslogtreecommitdiffstats
path: root/man3/pthread_mutex_init.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/pthread_mutex_init.3')
-rw-r--r--man3/pthread_mutex_init.3241
1 files changed, 0 insertions, 241 deletions
diff --git a/man3/pthread_mutex_init.3 b/man3/pthread_mutex_init.3
deleted file mode 100644
index 8d9abf9..0000000
--- a/man3/pthread_mutex_init.3
+++ /dev/null
@@ -1,241 +0,0 @@
-.\" 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-02-26 "Linux man-pages 6.7"
-.
-.
-.SH NAME
-pthread_mutex_init,
-pthread_mutex_lock,
-pthread_mutex_trylock,
-pthread_mutex_unlock,
-pthread_mutex_destroy
-\-
-operations on mutexes
-.
-.
-.SH SYNOPSIS
-.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 ", 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 ");"
-.
-.
-.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