From: Ingo Schwarze Subject: Re: pthread_rwlock_combo To: Ted Unangst Cc: tech@openbsd.org Date: Sun, 6 Jul 2025 12:45:57 +0200 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.