Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 312 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3p/pthread_mutex_lock.3p b/upstream/mageia-cauldron/man3p/pthread_mutex_lock.3p
new file mode 100644
index 00000000..30544ec7
--- /dev/null
+++ b/upstream/mageia-cauldron/man3p/pthread_mutex_lock.3p
@@ -0,0 +1,312 @@
+'\" et
+.TH PTHREAD_MUTEX_LOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+pthread_mutex_lock,
+pthread_mutex_trylock,
+pthread_mutex_unlock
+\(em lock and unlock a mutex
+.SH SYNOPSIS
+.LP
+.nf
+#include <pthread.h>
+.P
+int pthread_mutex_lock(pthread_mutex_t *\fImutex\fP);
+int pthread_mutex_trylock(pthread_mutex_t *\fImutex\fP);
+int pthread_mutex_unlock(pthread_mutex_t *\fImutex\fP);
+.fi
+.SH DESCRIPTION
+The mutex object referenced by
+.IR mutex
+shall be locked by a call to
+\fIpthread_mutex_lock\fR()
+that returns zero or
+.BR [EOWNERDEAD] .
+If the mutex is already locked by another thread, the calling thread
+shall block until the mutex becomes available. This operation shall
+return with the mutex object referenced by
+.IR mutex
+in the locked state with the calling thread as its owner. If a thread
+attempts to relock a mutex that it has already locked,
+\fIpthread_mutex_lock\fR()
+shall behave as described in the
+.BR Relock
+column of the following table. If a thread attempts to unlock a mutex
+that it has not locked or a mutex which is unlocked,
+\fIpthread_mutex_unlock\fR()
+shall behave as described in the
+.BR "Unlock When Not Owner"
+column of the following table.
+.TS
+center box tab(!);
+cB | cB | cB | cB
+l | l | l | l.
+Mutex Type!Robustness!Relock!Unlock When Not Owner
+_
+NORMAL!non-robust!deadlock!undefined behavior
+_
+NORMAL!robust!deadlock!error returned
+_
+ERRORCHECK!either!error returned!error returned
+_
+RECURSIVE!either!recursive!error returned
+!!(see below)
+_
+DEFAULT!non-robust!undefined!undefined behavior\s-2\(dg\s+2
+!!behavior\s-2\(dg\s+2
+_
+DEFAULT!robust!undefined!error returned
+!!behavior\s-2\(dg\s+2
+.TE
+.IP "\(dg" 6
+If the mutex type is PTHREAD_MUTEX_DEFAULT, the behavior of
+\fIpthread_mutex_lock\fR()
+may correspond to one of the three other standard mutex types as described
+in the table above. If it does not correspond to one of those three,
+the behavior is undefined for the cases marked \(dg.
+.P
+Where the table indicates recursive behavior, the mutex shall maintain
+the concept of a lock count. When a thread successfully acquires a
+mutex for the first time, the lock count shall be set to one. Every
+time a thread relocks this mutex, the lock count shall be incremented
+by one. Each time the thread unlocks the mutex, the lock count shall be
+decremented by one. When the lock count reaches zero, the mutex shall
+become available for other threads to acquire.
+.P
+The
+\fIpthread_mutex_trylock\fR()
+function shall be equivalent to
+\fIpthread_mutex_lock\fR(),
+except that if the mutex object referenced by
+.IR mutex
+is currently locked (by any thread, including the current thread), the
+call shall return immediately. If the mutex type is
+PTHREAD_MUTEX_RECURSIVE and the mutex is currently owned by the
+calling thread, the mutex lock count shall be incremented by one and
+the
+\fIpthread_mutex_trylock\fR()
+function shall immediately return success.
+.P
+The
+\fIpthread_mutex_unlock\fR()
+function shall release the mutex object referenced by
+.IR mutex .
+The manner in which a mutex is released is dependent upon the mutex's type
+attribute. If there are threads blocked on the mutex object referenced by
+.IR mutex
+when
+\fIpthread_mutex_unlock\fR()
+is called, resulting in the mutex becoming available, the scheduling
+policy shall determine which thread shall acquire the mutex.
+.P
+(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become
+available when the count reaches zero and the calling thread no longer
+has any locks on this mutex.)
+.P
+If a signal is delivered to a thread waiting for a mutex, upon return
+from the signal handler the thread shall resume waiting for the mutex
+as if it was not interrupted.
+.P
+If
+.IR mutex
+is a robust mutex and the process containing the owning thread
+terminated while holding the mutex lock, a call to
+\fIpthread_mutex_lock\fR()
+shall return the error value
+.BR [EOWNERDEAD] .
+If
+.IR mutex
+is a robust mutex and the owning thread terminated while holding the
+mutex lock, a call to
+\fIpthread_mutex_lock\fR()
+may return the error value
+.BR [EOWNERDEAD] 
+even if the process in which the owning thread resides has not
+terminated. In these cases, the mutex is locked by the thread but the
+state it protects is marked as inconsistent. The application should
+ensure that the state is made consistent for reuse and when that is
+complete call
+\fIpthread_mutex_consistent\fR().
+If the application is unable to recover the state, it should unlock the
+mutex without a prior call to
+\fIpthread_mutex_consistent\fR(),
+after which the mutex is marked permanently unusable.
+.P
+If
+.IR mutex
+does not refer to an initialized mutex object, the behavior of
+\fIpthread_mutex_lock\fR(),
+\fIpthread_mutex_trylock\fR(),
+and
+\fIpthread_mutex_unlock\fR()
+is undefined.
+.SH "RETURN VALUE"
+If successful, the
+\fIpthread_mutex_lock\fR(),
+\fIpthread_mutex_trylock\fR(),
+and
+\fIpthread_mutex_unlock\fR()
+functions shall return zero; otherwise, an error number shall be
+returned to indicate the error.
+.SH ERRORS
+The
+\fIpthread_mutex_lock\fR()
+and
+\fIpthread_mutex_trylock\fR()
+functions shall fail if:
+.TP
+.BR EAGAIN
+The mutex could not be acquired because the maximum number of recursive
+locks for
+.IR mutex
+has been exceeded.
+.TP
+.BR EINVAL
+The
+.IR mutex
+was created with the protocol attribute having the value
+PTHREAD_PRIO_PROTECT
+and the calling thread's priority is higher than the mutex's current
+priority ceiling.
+.TP
+.BR ENOTRECOVERABLE
+.br
+The state protected by the mutex is not recoverable.
+.TP
+.BR EOWNERDEAD
+.br
+The mutex is a robust mutex and the process containing the previous
+owning thread terminated while holding the mutex lock. The mutex lock
+shall be acquired by the calling thread and it is up to the new owner
+to make the state consistent.
+.P
+The
+\fIpthread_mutex_lock\fR()
+function shall fail if:
+.TP
+.BR EDEADLK
+The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current
+thread already owns the mutex.
+.P
+The
+\fIpthread_mutex_trylock\fR()
+function shall fail if:
+.TP
+.BR EBUSY
+The
+.IR mutex
+could not be acquired because it was already locked.
+.P
+The
+\fIpthread_mutex_unlock\fR()
+function shall fail if:
+.TP
+.BR EPERM
+The mutex type is PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE,
+or the mutex is a robust mutex, and the current thread does not own
+the mutex.
+.br
+.P
+The
+\fIpthread_mutex_lock\fR()
+and
+\fIpthread_mutex_trylock\fR()
+functions may fail if:
+.TP
+.BR EOWNERDEAD
+.br
+The mutex is a robust mutex and the previous owning thread terminated
+while holding the mutex lock. The mutex lock shall be acquired by the
+calling thread and it is up to the new owner to make the state consistent.
+.P
+The
+\fIpthread_mutex_lock\fR()
+function may fail if:
+.TP
+.BR EDEADLK
+A deadlock condition was detected.
+.P
+These functions shall not return an error code of
+.BR [EINTR] .
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+Applications that have assumed that non-zero return values are errors
+will need updating for use with robust mutexes, since a valid return
+for a thread acquiring a mutex which is protecting a currently
+inconsistent state is
+.BR [EOWNERDEAD] .
+Applications that do not check the error returns, due to ruling out the
+possibility of such errors arising, should not use robust mutexes. If
+an application is supposed to work with normal and robust mutexes it
+should check all return values for error conditions and if necessary
+take appropriate action.
+.SH RATIONALE
+Mutex objects are intended to serve as a low-level primitive from which
+other thread synchronization functions can be built. As such, the
+implementation of mutexes should be as efficient as possible, and this
+has ramifications on the features available at the interface.
+.P
+The mutex functions and the particular default settings of the mutex
+attributes have been motivated by the desire to not preclude fast,
+inlined implementations of mutex locking and unlocking.
+.P
+Since most attributes only need to be checked when a thread is going to
+be blocked, the use of attributes does not slow the (common)
+mutex-locking case.
+.P
+Likewise, while being able to extract the thread ID of the owner of a
+mutex might be desirable, it would require storing the current thread
+ID when each mutex is locked, and this could incur unacceptable levels
+of overhead. Similar arguments apply to a
+.IR mutex_tryunlock
+operation.
+.P
+For further rationale on the extended mutex types, see the Rationale (Informative) volume of POSIX.1\(hy2017,
+.IR "Threads Extensions".
+.P
+If an implementation detects that the value specified by the
+.IR mutex
+argument does not refer to an initialized mutex object, it is
+recommended that the function should fail and report an
+.BR [EINVAL] 
+error.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.ad l
+.IR "\fIpthread_mutex_consistent\fR\^(\|)",
+.IR "\fIpthread_mutex_destroy\fR\^(\|)",
+.IR "\fIpthread_mutex_timedlock\fR\^(\|)",
+.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)"
+.ad b
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 4.12" ", " "Memory Synchronization",
+.IR "\fB<pthread.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .