HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |CANCELLATION |ASYNC-SIGNAL SAFETY |RETURN VALUE |ERRORS |SEE ALSO |EXAMPLE |COLOPHON | |
pthread_cond_init(3) Library Functions Manualpthread_cond_init(3)pthread_cond_init, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait, pthread_cond_destroy - operations on conditions
#include <pthread.h>pthread_cond_tcond= PTHREAD_COND_INITIALIZER;int pthread_cond_init(pthread_cond_t *cond,pthread_condattr_t *cond_attr);int pthread_cond_signal(pthread_cond_t *cond);int pthread_cond_broadcast(pthread_cond_t *cond);int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,const struct timespec *abstime);int pthread_cond_destroy(pthread_cond_t *cond);
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. 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.pthread_cond_init() initializes the condition variablecond, using the condition attributes specified incond_attr, or default attributes ifcond_attr is NULL. The LinuxThreads implementation supports no attributes for conditions, hence thecond_attr parameter is actually ignored. Variables of typepthread_cond_t can also be initialized statically, using the constantPTHREAD_COND_INITIALIZER.pthread_cond_signal() restarts one of the threads that are waiting on the condition variablecond. If no threads are waiting oncond, nothing happens. If several threads are waiting oncond, exactly one is restarted, but it is not specified which.pthread_cond_broadcast() restarts all the threads that are waiting on the condition variablecond. Nothing happens if no threads are waiting oncond.pthread_cond_wait() atomically unlocks themutex (as perpthread_unlock_mutex()) and waits for the condition variablecond to be signaled. The thread execution is suspended and does not consume any CPU time until the condition variable is signaled. Themutex must be locked by the calling thread on entrance topthread_cond_wait(). Before returning to the calling thread,pthread_cond_wait() re-acquiresmutex (as perpthread_mutex_lock()). 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.pthread_cond_timedwait() atomically unlocksmutex and waits oncond, aspthread_cond_wait() does, but it also bounds the duration of the wait. Ifcond has not been signaled within the amount of time specified byabstime, the mutexmutex is re-acquired andpthread_cond_timedwait() returns the errorETIMEDOUT. Theabstime parameter specifies an absolute time, with the same origin astime(2) andgettimeofday(2): anabstime of 0 corresponds to 00:00:00 GMT, January 1, 1970.pthread_cond_destroy() destroys a condition variable, freeing the resources it might hold. No threads must be waiting on the condition variable on entrance topthread_cond_destroy(). In the LinuxThreads implementation, no resources are associated with condition variables, thuspthread_cond_destroy() actually does nothing except checking that the condition has no waiting threads.
pthread_cond_wait() andpthread_cond_timedwait() are cancelation points. If a thread is cancelled while suspended in one of these functions, the thread immediately resumes execution, then locks again themutex argument topthread_cond_wait() andpthread_cond_timedwait(), and finally executes the cancelation. Consequently, cleanup handlers are assured thatmutex is locked when they are called.
The condition functions are not async-signal safe, and should not be called from a signal handler. In particular, callingpthread_cond_signal() orpthread_cond_broadcast() from a signal handler may deadlock the calling thread.
All condition variable functions return 0 on success and a non- zero error code on error.
pthread_cond_init(),pthread_cond_signal(),pthread_cond_broadcast(), andpthread_cond_wait() never return an error code. Thepthread_cond_timedwait() function returns the following error codes on error:ETIMEDOUT The condition variable was not signaled until the timeout specified byabstime . Thepthread_cond_destroy() function returns the following error code on error:EBUSYSome threads are currently waiting oncond .
pthread_condattr_init(3),pthread_mutex_lock(3),pthread_mutex_unlock(3),gettimeofday(2),nanosleep(2).
Consider two shared variablesx andy , protected by the mutexmut, and a condition variablecond that is to be signaled wheneverx becomes greater thany.int x,y;pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;pthread_cond_t cond = PTHREAD_COND_INITIALIZER; Waiting untilx is greater thany is performed as follows:pthread_mutex_lock(&mut);while (x <= y) {pthread_cond_wait(&cond, &mut);}/* operate on x and y */pthread_mutex_unlock(&mut); Modifications onx andy that may causex to become greater thany should signal the condition if needed:pthread_mutex_lock(&mut);/* modify x and y */if (x > y) pthread_cond_broadcast(&cond);pthread_mutex_unlock(&mut); 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 throughx andy),pthread_cond_signal() can be used as a slightly more efficient alternative topthread_cond_broadcast(). In doubt, usepthread_cond_broadcast(). To wait forx to become greater thany with a timeout of 5 seconds, do: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); This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17pthread_cond_init(3)Pages that refer to this page:FUTEX_WAKE_OP(2const), PR_SET_TIMERSLACK(2const), pthread_condattr_init(3), pthreads(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |