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 .