[PATCH v5] manual: Document clock_nanosleep

[Maciej W. Rozycki]

On Fri, 30 May 2025, Florian Weimer wrote:

> >  I think the unusual API ought to be emphasized in bold somehow; even if 
> > POSIX doesn't bother, this is a manual facing actual developers and it 
> > ought to warn people about any pitfalls.
> 
> Most pthread_* functions behave this way, and the NSS *_r functions
> that are part of POSIX.  And clock_nanosleep isn't even the only
> outlier among the clock_* functions, there is clock_getcpuclockid as
> well.

 For `pthread_*' or NSS `*_r' functions it's understandable for their 
reentrancy, though I can't claim much experience in their area, so the 
similarity would not have struck me right away.  The majority of POSIX 
APIs going back to early *nix days does use `errno' though, and that was 
in my textbook back in 1990s too.  I guess calling these two functions 
`clock_nanosleep_r' and `clock_getcpuclockid_r' would have at least 
brought some consistency and a warning sign for the reentrant API being 
used.  But that ship has sailed, sigh.

  Maciej