[PATCH v5] manual: Document clock_nanosleep

[Florian Weimer]

* Maciej W. Rozycki:

>  Awww, that is a subtlety.  Indeed, we have a single function that has an 
> API different from all the other function.  Sorry to miss that in the 
> review.  The notion of 'errno' has been so strongly embedded in the whole 
> POSIX API, but I should have caught it anyway.
>
>  I guess we'll have to start from scratch, starting from the removal of 
> the expression of 'nanosleep' in terms of 'clock_nanosleep' and through 
> rewriting the paragraphs concerning the return value entirely.
>
>  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.