Hello Ted,

Ted Unangst wrote on Sun, Jul 06, 2025 at 02:49:18PM -0400:
> On 2025-07-06, Ingo Schwarze wrote:
>> Ted Unangst wrote on Sat, Jul 05, 2025 at 12:31:52PM -0400:

>>> And now the same for mutex. Pretty much same as before.

>> OK schwarze@ except that you need to sort ERRORS and that you broke
>> STANDARDS.

> Sort by error number? It is currently sorted by the function. I think that
> is more useful. I would not typically look for an error, and then see if it
> applies to my function.

My bad - i meant "sort SEE ALSO", see: mandoc -T lint pthread_mutex_init.3

You are right, there is no conventional sort order for ERRORS,
sorting by function is just fine, or whatever makes sense for the
particular page.

>> The simplest way to fix this is to just keep the text as it is, i.e.
>> 
>> The functions
>> .Fn pthread_mutex_init ,
>> .Fn pthread_mutex_destroy ,
>> and
>> .Fn pthread_mutex_unlock
>> conform to
>> .St -p1003.1-96 .
>> The functions
>> .Fn pthread_mutex_lock ,
>> .Fn pthread_mutex_timedlock ,
>> and
>> .Fn pthread_mutex_trylock
>> conform to
>> .St -p1003.1-2008 .
>> 
>> That lazy copout seems acceptable for now, but not very good in the
>> long run.  It is likely to make readers wonder why we conform to
>> inconsistent standards.  It would seem desirable to check whether we
>> conform to -p1003.1-2024 and update to that if we do.

> Heh, well, I don't think I would have suggested that, but if you're okay 
> with it, then I guess. But...

>> It appears that guenther@ checked on 2012/02/24 that the three *lock*
>> functions conform to -p1003.1-2008 but didn't go any further than that.

> Checking, there are some discrepancies. Most or all of the EINVAL 
> checks have been removed, in favor of undefined behavior. Our implementation
> is compliant, but we don't distinguish between standard required and standard
> permitted behavior. A conformant application cannot rely on these checks.

In such cases, it might be useful to say stuff like the following below
STANDARDS (not a complete draft, just an example what can be said):

  .Sh STANDARDS
  The function
  .Fn pthread_mutex_init
  conforms to
  .St -p1003.1-2024 .
  .Pp
  Raising an error when
  .Fa attr
  is invalid is an extension to the standard.

That way, readers who care about portability know that they cannot
rely on that kind of misuse being caught.

> Also, our prototypes are missing the restrict keyword.

I don't think that matters.  Not having the restrict qualifier
doesn't make an implementation non-conforming because that qualifier
never changes the functionality.  Actually, unless i totally
misunderstand, the fewer restrict qualifiers an implementation has,
the safer it is, because it minimises the risk that the compiler
will over-optimise - and over-optimization is a common source of
bugs.  I hate the restrict qualifier and would certainly never use
it in my own code.  Having restrict qualifiers in library APIs feels
foolish to me because it puts additional cognitive load on application
developers (who already have their hands full writing good and safe
code without such additional, gratuitious chicanery), additional
risk of bugs on users, and when those bugs bite, the compiler
developers who have gone rampant with optimization can gleefully
blame the poor application developers who have fallen prey to a
standards feature prioritising micro-optimization over security.
Not sure whether we should delete all the restrict qualifiers from
all our library headers (including libc), but i would probably not
object to deleting them.

Yours,
  Ingo