Merging upstream version 6.7.

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

1 files changed, 264 insertions, 0 deletions

diff --git a/man3/pthread_cond_init.3 b/man3/pthread_cond_init.3
new file mode 100644
index 0000000..7fff419
--- /dev/null
+++ b/man3/pthread_cond_init.3
@@ -0,0 +1,264 @@
+.\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr>
+.\" Copyright 2023, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_cond_init 3 2024-02-26 "Linux man-pages 6.7"
+.
+.
+.SH NAME
+pthread_cond_init,
+pthread_cond_signal,
+pthread_cond_broadcast,
+pthread_cond_wait,
+pthread_cond_timedwait,
+pthread_cond_destroy
+\-
+operations on conditions
+.
+.
+.SH SYNOPSIS
+.B #include <pthread.h>
+.P
+.BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;"
+.P
+.BI "int pthread_cond_init(pthread_cond_t *" cond ", pthread_condattr_t *" cond_attr ");"
+.BI "int pthread_cond_signal(pthread_cond_t *" cond ");"
+.BI "int pthread_cond_broadcast(pthread_cond_t *" cond ");"
+.BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ");"
+.BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ", const struct timespec *" abstime ");"
+.BI "int pthread_cond_destroy(pthread_cond_t *" cond ");"
+.
+.
+.SH DESCRIPTION
+A condition (short for ``condition variable'')
+is a synchronization device that allows threads
+to suspend execution and relinquish the processors
+until some predicate on shared data is satisfied.
+The basic operations on conditions are:
+signal the condition (when the predicate becomes true),
+and wait for the condition,
+suspending the thread execution until another thread signals the condition.
+.P
+A condition variable must always be associated with a mutex,
+to avoid the race condition where
+a thread prepares to wait on a condition variable
+and another thread signals the condition
+just before the first thread actually waits on it.
+.P
+\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP,
+using the condition attributes specified in \fIcond_attr\fP,
+or default attributes if \fIcond_attr\fP is \fBNULL\fP.
+The LinuxThreads implementation supports no attributes for conditions,
+hence the \fIcond_attr\fP parameter is actually ignored.
+.P
+Variables of type \fBpthread_cond_t\fP can also be initialized statically,
+using the constant \fBPTHREAD_COND_INITIALIZER\fP.
+.P
+\fBpthread_cond_signal\fP restarts one of the threads that
+are waiting on the condition variable \fIcond\fP.
+If no threads are waiting on \fIcond\fP,
+nothing happens.
+If several threads are waiting on \fIcond\fP,
+exactly one is restarted,
+but it is not specified which.
+.P
+\fBpthread_cond_broadcast\fP restarts all the threads that
+are waiting on the condition variable \fIcond\fP.
+Nothing happens if no threads are waiting on \fIcond\fP.
+.P
+\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP
+(as per \fBpthread_unlock_mutex\fP)
+and waits for the condition variable \fIcond\fP to be signaled.
+The thread execution is suspended and does not consume any CPU time
+until the condition variable is signaled.
+The \fImutex\fP must be locked by the calling thread
+on entrance to \fBpthread_cond_wait\fP.
+Before returning to the calling thread,
+\fBpthread_cond_wait\fP re-acquires \fImutex\fP
+(as per \fBpthread_lock_mutex\fP).
+.P
+Unlocking the mutex and suspending on the condition variable is done atomically.
+Thus,
+if all threads always acquire the mutex before signaling the condition,
+this guarantees that the condition cannot be signaled (and thus ignored)
+between the time a thread locks the mutex
+and the time it waits on the condition variable.
+.P
+\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP
+and waits on \fIcond\fP,
+as \fBpthread_cond_wait\fP does,
+but it also bounds the duration of the wait.
+If \fIcond\fP has not been signaled
+within the amount of time specified by \fIabstime\fP,
+the mutex \fImutex\fP is re-acquired
+and \fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP.
+The \fIabstime\fP parameter specifies an absolute time,
+with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2):
+an \fIabstime\fP of 0
+corresponds to 00:00:00 GMT, January 1, 1970.
+.P
+\fBpthread_cond_destroy\fP destroys a condition variable,
+freeing the resources it might hold.
+No threads must be waiting on the condition variable
+on entrance to \fBpthread_cond_destroy\fP.
+In the LinuxThreads implementation,
+no resources are associated with condition variables,
+thus \fBpthread_cond_destroy\fP actually does nothing
+except checking that the condition has no waiting threads.
+.
+.
+.SH CANCELLATION
+\fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP
+are cancelation points.
+If a thread is cancelled while suspended in one of these functions,
+the thread immediately resumes execution,
+then locks again the \fImutex\fP
+argument to \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP,
+and finally executes the cancelation.
+Consequently,
+cleanup handlers are assured that \fImutex\fP is locked
+when they are called.
+.
+.
+.SH "ASYNC-SIGNAL SAFETY"
+The condition functions are not async-signal safe,
+and should not be called from a signal handler.
+In particular,
+calling \fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP
+from a signal handler
+may deadlock the calling thread.
+.
+.
+.SH "RETURN VALUE"
+All condition variable functions return 0 on success
+and a non-zero error code on error.
+.
+.
+.SH ERRORS
+\fBpthread_cond_init\fP,
+\fBpthread_cond_signal\fP,
+\fBpthread_cond_broadcast\fP,
+and \fBpthread_cond_wait\fP
+never return an error code.
+.P
+The \fBpthread_cond_timedwait\fP function returns
+the following error codes on error:
+.RS
+.TP
+\fBETIMEDOUT\fP
+The condition variable was not signaled
+until the timeout specified by \fIabstime\fP.
+.TP
+\fBEINTR\fP
+\fBpthread_cond_timedwait\fP was interrupted by a signal.
+.RE
+.P
+The \fBpthread_cond_destroy\fP function returns
+the following error code on error:
+.RS
+.TP
+\fBEBUSY\fP
+Some threads are currently waiting on \fIcond\fP.
+.RE
+.
+.
+.SH "SEE ALSO"
+\fBpthread_condattr_init\fP(3),
+\fBpthread_mutex_lock\fP(3),
+\fBpthread_mutex_unlock\fP(3),
+\fBgettimeofday\fP(2),
+\fBnanosleep\fP(2).
+.
+.
+.SH EXAMPLE
+Consider two shared variables \fIx\fP and \fIy\fP,
+protected by the mutex \fImut\fP,
+and a condition variable \fIcond\fP
+that is to be signaled
+whenever \fIx\fP becomes greater than \fIy\fP.
+.P
+.RS
+.ft 3
+.nf
+.sp
+int x,y;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
+.ft
+.P
+.RE
+.fi
+.P
+Waiting until \fIx\fP is greater than \fIy\fP is performed as follows:
+.P
+.RS
+.ft 3
+.nf
+.sp
+pthread_mutex_lock(&mut);
+while (x <= y) {
+        pthread_cond_wait(&cond, &mut);
+}
+/* operate on x and y */
+pthread_mutex_unlock(&mut);
+.ft
+.P
+.RE
+.fi
+.P
+Modifications on \fIx\fP and \fIy\fP
+that may cause \fIx\fP to become greater than \fIy\fP
+should signal the condition if needed:
+.P
+.RS
+.ft 3
+.nf
+.sp
+pthread_mutex_lock(&mut);
+/* modify x and y */
+if (x > y) pthread_cond_broadcast(&cond);
+pthread_mutex_unlock(&mut);
+.ft
+.P
+.RE
+.fi
+.P
+If it can be proved that at most one waiting thread needs to be waken up
+(for instance,
+if there are only two threads communicating through \fIx\fP and \fIy\fP),
+\fBpthread_cond_signal\fP can be used as
+a slightly more efficient alternative to \fBpthread_cond_broadcast\fP.
+In doubt,
+use \fBpthread_cond_broadcast\fP.
+.P
+To wait for \fIx\fP to become greater than \fIy\fP
+with a timeout of 5 seconds,
+do:
+.P
+.RS
+.ft 3
+.nf
+.sp
+struct timeval now;
+struct timespec timeout;
+int retcode;
+\&
+pthread_mutex_lock(&mut);
+gettimeofday(&now);
+timeout.tv_sec = now.tv_sec + 5;
+timeout.tv_nsec = now.tv_usec * 1000;
+retcode = 0;
+while (x <= y && retcode != ETIMEDOUT) {
+        retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
+}
+if (retcode == ETIMEDOUT) {
+        /* timeout occurred */
+} else {
+        /* operate on x and y */
+}
+pthread_mutex_unlock(&mut);
+.ft
+.P
+.RE
+.fi