[patch v5] manual: add syscall list

[Florian Weimer]

* DJ Delorie:

> diff --git a/manual/startup.texi b/manual/startup.texi
> index 96a7a472bb..1680a37be2 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -690,7 +690,158 @@ 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{}:
> +@include syscalls.texi
> +
> +Here's the corresponding list of cancellable system calls:
> +@include syscallsc.texi

I think those lists are still very misleading, as the setuid issue
remains.  I don't think they do not help with the issue we are trying to
solve downstream, and I'm not sure if it helps anyone in the community.

I suggest to add references to the man-pages project for the five still
undocumented functions we need.  We could add a Wikipedia-style stub:
“This documentation is a stub.  Send a patch to improve it.”

> +In some cases, if @theglibc{} has detected that a system call has been
> +superceeded by a more capable one, the wrapper may map the old call to
> +the new one.  For example, @code{dup2} is implemented via @code{dup3}
> +by passing an additional empty flags argument, and @code{open} calls
> +@code{openat} passing the additional @code{AT_FDCWD}.  Sometimes even
> +more is done, such as converting between 32-bit and 64-bit time
> +values.  Where not documented elsewhere in this manual, such cases are
> +listed here:
> +
> +@table @code
> +
> +@item clock_nanosleep
> +Calls either @code{clock_nanosleep} or @code{clock_nanosleep_time64}.

Should we really document this?  I think people writing seccomp filters
would really like us to not change the system call footprint, but I
don't think this should be part of the API contract.

Thanks,
Florian