[patch v4] manual: add syscall list

[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.

> +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