Index | Thread | Search

From:
"Ted Unangst" <tedu@tedunangst.com>
Subject:
pthread man.3 inode conservation
To:
tech@openbsd.org
Date:
Sat, 21 Jun 2025 00:26:05 -0400

Download raw body.

Thread
How about this? There's a lot of one sentence man pages in libpthread,
which I think are probably not very useful. It's a lackluster experience
having to read four or five different man pages just to use a condition
variable. Why isn't this all in one place?

This diff more or less mechanically combines the pages. I think a bit more
narrative structure can be added, but at least you can get some idea of what
these functions are for and how they work together in a single page now.

Starting with condition variables.

Index: Makefile.inc
===================================================================
RCS file: /home/cvs/src/lib/libpthread/man/Makefile.inc,v
diff -u -p -r1.37 Makefile.inc
--- Makefile.inc	12 Jan 2019 00:16:03 -0000	1.37
+++ Makefile.inc	21 Jun 2025 04:19:48 -0000
@@ -19,13 +19,7 @@ MAN+=	\
 	pthread_barrierattr_getpshared.3 \
 	pthread_cleanup_pop.3 \
 	pthread_cleanup_push.3 \
-	pthread_condattr_init.3 \
-	pthread_cond_broadcast.3 \
-	pthread_cond_destroy.3 \
 	pthread_cond_init.3 \
-	pthread_cond_signal.3 \
-	pthread_cond_timedwait.3 \
-	pthread_cond_wait.3 \
 	pthread_cancel.3 \
 	pthread_create.3 \
 	pthread_detach.3 \
Index: pthread_cond_init.3
===================================================================
RCS file: /home/cvs/src/lib/libpthread/man/pthread_cond_init.3,v
diff -u -p -r1.13 pthread_cond_init.3
--- pthread_cond_init.3	7 Jun 2025 00:16:52 -0000	1.13
+++ pthread_cond_init.3	21 Jun 2025 04:17:28 -0000
@@ -40,6 +40,24 @@
 .In pthread.h
 .Ft int
 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
+.Ft int
+.Fn pthread_cond_destroy "pthread_cond_t *cond"
+.Ft int
+.Fn pthread_cond_broadcast "pthread_cond_t *cond"
+.Ft int
+.Fn pthread_cond_signal "pthread_cond_t *cond"
+.Ft int
+.Fn pthread_cond_wait "pthread_cond_t *cond" "pthread_mutex_t *mutex"
+.Ft int
+.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
+.Ft int
+.Fn pthread_condattr_init "pthread_condattr_t *attr"
+.Ft int
+.Fn pthread_condattr_destroy "pthread_condattr_t *attr"
+.Ft int
+.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id"
+.Ft int
+.Fn pthread_condattr_getclock "pthread_condattr_t *attr" "clockid_t *clock_id"
 .Sh DESCRIPTION
 The
 .Fn pthread_cond_init
@@ -50,12 +68,84 @@ If
 is
 .Dv NULL ,
 the default attributes are used.
+.Pp
+The
+.Fn pthread_cond_broadcast
+function unblocks all threads waiting for the condition variable
+.Fa cond .
+The
+.Fn pthread_cond_signal
+function unblocks at least one thread waiting for the condition variable
+.Fa cond .
+.Pp
+The
+.Fn pthread_cond_wait
+function atomically blocks the current thread waiting on the condition
+variable specified by
+.Fa cond ,
+and unblocks the mutex specified by
+.Fa mutex .
+The waiting thread unblocks only after another thread calls
+.Fn pthread_cond_signal
+or
+.Fn pthread_cond_broadcast
+with the same condition variable.
+The
+.Fn pthread_cond_timedwait
+function does the same, but returns after the system time reaches
+.Fa abstime .
+The current thread then reacquires the lock on
+.Fa mutex .
+.Pp
+The
+.Fn pthread_cond_destroy
+function frees the resources allocated by the condition variable
+.Fa cond .
+.Pp
+Condition variable attributes are used to specify parameters to
+.Fn pthread_cond_init .
+One attribute object can be used in multiple calls to
+.Fn pthread_cond_init ,
+with or without modifications between calls.
+.Pp
+The
+.Fn pthread_condattr_init
+function initializes
+.Fa attr
+with all the default condition variable attributes.
+.Pp
+The
+.Fn pthread_condattr_destroy
+function destroys
+.Fa attr .
+.Pp
+The
+.Fn pthread_condattr_setclock
+function sets the clock attribute of
+.Fa attr
+to the value of the
+.Fa clock_id
+parameter.
+The
+.Fn pthread_condattr_getclock
+function copies the value of the clock attribute from
+.Fa attr
+to the location pointed to by the
+.Fa clock_id
+parameter.
+The clock attribute is the ID of the clock against which the timeout of
+.Fn pthread_cond_timedwait
+is compared;
+the default value of the clock attribute is
+.Dv CLOCK_REALTIME .
 .Sh RETURN VALUES
 If successful, the
 .Fn pthread_cond_init
 function will return zero and put the new condition variable ID into
 .Fa cond ,
 otherwise an error number will be returned to indicate the error.
+Other functions similarly return zero for success and error numbers
+for failure.
 .Sh ERRORS
 .Fn pthread_cond_init
 will fail if:
@@ -71,13 +161,23 @@ variable.
 The system temporarily lacks the resources to create another condition
 variable.
 .El
+.Pp
+Other functions may fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The value specified by
+.Fa cond
+or another argument is invalid.
+.It Bq Er EBUSY
+The variable
+.Fa cond
+is locked by another thread.
+.It Bq Er ETIMEDOUT
+The system time has reached or exceeded the time specified in
+.Fa abstime .
+.El
 .Sh SEE ALSO
-.Xr pthread_cond_broadcast 3 ,
-.Xr pthread_cond_destroy 3 ,
-.Xr pthread_cond_signal 3 ,
-.Xr pthread_cond_timedwait 3 ,
-.Xr pthread_cond_wait 3
+.Xr pthread_mutex_init 3
 .Sh STANDARDS
-.Fn pthread_cond_init
-conforms to
+These functions conform to
 .St -p1003.1-96 .