[v3] manual: add syscall list

Alejandro Colomar <alx@kernel.org> writes:
> Current upstream is 6.8; you may want to choose that one.

[v3 has the above, plus a syntax change to allow .info files, hopefully
this one will pass CI]

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>

On 5/21/24 4:04 PM, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
>> Current upstream is 6.8; you may want to choose that one.

Passes CI/CD:
https://patchwork.sourceware.org/project/glibc/patch/xn5xv77wym.fsf@greed.delorie.com/

Thank you!

Needs a few changes IMO.

Looking forward to v4.

> [v3 has the above, plus a syntax change to allow .info files, hopefully
> this one will pass CI]
> 
> 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>
> 
> diff --git a/config.make.in b/config.make.in
> index 55e8b7563b..36096881b7 100644
> --- 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@

OK. Encoded version.

>  
>  # Build tools.
>  CC = @CC@
> diff --git a/configure b/configure
> index 432e40a592..73ec5cdd66 100755
> --- a/configure
> +++ b/configure
> @@ -706,6 +706,7 @@ force_install
>  bindnow
>  hardcoded_path_in_tests
>  enable_timezone_tools
> +man_pages_version
>  rtld_early_cflags
>  extra_nonshared_cflags
>  sysheaders
> @@ -787,6 +788,7 @@ with_headers
>  with_nonshared_cflags
>  with_rtld_early_cflags
>  with_timeoutfactor
> +with_man_pages
>  enable_sanity_checks
>  enable_shared
>  enable_profile
> @@ -1509,6 +1511,8 @@ Optional Packages:
>                            build early initialization with additional CFLAGS
>    --with-timeoutfactor=NUM
>                            specify an integer to scale the timeout
> +  --with-man-pages=VERSION
> +                          tie manual to a specific man-pages version
>    --with-cpu=CPU          select code for CPU variant
>  
>  Some influential environment variables:
> @@ -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 :
>    printf %s "(cached) " >&6
>  else $as_nop
> -  ac_cv_prog_cxx_cxx11=no
> +  ac_cv_prog_cxx_11=no
>  ac_save_CXX=$CXX
>  cat confdefs.h - <<_ACEOF >conftest.$ac_ext
>  /* end confdefs.h.  */
> @@ -4137,11 +4141,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++98 features" >&5
>  printf %s "checking for $CXX option to enable C++98 features... " >&6; }
> -if test ${ac_cv_prog_cxx_cxx98+y}
> +if test ${ac_cv_prog_cxx_98+y}
>  then :
>    printf %s "(cached) " >&6
>  else $as_nop
> -  ac_cv_prog_cxx_cxx98=no
> +  ac_cv_prog_cxx_98=no
>  ac_save_CXX=$CXX
>  cat confdefs.h - <<_ACEOF >conftest.$ac_ext
>  /* end confdefs.h.  */
> @@ -4374,6 +4378,17 @@ fi
>  printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
>  
>  
> +man_pages_version=6.8
> +
> +
> +# Check whether --with-man-pages was given.
> +if test ${with_man_pages+y}
> +then :
> +  withval=$with_man_pages; man_pages_version=$withval
> +fi
> +
> +
> +
>  # Check whether --enable-sanity-checks was given.
>  if test ${enable_sanity_checks+y}
>  then :
> diff --git a/configure.ac b/configure.ac
> index bdc385d03c..bdd82a8356 100644
> --- 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

OK. Good, base version we audited up to.

> +
> +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 special situations) @<:@default=yes@:>@]),
> diff --git a/manual/Makefile b/manual/Makefile
> index b5fda4a7ae..1d5b557fa8 100644
> --- a/manual/Makefile
> +++ b/manual/Makefile
> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
>  
>  # Generated files directly included from libc.texinfo.
>  libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
> -		      libm-err.texi version.texi pkgvers.texi
> +		      libm-err.texi version.texi pkgvers.texi \
> +		      syscalls.texi syscallsc.texi

OK. Two new texi files.

>  
>  # Add path to build dir for generated files
>  texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
> @@ -117,6 +118,7 @@ $(objpfx)stamp-pkgvers: $(common-objpfx)config.make
>  	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
>  	fi
>  	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
> +	echo "@set man_pages_version $(man-pages-version)" >> $(objpfx)pkgvers-tmp; \

OK.

>  	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
>  	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
>  	touch $@
> @@ -138,6 +140,31 @@ $(objpfx)%.c.texi: examples/%.c
>  	    $< | expand > $@.new
>  	mv -f $@.new $@
>  
> +# Generate a list of wrapped syscalls

s/wrapped syscalls/syscall wrappers (non-cancellable)... /g

> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \

OK. This scans *all targets* and generates *all syscalls* regardless of if the
configuration is used or unused. This makes the list architecture agnostic. We
will need to say something about that later.

> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscalls-tmp
> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> +	touch $@
> +# Cancelled syscalls

s/Cancelled/... and cancellable syscall wrappers/g

> +$(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..527e4d4795 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -690,7 +690,30 @@ 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.

This needs extra information to say that this list covers all targets provided by glibc.

When posting v4 may you please post a PDF of the final results from `make pdf?`

Thank you!

> +
> +Non-cancellable system calls:
> +@include syscalls.texi
> +
> +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.
>