manual: add syscall list appendix

[Carlos O'Donell]

On 5/16/24 1:55 PM, DJ Delorie wrote:
> "Carlos O'Donell" <carlos@redhat.com> writes:
>> This needs a configure argument to specify which version of the Linux man-pages project
>> release is the version we've looked at to make sure we match the behaviour for the
>> specified syscalls.
>>
>> I think we should specifically reference e.g. Linux man-pages X.Y.
> 
> Can we make that optional?  I.e. if *no* configure option is specified,
> the wording is version-agnostic?  Development in git likely doesn't care
> which version of man-pages is current, and it would be continuously
> changing anyway.  We would only need to lock-step in released versions
> of glibc, and then, we'd need to hard-code it somewhere as a default.

$0.02. No. This is similar to the Linux kernel version checks. We should have a minimum
and bump them up as we audit and review.

>> What about syscalls that have cancellation?
>>
>> We should really split them out and document that we wrap them in special cancellation
>> code (which will change a bit as I need to review Adhemerval's changes for that).
> 
> I'll see what I can do ;-)
> 
>> The intent is to say that if we didn't document anything in the glibc manual
>> that users should feel free to go read the Linux man-pages documentaiton for
>> that syscall.
>>
>> Thoughts?
> 
> It's long for an appendix.  Do we have a chapter on cancellation?  Do we
> want to be that Linux-centric?

May you please expand on what you think is long for an appendix?

There are 117 undocumented POSIX Thread APIs in glibc that we *really* need to document,
but I am not asking you to document those. We do not talk about cancellation in the manual,
but we should. I don't think we need to do that for this patch, but we should correctly
note which have cancellation support and leave it at that.

We can be as Linux-centric as we want... so long as the manual is accurate and describes
these as Linux-specific things. We do this often in the manual.

-- 
Cheers,
Carlos.