[v4] manual: add syscall list

  [v4 cleans up comment text and list prefixes]

Default version of man-pages is in configure.ac but can be overridden
by --with-man-pages=X.Y

Reviewed-by: Alejandro Colomar <alx@kernel.org>
  

* 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
  

* 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
  

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.
  

PDF pages 861-863 ; posting the whole pdf exceeds the lists' message
size limit.
  

Hi DJ,

On Wed, May 22, 2024 at 03:41:04PM GMT, DJ Delorie wrote:
> [v4 cleans up comment text and list prefixes]
> 
> Default version of man-pages is in configure.ac but can be overridden
> by --with-man-pages=X.Y
> 
> Reviewed-by: Alejandro Colomar <alx@kernel.org>
> 

[...]

> +# Generate a list of potential syscall wrappers (non-cancellable)
> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \

I would change the line above to avoid `` --or $()--, by using xargs(1),
which is simpler, IMO.  While rewriting this line, I'd also remove the
'-print' action since it's the default, and also change -name by a
simpler grep(1):

	find ../sysdeps -type f \
	| grep '/syscalls.list$' \
	| xargs sed ... \

grep(1) is also easier to understand than the many file-name variants
that find(1) has available (and with some luck, spreads the work load to
more CPUs, finishing faster).

> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \

For writing a comma separated list, you can use something similar to a
script I wrote for the git-commit subject prefixes that I use in the
Linux man-pages project:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/scripts/bash_aliases#n146>

For your case, it would be:

	... \
	| sort \
	| uniq \
	| sed 's/$/, /' \
	| tr -d '\n' \
	| sed 's/, $//' \
	> ...

which separates with ", ".  Or if you want ",\n" as the separator, it
would be:

	... \
	| sort \
	| uniq \
	| sed 's/$/,/' \
	| sed '$s/,$//' \
	> ...

No need to use perl(1) nor python(1).  ;)
If you take those snippets, please add

	Co-developed-by: Alejandro Colomar <alx@kernel.org>
	Signed-off-by: Alejandro Colomar <alx@kernel.org>

Have a lovely night!
Alex

> +	> $(objpfx)syscalls-tmp
> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> +	touch $@
> +
> +# Generate a list of potential syscall wrappers (cancellable)
> +$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
> +$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \
> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/!d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscallsc-tmp
> +	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
> +	touch $@
> +
>  $(objpfx)%.info: %.texinfo
>  	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
>  
> 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():
> +@include syscalls.texi
> +
> +Here's the corresponding list of cancellable system calls:
> +@include syscallsc.texi
>  
>  However, there are times when you want to make a system call explicitly,
>  and for that, @theglibc{} provides the @code{syscall} function.
>
  

* DJ Delorie:

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

I think that should do it?

  … | xargs | sed 's/ /, /g' | …

It's not completely reliable in general (-n and -e as initial strings
are special), but it would work in this context.

Thanks,
Florian
  

On Mai 23 2024, Florian Weimer wrote:

> * DJ Delorie:
>
>> 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.
>
> I think that should do it?
>
>   … | xargs | sed 's/ /, /g' | …

    ... | sed '$b;s/$/,/' | ...
  

On Wed, May 22, 2024, at 3:41 PM, DJ Delorie wrote:
> [v4 cleans up comment text and list prefixes]

I saw something go by earlier about previous reviewers not being
confident in their understanding of the changes to the configure.ac,
so let me jump in and review that part...

> --- a/configure.ac
> +++ b/configure.ac
> @@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
>  	    [timeoutfactor=1])
>  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
> 
> +man_pages_version=6.8
> +
> +AC_ARG_WITH([man-pages],
> +	    AS_HELP_STRING([--with-man-pages=VERSION],
> +			   [tie manual to a specific man-pages version]),
> +	    [man_pages_version=$withval],
> +	    [])
> +AC_SUBST(man_pages_version)
> +
>  AC_ARG_ENABLE([sanity-checks],
>  	      AS_HELP_STRING([--disable-sanity-checks],
>  			     [really do not use threads (should not be used except in 

This is fine as is.  I might suggest a tiny change: instead of
setting the default value for man_pages_version above the AC_ARG_WITH,
set it in the action-if-not-given:

>  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
> 
> +AC_ARG_WITH([man-pages],
> +	    AS_HELP_STRING([--with-man-pages=VERSION],
> +			   [tie manual to a specific man-pages version]),
> +	    [man_pages_version=$withval],
> +	    [man_pages_version=6.8])
> +AC_SUBST(man_pages_version)

Also, I wonder if it makes sense to tie the default here to the
default for --enable-kernel, assuming there is one.

I don’t believe there are any strong reasons to M4-quote or not
M4-quote the argument to AC_SUBST, since shell variable names tend not
to be also M4 macro names, so please just make sure the way you did it
is consistent with AC_SUBSTs elsewhere in the file.


> --- a/config.make.in
> +++ b/config.make.in
> @@ -91,6 +91,7 @@ use-nscd = @use_nscd@
>  build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
>  build-pt-chown = @build_pt_chown@
>  pthread-in-libc = @pthread_in_libc@
> +man-pages-version = @man_pages_version@
> 
>  # Build tools.
>  CC = @CC@

Standard update to expose a new @subst@ as a make variable.

> --- a/configure
> +++ b/configure
...
> @@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
>  then :
>    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX 
> option to enable C++11 features" >&5
>  printf %s "checking for $CXX option to enable C++11 features... " >&6; 
> }
> -if test ${ac_cv_prog_cxx_cxx11+y}
> +if test ${ac_cv_prog_cxx_11+y}
>  then :
...

This looks like you didn’t use the same version of Autoconf as the
last person to update configure.ac.  As I understand it we’re trying
to stick to a constant version.  Check with Joseph Myers for what you
should be using.

zw
  

"Zack Weinberg" <zack@owlfolio.org> writes:
>> +man_pages_version=6.8
>> +
>> +AC_ARG_WITH([man-pages],
>> +	    AS_HELP_STRING([--with-man-pages=VERSION],
>> +			   [tie manual to a specific man-pages version]),
>> +	    [man_pages_version=$withval],
>> +	    [])
>> +AC_SUBST(man_pages_version)
>> +
>>  AC_ARG_ENABLE([sanity-checks],
>>  	      AS_HELP_STRING([--disable-sanity-checks],
>>  			     [really do not use threads (should not be used except in 
>
> This is fine as is.  I might suggest a tiny change: instead of
> setting the default value for man_pages_version above the AC_ARG_WITH,
> set it in the action-if-not-given:

I started that way, but moved it out so it would be more obvious where
to change the value when the time comes.  This is the same thing we do
with the minimum kernel version, although in that case the default value
is spread across target-specific files.

> Also, I wonder if it makes sense to tie the default here to the
> default for --enable-kernel, assuming there is one.

--enable-kernel sets a minimum kernel version, whereas the man pages is
typically going to be the latest (maximum) version.

>> -if test ${ac_cv_prog_cxx_cxx11+y}
>> +if test ${ac_cv_prog_cxx_11+y}
>>  then :
> ...
>
> This looks like you didn’t use the same version of Autoconf as the
> last person to update configure.ac.  As I understand it we’re trying
> to stick to a constant version.  Check with Joseph Myers for what you
> should be using.

I used verison 2.71 (as noted in configure) right from the GNU ftp site.

The last time this line was changed, it was from
c6cb8783b5fb5896cb63fe9008b6a33351f3c777 which changed us from autoconf
2.69 to 2.71.

It turns out Fedora has added a patch to 2.71 that makes the '-' side of
the changes noted; which means that we can't use Fedora's autoconf if the
rule is (as documented) "GNU autoconf 2.71 (exactly)".

Or we need to change the rules.

  "If you change any of the 'configure.ac' files you will also need

     * GNU 'autoconf' 2.71 (exactly)"
  

[cc list trimmed and Joseph added]

On Thu, May 23, 2024, at 3:38 PM, DJ Delorie wrote:
>> This is fine as is.  I might suggest a tiny change: instead of
>> setting the default value for man_pages_version above the AC_ARG_WITH,
>> set it in the action-if-not-given:
>
> I started that way, but moved it out so it would be more obvious where
> to change the value when the time comes.  This is the same thing we do
> with the minimum kernel version, although in that case the default value
> is spread across target-specific files.

OK, if we're doing the same thing elsewhere then it's good to be consistent.

> --enable-kernel sets a minimum kernel version, whereas the man pages is
> typically going to be the latest (maximum) version.

I see.

>> This looks like you didn’t use the same version of Autoconf as the
>> last person to update configure.ac.  As I understand it we’re trying
>> to stick to a constant version.  Check with Joseph Myers for what you
>> should be using.
>
> I used verison 2.71 (as noted in configure) right from the GNU ftp site.
>
> The last time this line was changed, it was from
> c6cb8783b5fb5896cb63fe9008b6a33351f3c777 which changed us from autoconf
> 2.69 to 2.71.
>
> It turns out Fedora has added a patch to 2.71 that makes the '-' side of
> the changes noted; which means that we can't use Fedora's autoconf if the
> rule is (as documented) "GNU autoconf 2.71 (exactly)".
>
> Or we need to change the rules.

I have no opinion here.  Joseph, do you have an opinion?

zw
  

"Zack Weinberg" <zack@owlfolio.org> writes:
> I have no opinion here.  Joseph, do you have an opinion?

For completeness, here's the Fedora patch...

+From f460883035ef849a2248b1713f711292ec19f4f0 Mon Sep 17 00:00:00 2001
+From: Emanuele Giaquinta <emanuele.giaquinta@gmail.com>
+Date: Fri, 14 May 2021 09:06:20 +0300
+Subject: [PATCH] _AC_PROG_CXX_STDCXX_EDITION_TRY: fix typo in variable name
+
+The typo causes "ac_prog_cxx_stdcxx" to be always set to "cxx11",
+regardless of whether the C++ compiler supports C++11.
+Message-Id: <YJ4TXAeJcvU0oSec@FSAPPLE2215.fi.f-secure.com>
+(tiny change)
+---
+ lib/autoconf/c.m4 | 4 ++--
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+
+diff --git a/lib/autoconf/c.m4 b/lib/autoconf/c.m4
+index 9f881f0b..47434c89 100644
+--- a/lib/autoconf/c.m4
++++ b/lib/autoconf/c.m4
+@@ -2749,8 +2749,8 @@ AC_DEFUN([_AC_PROG_CXX_STDCXX_EDITION_TRY],
+ [AC_REQUIRE([_AC_CXX_CXX$1_TEST_PROGRAM])]dnl
+ [AS_IF([test x$ac_prog_cxx_stdcxx = xno],
+ [AC_MSG_CHECKING([for $CXX option to enable C++$1 features])
+-AC_CACHE_VAL(ac_cv_prog_cxx_$1,
+-[ac_cv_prog_cxx_$1=no
++AC_CACHE_VAL(ac_cv_prog_cxx_cxx$1,
++[ac_cv_prog_cxx_cxx$1=no
+ ac_save_CXX=$CXX
+ AC_LANG_CONFTEST([AC_LANG_DEFINES_PROVIDED][$][ac_cxx_conftest_cxx$1_program])
+ for ac_arg in '' m4_normalize(m4_defn([_AC_CXX_CXX$1_OPTIONS]))
+-- 
+2.37.2
+
  

On Thu, 23 May 2024, Zack Weinberg wrote:

> >> This looks like you didn’t use the same version of Autoconf as the
> >> last person to update configure.ac.  As I understand it we’re trying
> >> to stick to a constant version.  Check with Joseph Myers for what you
> >> should be using.
> >
> > I used verison 2.71 (as noted in configure) right from the GNU ftp site.
> >
> > The last time this line was changed, it was from
> > c6cb8783b5fb5896cb63fe9008b6a33351f3c777 which changed us from autoconf
> > 2.69 to 2.71.
> >
> > It turns out Fedora has added a patch to 2.71 that makes the '-' side of
> > the changes noted; which means that we can't use Fedora's autoconf if the
> > rule is (as documented) "GNU autoconf 2.71 (exactly)".
> >
> > Or we need to change the rules.
> 
> I have no opinion here.  Joseph, do you have an opinion?

We should be using the unmodified upstream version to generate the 
checked-in files.
  

Hi Zack,

On Thu, May 23, 2024 at 12:59:13PM GMT, Zack Weinberg wrote:
> On Wed, May 22, 2024, at 3:41 PM, DJ Delorie wrote:
> > [v4 cleans up comment text and list prefixes]
> 
> I saw something go by earlier about previous reviewers not being
> confident in their understanding of the changes to the configure.ac,
> so let me jump in and review that part...

That was me.  :)

> >  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
> > 
> > +AC_ARG_WITH([man-pages],
> > +	    AS_HELP_STRING([--with-man-pages=VERSION],
> > +			   [tie manual to a specific man-pages version]),
> > +	    [man_pages_version=$withval],
> > +	    [man_pages_version=6.8])
> > +AC_SUBST(man_pages_version)
> 
> Also, I wonder if it makes sense to tie the default here to the
> default for --enable-kernel, assuming there is one.

The versions of the Linux man-pages project are independent of the Linux
kernel ones.  In fact, I think all of my releases will be 6.x, and 7.x
will be for whoever is the maintainer after me.

Have a lovely night!
Alex