Re: [patch v4] manual: add syscall list

[DJ Delorie <dj@redhat.com>]

Florian Weimer <fweimer@redhat.com> writes:
> @theglibc() should be @theglibc{} (typographical error).

Fixed.

>> +@include syscalls.texi
>
> Should the list be separated by commas?  It's currently space-separated
> only.

The script to generate it would have to be much more complicated to put
commas after every line *except* the last line, and I didn't want to
involve something like perl or python.

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

As I noted before, I'm all for cleaning up the syscalls.list files, but
this patch is independent of that problem.  setuid is listed as a
wrapped syscall in sysdeps/unix/syscalls.list.  If that's not true,
take it off that list.

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

I can add a note about that in the syscall() text.

> Maybe add to the commit message why we are adding this?

We are adding this because the kernel folks don't have authoritative
documentation for their APIs.  The best they have is the man pages
project, which is an independent, volunteer, and cross-OS effort.  Since
glibc is providing wrappers for syscalls, we get blamed for not
documenting *our* APIs (the wrappers).  This "blame" prevents glibc from
being used in certain paperwork-heavy situations.  The only alternative
is to document these functions ourselves, but because of the GFDL we
can't share the man-pages project's efforts.  I'm not sure how to
document that politely ;-)

> Is this an attempt to achieve completeness of the manual by
> referencing the manual page for certain functions we do not document?

No, it's an attempt to achieve completeness by referencing the man pages
for functions we do not *control*.

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

To do that cleanly, they'd have to be integrated throughout the manual
as each function's purpose deems apropriate.  Plus, the parameters would
still need to be documented or at least enumerated.  Otherwise, it
becomes just a more complex scripting, without real benefit.

> Do we have a rendered version of the current development version that we
> can point people to for review purposes?

I posted a PDF in a separate email.