From: Ingo Schwarze Subject: Re: replace -sus instances is libpthread To: Job Snijders Cc: Theo de Raadt , Jason McIntyre , tech@openbsd.org Date: Tue, 18 Jun 2024 20:07:00 +0200 Hello Job, Job Snijders wrote on Mon, Jun 17, 2024 at 08:44:47PM +0000: > On Mon, Jun 17, 2024 at 09:07:21PM +0200, Ingo Schwarze wrote: >> I agree that replacing -susvX references with POSIX references makes >> sense where that can be done in such a way that the resulting >> statement is correct. >> >> When considering the replacement, keep in mind that so far, our policy >> has been to usually list the *latest* officially published POSIX standard >> that our implementation conforms to. That is most relevant for the >> primary audience of our manual pages, software developers: It is good >> practice to adhere to the latest stable POSIX standard when developing. > The below diff attempts to do that. I feel way out of my depth here and do not think i could reasonably provide an OK on such a diff. I believe a weasel cannot tear this apart, we need something more ferocious, maybe a cougar like guenther@. > For a number of functions the 'restrict' keyword was introduced in the > function signature in Issue 6, in such cases I used -xsh5. One such > example is: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlockattr_getpshared.html > > I checked each of the changed man pages against XSH5 > https://pubs.opengroup.org/onlinepubs/009639399/toc.pdf > and later POSIX documentation > Index: pthread_getconcurrency.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_getconcurrency.3,v > diff -u -p -r1.4 pthread_getconcurrency.3 > --- pthread_getconcurrency.3 5 Jun 2013 03:44:50 -0000 1.4 > +++ pthread_getconcurrency.3 17 Jun 2024 20:38:05 -0000 > @@ -111,4 +111,11 @@ The > and > .Fn pthread_setconcurrency > functions conform to > -.St -susv2 . > +.St -xsh5 . > +.Sh HISTORY > +The > +.Fn pthread_getconcurrency > +and > +.Fn pthread_setconcurrency > +functions are marked obsolescent in > +.St -p1003.1-2008 . According to my limited understanding, i would say something like .Sh STANDARDS The functions .Fn pthread_getconcurrency and .Fn pthread_setconcurrency conform to the X/Open System Interfaces option of the .St -p1003.1-2001 specification and have been marked as obsolescent since .St -p1003.1-2008 . (If it is true that we conform to Issue 6, because in that case Issue 6 is the latest stable standard we conform to, not Issue 5.) I think information about standards declaring obsolescence belongs in STANDARDS, not in HISTORY. HISTORY is more about implementations than about standards. Finally, has this been removed from Issue 8? In that case, i would be inclined to say: conform to the X/Open System Interfaces option of the .St -p1003.1-2001 specification, were marked as obsolescent in .St -p1003.1-2008 , and were removed from .St -p1003.1-2024 . Unless i'm blind, our manual page lacks information regarding what developers ought to use instead of these functions. > Index: pthread_mutexattr.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_mutexattr.3,v > diff -u -p -r1.6 pthread_mutexattr.3 > --- pthread_mutexattr.3 10 Nov 2015 23:48:18 -0000 1.6 > +++ pthread_mutexattr.3 17 Jun 2024 20:38:05 -0000 > @@ -174,4 +174,4 @@ conform to > and > .Fn pthread_mutexattr_gettype > conform to > -.St -susv2 > +.St -xsh5 . For all functions where our implementation conforms, this should be -p1003.1-2008 (or even -p1003.1-2024). If our implementation lacks "restrict", maybe theat ought to be fixed in the code? Again, ask the cougars. If, for a given function, we intentionally do not follow a newer standard, give the latest we do follow, so -xsh5 might possibly be adequate for such cases. It can happen that different functions in the same manual page have to be documented to follow different standards. In general, that isn't a particularly desirable situation, but i believe it can be required in some unusual cases. > Index: pthread_rwlock_destroy.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlock_destroy.3,v > diff -u -p -r1.9 pthread_rwlock_destroy.3 > --- pthread_rwlock_destroy.3 5 Jun 2013 03:44:50 -0000 1.9 > +++ pthread_rwlock_destroy.3 17 Jun 2024 20:38:05 -0000 > @@ -73,7 +73,7 @@ is invalid. > The > .Fn pthread_rwlock_destroy > function is expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > .Fn pthread_rwlock_destroy dto. I guess i'm aborting my review here, it seems i'm not really helping much without understanding the subject matter. But i do think this likely needs more work before commit. Please also consider whether postponing this until Issue 8 becomes available could save time. It would be a pity if we spend time now to change it all to Issue 7, then spend time again to change it all to Issue 8 shortly afterwards. Yours Inngo > Index: pthread_rwlock_init.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlock_init.3,v > diff -u -p -r1.8 pthread_rwlock_init.3 > --- pthread_rwlock_init.3 5 Jun 2013 03:44:50 -0000 1.8 > +++ pthread_rwlock_init.3 17 Jun 2024 20:38:05 -0000 > @@ -90,7 +90,7 @@ is invalid. > The > .Fn pthread_rwlock_init > function is expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > .Fn pthread_rwlock_init > Index: pthread_rwlock_rdlock.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlock_rdlock.3,v > diff -u -p -r1.12 pthread_rwlock_rdlock.3 > --- pthread_rwlock_rdlock.3 13 Feb 2019 23:54:10 -0000 1.12 > +++ pthread_rwlock_rdlock.3 17 Jun 2024 20:38:05 -0000 > @@ -138,11 +138,13 @@ The > and > .Fn pthread_rwlock_tryrdlock > functions are expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > .Fn pthread_rwlock_rdlock > -function first appeared in > +and > +.Fn pthread_rwlock_tryrdlock > +functions first appeared in > .Fx 3.0 > and > .Ox 2.5 . > Index: pthread_rwlock_unlock.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlock_unlock.3,v > diff -u -p -r1.8 pthread_rwlock_unlock.3 > --- pthread_rwlock_unlock.3 5 Jun 2013 03:44:50 -0000 1.8 > +++ pthread_rwlock_unlock.3 17 Jun 2024 20:38:05 -0000 > @@ -72,7 +72,7 @@ The current thread does not own the read > The > .Fn pthread_rwlock_unlock > function is expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > .Fn pthread_rwlock_unlock > Index: pthread_rwlock_wrlock.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlock_wrlock.3,v > diff -u -p -r1.11 pthread_rwlock_wrlock.3 > --- pthread_rwlock_wrlock.3 13 Feb 2019 23:54:10 -0000 1.11 > +++ pthread_rwlock_wrlock.3 17 Jun 2024 20:38:05 -0000 > @@ -116,11 +116,13 @@ The > and > .Fn pthread_rwlock_trywrlock > functions are expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > +.Fn pthread_rwlock_trywrlock > +and > .Fn pthread_rwlock_wrlock > -function first appeared in > +functions first appeared in > .Fx 3.0 > and > .Ox 2.5 . > Index: pthread_rwlockattr_destroy.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlockattr_destroy.3,v > diff -u -p -r1.10 pthread_rwlockattr_destroy.3 > --- pthread_rwlockattr_destroy.3 5 Jun 2013 03:44:50 -0000 1.10 > +++ pthread_rwlockattr_destroy.3 17 Jun 2024 20:38:05 -0000 > @@ -61,7 +61,7 @@ is invalid. > The > .Fn pthread_rwlockattr_destroy > function is expected to conform to > -.St -susv2 . > +.St -p1003.1-2008 . > .Sh HISTORY > The > .Fn pthread_rwlockattr_destroy > Index: pthread_rwlockattr_getpshared.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlockattr_getpshared.3,v > diff -u -p -r1.10 pthread_rwlockattr_getpshared.3 > --- pthread_rwlockattr_getpshared.3 5 Jun 2013 03:44:50 -0000 1.10 > +++ pthread_rwlockattr_getpshared.3 17 Jun 2024 20:38:06 -0000 > @@ -74,7 +74,7 @@ is invalid. > The > .Fn pthread_rwlockattr_getpshared > function is expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > .Fn pthread_rwlockattr_getpshared > Index: pthread_rwlockattr_init.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlockattr_init.3,v > diff -u -p -r1.9 pthread_rwlockattr_init.3 > --- pthread_rwlockattr_init.3 5 Jun 2013 03:44:50 -0000 1.9 > +++ pthread_rwlockattr_init.3 17 Jun 2024 20:38:06 -0000 > @@ -60,7 +60,7 @@ Insufficient memory exists to initialize > The > .Fn pthread_rwlockattr_init > function is expected to conform to > -.St -susv2 . > +.St -p1003.1-2008 . > .Sh HISTORY > The > .Fn pthread_rwlockattr_init > Index: pthread_rwlockattr_setpshared.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_rwlockattr_setpshared.3,v > diff -u -p -r1.10 pthread_rwlockattr_setpshared.3 > --- pthread_rwlockattr_setpshared.3 5 Jun 2013 03:44:50 -0000 1.10 > +++ pthread_rwlockattr_setpshared.3 17 Jun 2024 20:38:06 -0000 > @@ -76,7 +76,7 @@ is invalid. > The > .Fn pthread_rwlockattr_setpshared > function is expected to conform to > -.St -susv2 . > +.St -xsh5 . > .Sh HISTORY > The > .Fn pthread_rwlockattr_setpshared > Index: pthread_schedparam.3 > =================================================================== > RCS file: /cvs/src/lib/libpthread/man/pthread_schedparam.3,v > diff -u -p -r1.6 pthread_schedparam.3 > --- pthread_schedparam.3 10 Nov 2015 23:48:18 -0000 1.6 > +++ pthread_schedparam.3 17 Jun 2024 20:38:06 -0000 > @@ -89,4 +89,4 @@ Non-existent thread > and > .Fn pthread_getschedparam > conform to > -.St -susv2 > +.St -xsh5 .