jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: pthread_cond_init.3,v 1.14 2025/07/03 18:01:38 tedu Exp $
2.\"
3.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the author nor the names of any co-contributors
15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD: pthread_cond_init.3,v 1.6 1999/08/28 00:03:03 peter Exp $
31.\" $FreeBSD: pthread_cond_destroy.3,v 1.5 1999/08/28 00:03:03 peter Exp $
32.\" $FreeBSD: pthread_cond_wait.3,v 1.6 1999/08/28 00:03:04 peter Exp $
33.\" $FreeBSD: pthread_cond_timedwait.3,v 1.6 1999/08/28 00:03:04 peter Exp $
34.\" $FreeBSD: pthread_cond_broadcast.3,v 1.5 1999/08/28 00:03:03 peter Exp $
35.\" $FreeBSD: pthread_cond_signal.3,v 1.5 1999/08/28 00:03:04 peter Exp $
36.\"
37.Dd $Mdocdate: July 3 2025 $
38.Dt PTHREAD_COND_INIT 3
39.Os
40.Sh NAME
41.Nm pthread_cond_init ,
42.Nm pthread_cond_destroy ,
43.Nm pthread_cond_wait ,
44.Nm pthread_cond_timedwait ,
45.Nm pthread_cond_broadcast ,
46.Nm pthread_cond_signal
47.Nd block and unblock threads with condition variables
48.Sh SYNOPSIS
49.Lb libpthread
50.In pthread.h
51.Ft int
52.Fo pthread_cond_init
53.Fa "pthread_cond_t *cond"
54.Fa "const pthread_condattr_t *attr"
55.Fc
56.Ft int
57.Fo pthread_cond_destroy
58.Fa "pthread_cond_t *cond"
59.Fc
60.Ft int
61.Fo pthread_cond_wait
62.Fa "pthread_cond_t *cond"
63.Fa "pthread_mutex_t *mutex"
64.Fc
65.Ft int
66.Fo pthread_cond_timedwait
67.Fa "pthread_cond_t *cond"
68.Fa "pthread_mutex_t *mutex"
69.Fa "const struct timespec *abstime"
70.Fc
71.Ft int
72.Fo pthread_cond_broadcast
73.Fa "pthread_cond_t *cond"
74.Fc
75.Ft int
76.Fo pthread_cond_signal
77.Fa "pthread_cond_t *cond"
78.Fc
79.Sh DESCRIPTION
80The
81.Fn pthread_cond_init
82function creates a new condition variable with attributes specified by
83.Fa attr .
84If
85.Fa attr
86is
87.Dv NULL ,
88the default attributes are used.
89.Pp
90The
91.Fn pthread_cond_destroy
92function frees the resources associated with the condition variable
93.Fa cond .
94.Pp
95The
96.Fn pthread_cond_wait
97function atomically blocks the current thread by waiting on the condition
98variable
99.Fa cond ,
100and unlocks the mutex specified by
101.Fa mutex .
102The waiting thread unblocks only after another thread calls
103.Fn pthread_cond_broadcast
104or
105.Fn pthread_cond_signal
106with the same condition variable.
107The
108.Fn pthread_cond_timedwait
109function does the same, but returns after the system time reaches
110.Fa abstime .
111In all cases, both functions then reacquire the lock on
112.Fa mutex
113before returning.
114.Pp
115The
116.Fn pthread_cond_broadcast
117function unblocks all threads waiting for the condition variable
118.Fa cond .
119The
120.Fn pthread_cond_signal
121function unblocks at least one thread waiting for the condition variable
122.Fa cond .
123.Sh RETURN VALUES
124These functions return zero for success and positive error numbers
125for failure.
126.Sh ERRORS
127.Fn pthread_cond_init
128fails if:
129.Bl -tag -width Er
130.It Bq Er EINVAL
131The value specified by
132.Fa attr
133is invalid.
134.It Bq Er ENOMEM
135The process cannot allocate enough memory to create another condition
136variable.
137.It Bq Er EAGAIN
138The system temporarily lacks the resources to create another condition
139variable.
140.El
141.Pp
142The other functions fail if:
143.Bl -tag -width Er
144.It Bq Er EINVAL
145The value specified by
146.Fa cond ,
147.Fa mutex ,
148or
149.Fa abstime
150is invalid.
151.El
152.Pp
153.Fn pthread_cond_destroy
154additionally fails if:
155.Bl -tag -width Er
156.It Bq Er EBUSY
157The variable
158.Fa cond
159is locked by another thread.
160.El
161.Pp
162.Fn pthread_cond_timedwait
163additionally fails if:
164.Bl -tag -width Er
165.It Bq Er ETIMEDOUT
166The system time has reached or exceeded the time specified in
167.Fa abstime .
168.El
169.Sh SEE ALSO
170.Xr pthread_condattr_init 3 ,
171.Xr pthread_mutex_init 3
172.Sh STANDARDS
173These functions conform to
174.St -p1003.1-96 .