aboutsummaryrefslogtreecommitdiff
path: root/linuxthreads/man/pthread_mutex_init.man
diff options
context:
space:
mode:
Diffstat (limited to 'linuxthreads/man/pthread_mutex_init.man')
-rw-r--r--linuxthreads/man/pthread_mutex_init.man213
1 files changed, 0 insertions, 213 deletions
diff --git a/linuxthreads/man/pthread_mutex_init.man b/linuxthreads/man/pthread_mutex_init.man
deleted file mode 100644
index 643b007aec..0000000000
--- a/linuxthreads/man/pthread_mutex_init.man
+++ /dev/null
@@ -1,213 +0,0 @@
-.TH PTHREAD_MUTEX 3 LinuxThreads
-
-.XREF pthread_mutex_lock
-.XREF pthread_mutex_unlock
-.XREF pthread_mutex_trylock
-.XREF pthread_mutex_destroy
-
-.SH NAME
-pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, pthread_mutex_destroy \- operations on mutexes
-
-.SH SYNOPSIS
-#include <pthread.h>
-
-pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;
-
-pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;
-
-pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;
-
-int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr);
-
-int pthread_mutex_lock(pthread_mutex_t *mutex);
-
-int pthread_mutex_trylock(pthread_mutex_t *mutex);
-
-int pthread_mutex_unlock(pthread_mutex_t *mutex);
-
-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.
-
-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.
-
-!pthread_mutex_init! initializes the mutex object pointed to by
-|mutex| according to the mutex attributes specified in |mutexattr|.
-If |mutexattr| is !NULL!, default attributes are used instead.
-
-The LinuxThreads implementation supports only one mutex attributes,
-the |mutex kind|, 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 !pthread_mutexattr_init!(3) for more
-information on mutex attributes.
-
-Variables of type !pthread_mutex_t! can also be initialized
-statically, using the constants !PTHREAD_MUTEX_INITIALIZER! (for fast
-mutexes), !PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP! (for recursive
-mutexes), and !PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP! (for error checking
-mutexes).
-
-!pthread_mutex_lock! locks the given mutex. If the mutex is currently
-unlocked, it becomes locked and owned by the calling thread, and
-!pthread_mutex_lock! returns immediately. If the mutex is already
-locked by another thread, !pthread_mutex_lock! suspends the calling
-thread until the mutex is unlocked.
-
-If the mutex is already locked by the calling thread, the behavior of
-!pthread_mutex_lock! 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,
-!pthread_mutex_lock! returns immediately with the error code !EDEADLK!.
-If the mutex is of the ``recursive'' kind, !pthread_mutex_lock!
-succeeds and returns immediately, recording the number of times the
-calling thread has locked the mutex. An equal number of
-!pthread_mutex_unlock! operations must be performed before the mutex
-returns to the unlocked state.
-
-!pthread_mutex_trylock! behaves identically to !pthread_mutex_lock!,
-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, !pthread_mutex_trylock! returns
-immediately with the error code !EBUSY!.
-
-!pthread_mutex_unlock! unlocks the given mutex. The mutex is assumed
-to be locked and owned by the calling thread on entrance to
-!pthread_mutex_unlock!. If the mutex is of the ``fast'' kind,
-!pthread_mutex_unlock! always returns it to the unlocked state. If it
-is of the ``recursive'' kind, it decrements the locking count of the
-mutex (number of !pthread_mutex_lock! operations performed on it by
-the calling thread), and only when this count reaches zero is the
-mutex actually unlocked.
-
-On ``error checking'' mutexes, !pthread_mutex_unlock! 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 !pthread_mutex_unlock!.
-If these conditions are not met, an error code is returned and the
-mutex remains unchanged. ``Fast'' and ``recursive'' 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.
-
-!pthread_mutex_destroy! 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 !pthread_mutex_destroy! actually does nothing except
-checking that the mutex is unlocked.
-
-.SH CANCELLATION
-
-None of the mutex functions is a cancellation point, not even
-!pthread_mutex_lock!, in spite of the fact that it can suspend a
-thread for arbitrary durations. This way, the status of mutexes at
-cancellation points is predictable, allowing cancellation handlers to
-unlock precisely those mutexes that need to be unlocked before the
-thread stops executing. Consequently, threads using deferred
-cancellation 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 !pthread_mutex_lock! or !pthread_mutex_unlock! from a signal
-handler may deadlock the calling thread.
-
-.SH "RETURN VALUE"
-
-!pthread_mutex_init! always returns 0. The other mutex functions
-return 0 on success and a non-zero error code on error.
-
-.SH ERRORS
-
-The !pthread_mutex_lock! function returns the following error code
-on error:
-.RS
-.TP
-!EINVAL!
-the mutex has not been properly initialized.
-
-.TP
-!EDEADLK!
-the mutex is already locked by the calling thread
-(``error checking'' mutexes only).
-.RE
-
-The !pthread_mutex_trylock! function returns the following error codes
-on error:
-.RS
-.TP
-!EBUSY!
-the mutex could not be acquired because it was currently locked.
-
-.TP
-!EINVAL!
-the mutex has not been properly initialized.
-.RE
-
-The !pthread_mutex_unlock! function returns the following error code
-on error:
-.RS
-.TP
-!EINVAL!
-the mutex has not been properly initialized.
-
-.TP
-!EPERM!
-the calling thread does not own the mutex (``error checking'' mutexes only).
-.RE
-
-The !pthread_mutex_destroy! function returns the following error code
-on error:
-.RS
-.TP
-!EBUSY!
-the mutex is currently locked.
-.RE
-
-.SH AUTHOR
-Xavier Leroy <Xavier.Leroy@inria.fr>
-
-.SH "SEE ALSO"
-!pthread_mutexattr_init!(3),
-!pthread_mutexattr_setkind_np!(3),
-!pthread_cancel!(3).
-
-.SH EXAMPLE
-
-A shared global variable |x| can be protected by a mutex as follows:
-
-.RS
-.ft 3
-.nf
-.sp
-int x;
-pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
-.ft
-.LP
-.RE
-.fi
-
-All accesses and modifications to |x| should be bracketed by calls to
-!pthread_mutex_lock! and !pthread_mutex_unlock! as follows:
-
-.RS
-.ft 3
-.nf
-.sp
-pthread_mutex_lock(&mut);
-/* operate on x */
-pthread_mutex_unlock(&mut);
-.ft
-.LP
-.RE
-.fi
-
-