Re: [patch v4] manual: add syscall list

[Florian Weimer <fweimer@redhat.com>]

* Florian Weimer:

> * DJ Delorie:
>
>> diff --git a/manual/startup.texi b/manual/startup.texi
>> index 96a7a472bb..f6e0ab909c 100644
>> --- a/manual/startup.texi
>> +++ b/manual/startup.texi
>> @@ -690,7 +690,31 @@ you don't need to know about it because you can just use @theglibc{}'s
>>  @code{chmod} function.
>>  
>>  @cindex kernel call
>> -System calls are sometimes called kernel calls.
>> +System calls are sometimes called syscalls or kernel calls, and this
>> +interface is mostly a purely mechanical translation from the kernel's
>> +ABI to the C ABI. For the set of syscalls where we do not guarantee
>> +POSIX Thread cancellation the wrappers only organize the incoming
>> +arguments from the C calling convention to the calling convention of
>> +the target kernel. For the set of syscalls where we provided POSIX
>> +Thread cancellation the wrappers set some internal state in the
>> +library to support cancellation, but this does not impact the
>> +behaviour of the syscall provided by the kernel.
>> +
>> +@Theglibc{} includes by reference the Linux man-pages
>> +@value{man_pages_version} documentation to document the listed
>> +syscalls for the Linux kernel. For reference purposes only the latest
>> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
>> +documentation can be accessed from the
>> +@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
>> +has more specific documentation in this manual that more specific
>> +documentation is considered authoritative.
>> +
>> +Here is the list of all potential non-cancellable system calls, across
>> +all configurations of @theglibc():
>
> @theglibc() should be @theglibc{} (typographical error).
>
>> +@include syscalls.texi
>
> Should the list be separated by commas?  It's currently space-separated
> only.
>
> The list still includes getuid, which is most emphatically not a single
> system call in multi-threaded programs, not on Linux and not on Hurd.

Actually setuid, but fortunately it's in the list as well.

>
>> +Here's the corresponding list of cancellable system calls:
>> +@include syscallsc.texi
>
> Unfortunately, this now gives the impression that the syscall function
> described below implements a cancellable system call when called for
> SYS_read (for example).  But that's not accurate.  System calls invoked
> through the syscall function are never cancellable.
>
> Maybe add to the commit message why we are adding this?  Is this an
> attempt to achieve completeness of the manual by referencing the manual
> page for certain functions we do not document?  Maybe it would be more
> approriate to add @deftypefn directives for those specific functions,
> with a stub that refers to the corresponding man-pages URL?
>
> Do we have a rendered version of the current development version that we
> can point people to for review purposes?
>
> Thanks,
> Florian