Hi Ted,

Ted Unangst wrote on Sat, Jul 05, 2025 at 12:26:22PM -0400:
> On 2025-07-04, Ingo Schwarze wrote:

>> I realize you did not add the following sentence:
>> 
>>      The results of acquiring a read lock while the calling thread
>>      holds a write lock are undefined.
>> 
>> That sentence is already in pthread_rwlock_rdlock(3), but it
>> contradicts our own manual page, which says:

> I deleted that.

Good, thanks.

>> Looking at our code, my impression is that this EDEADLK behaviour
>> is described correctly and we conform to POSIX in this respect,
>> so i think you should simply delete the two lies about undefined

> We have other lies, however. pthread_rwlock_unlock never returns any
> errors. I have left this for now. I think the entire library needs a
> fact check.

Hmm, that may well be true.  It appears the quality of documentation
produced by NetBSD and FreeBSD tends to be lower than what the CSRG
did at the UC.

>> Below HISTORY, the "first appeared in FreeBSD 3.0" might be a lie -
>> or are the functions really FreeBSD inventions?  Also, you lost part
>> of the OpenBSD history.  I'd suggest dropping the FreeBSD history
>> and simply saying:

> I dropped the section. Very few of the other pages seem to have it.
> I don't think it's very useful? We can add it back, but I'd prefer to
> consistent. We have some text in pthreads.3 about the library, maybe that
> can be expanded.

I really don't like that you dropped it.  The end goal is certainly
to have it, we have the section in libc and most other libraries.
The content is non-trivial in libpthread in particular since thread
support was added in a piece-meal manner over many years.  Adding
such information requires looking at every individual function,
so there is no great benefit to doing it all at once.  On the other
hand, researching it is harder in libpthread than elsewhere because
of how much stuff moved around among various source directories.
So deleting what has already been researched really does a disservice,
in particular during a merge, which makes it harder to notice at a
later time that the work had already been done.

So, here is a patch to put HISTORY back, sort SEE ALSO, and mop up
some trailing whitespace.  OK?


>> The STANDARDS section should probably be updated, -susv2 sounds
>> unusually old-fashioned, but no need to mix that into this diff.

> Yeah, that needs checking and consistency.
 
> I don't really like the "expected to conform" language. We don't know?
> But I also don't like "conforms to" language. Did we check? We have this
> language everywhere, but maybe we can consider it again.

I don't like "expected to conform" either, but yes, changing it
to "conforms to" does require checking.  I think checking that
should eventually be the goal - checking POSIX conformance of our
system certainly seems useful.  Until someone finds the time,
having "expected to conform" is better than nothing.

> What about saying "These functions are specified by .."? 

I don't like it.

In some cases, we deliberately deviate from misguided parts of the
standard, and clearly documenting those deviations is particularly
important.  Your "are specified by" woording makkes that harder.

Also, for some manual pages, in particular in section 1, conformance
has already been checked and STANDARDS says "conforms to".  In those
cases, your proposed wording would lose information.

Yours,
  Ingo


Index: pthread_rwlock_init.3
===================================================================
RCS file: /cvs/src/lib/libpthread/man/pthread_rwlock_init.3,v
diff -u -r1.10 pthread_rwlock_init.3
--- pthread_rwlock_init.3	5 Jul 2025 16:13:50 -0000	1.10
+++ pthread_rwlock_init.3	6 Jul 2025 10:40:37 -0000
@@ -239,7 +239,7 @@
 or writing).
 .El
 .Pp
-The 
+The
 .Fn pthread_rwlock_unlock
 fails if:
 .Bl -tag -width Er
@@ -247,10 +247,27 @@
 The current thread does not own the read/write lock.
 .El
 .Sh SEE ALSO
-.Xr pthreads 3 ,
-.Xr pthread_rwlockattr_init 3
+.Xr pthread_rwlockattr_init 3 ,
+.Xr pthreads 3
 .Sh STANDARDS
 These functions are expected to conform to
 .St -susv2 .
+.Sh HISTORY
+.Fn pthread_rwlock_init ,
+.Fn pthread_rwlock_destroy ,
+.Fn pthread_rwlock_rdlock ,
+.Fn pthread_rwlock_tryrdlock ,
+.Fn pthread_rwlock_wrlock ,
+.Fn pthread_rwlock_trywrlock ,
+and
+.Fn pthread_rwlock_unlock
+have been avaliable since
+.Ox 2.5 ,
+and
+.Fn pthread_rwlock_timedrdlock
+and
+.Fn pthread_rwlock_timedwrlock
+since
+.Ox 4.8 .
 .Sh BUGS
 The PTHREAD_PROCESS_SHARED attribute is not supported.