From: "Ted Unangst" Subject: pthread man.3 inode conservation To: tech@openbsd.org Date: Sat, 21 Jun 2025 00:26:05 -0400 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 .