[patch v5] manual: add syscall list

[patch v5] manual: add syscall list

[DJ Delorie]

[v5: added "lightly processed" list.  Added commas.  Fixed some typos.
Still contains the unintended configure change, but this "bug" exists
in the official GNU autoconf]


The purpose of this patch is to ensure the manual is "complete" wrt
possible system calls that (1) aren't otherwise documented, and (2)
are merely redirected to the kernel.  A generated list of syscalls
which may have auto-generated wrappers is added with reference to the
Linux Man-Pages project for further details, as well as a table of
syscalls that glibc may add a slight amount of processing around them
to make them meet the C API without changing their behavior or adapt
to kernel changes.

Note: the manually created list of "lightly processed" syscalls is
intentionally not complete; syscalls which are documented elsewhere in
the manual are omitted, as are syscalls which are heavily processed
and need actual documenation (left as @comments in that list).

There are a few "lightly processed" syscalls that look like they could
be migrated to the auto-generated list (noted in @comments) but this
patch does not intend to actually change the library, only the manual.
An audit and cleanup of syscall lists and implementations would be a
separate project.

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

Co-developed-by: Alejandro Colomar <alx@kernel.org>
Signed-off-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@
 
 # 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
+
+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..8cb114b41d 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
 
 # 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; \
 	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
 	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
 	touch $@
@@ -138,6 +140,36 @@ $(objpfx)%.c.texi: examples/%.c
 	    $< | expand > $@.new
 	mv -f $@.new $@
 
+# Generate a list of potential syscall wrappers (non-cancellable)
+$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
+$(objpfx)stamp-syscalls: $(common-objpfx)config.make
+	find ../sysdeps -name syscalls.list -print \
+	| xargs sed -e '/^[^_a-zA-Z]/d' \
+		    -e '/^$$/d' \
+	            -e '/[ \t]C/d' \
+	            -e 's/[ \t].*//' \
+	            -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	| sed 's/$$/,/; $$s/,//' \
+	> $(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
+	find ../sysdeps -name syscalls.list -print \
+	| xargs sed -e '/^[^_a-zA-Z]/d' \
+		    -e '/^$$/d' \
+	            -e '/[ \t]C/!d' \
+	            -e 's/[ \t].*//' \
+	            -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	| sed 's/$$/,/; $$s/,//' \
+	> $(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..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
+
+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}.
+
+@comment clone
+@comment clone3
+
+@item creat
+Calls either @code{creat} or @code{__open}.
+
+@item epoll_create
+Calls either @code{epoll_create} or @code{epoll_creat1}.
+
+@item epoll_pwait
+Calls @code{epoll_pwait} passing an additional parameter.
+
+@item epoll_wait
+Calls either @code{epoll_wait} or @code{epoll_pwait}.
+
+@item fallocate
+Calls @code{fallocate} but promotes arguments.
+
+@item fanotify_mark
+Calls @code{fanotify_mark} promoting arguments
+
+@item fstatat64
+Calls @code{fstatat64_time64} then manages 32/64 bit conversions.
+
+@item ftime
+Calls @code{ftime64}  then manages 32/64 bit conversions.
+
+@item getdtablesize
+Calls @code{getrlimit}.
+
+@item inotify_init
+Calls @code{inotify_init} or @code{inotify_init1}.
+
+@item mknodat
+Calls @code{mknodat} handling 32/64 bit pid conversions.
+
+@comment mq_notify
+@comment mq_timedreceive
+
+@item msgctl
+Calls @code{msgctl64} and manages 32/64 bit conversions.
+
+@item msgget
+Calls @code{msgget} directly or via IPC.
+
+@item msgrcv
+Calls @code{msgrcv} directly or via IPC.
+
+@item msgsnd
+Calls @code{msgsnd} directly or via IPC.
+
+@item poll
+Calls @code{poll} or @code{ppoll}.
+
+@item prlimit64
+Provides unique versioning for HPPA.
+
+@comment putpmsg
+
+@item setresgid
+Calls @code{setresgid} or @code{setresgid32}.
+
+@item setresuid
+Calls @code{setresuid} or @code{setresuid32}.
+
+@item shmat
+Calls @code{shmat} directly or via IPC.
+
+@item shmctl
+Calls @code{shmctl} directly or via IPC.
+
+@item shmdt
+Calls @code{shmdt} directly or via IPC.
+
+@item shmget
+Calls @code{shmget} directly or via IPC.
+
+@item signalfd
+Calls @code{signalfd4}
+
+@comment sigreturn
+
+@comment splice
+@comment should be autogenerated?
+
+@item statx
+Calls @code{statx} or @code{fstata64}
+
+@comment tee
+@comment should be autogenerated?
+
+@comment timer_create
+@comment timer_delete
+@comment timer_getoverrun
+@comment timer_gettime
+@comment timer_settime
+@comment timerfd_gettime
+@comment timerfd_settime
+
+@comment ustat
+@comment just calls _old_usat?
+
+@item utimensat
+Calls @code{utimensat} or @code{utimensat_time64}
+
+@comment vmsplice
+@comment should be autogenerated?
+
+@item waitpid
+Calls @code{waitpid} passing an extra parameter the kernel expects.
+
+@end table
 
 However, there are times when you want to make a system call explicitly,
 and for that, @theglibc{} provides the @code{syscall} function.
@@ -712,6 +863,8 @@ we won't describe it here either because anyone who is coding
 library source code as a specification of the interface between them
 anyway.
 
+@code{syscall} does not provide cancellation logic, even if the system
+call you're calling is listed as cancellable above.
 
 @code{syscall} is declared in @file{unistd.h}.
 

Re: [patch v5] manual: add syscall list

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 14528 bytes --]

Hi DJ,

On Fri, May 31, 2024 at 12:26:44AM GMT, DJ Delorie wrote:
> 
> [v5: added "lightly processed" list.  Added commas.  Fixed some typos.
> Still contains the unintended configure change, but this "bug" exists
> in the official GNU autoconf]
> 
> 
> The purpose of this patch is to ensure the manual is "complete" wrt
> possible system calls that (1) aren't otherwise documented, and (2)
> are merely redirected to the kernel.  A generated list of syscalls
> which may have auto-generated wrappers is added with reference to the
> Linux Man-Pages project for further details, as well as a table of
> syscalls that glibc may add a slight amount of processing around them
> to make them meet the C API without changing their behavior or adapt
> to kernel changes.
> 
> Note: the manually created list of "lightly processed" syscalls is
> intentionally not complete; syscalls which are documented elsewhere in
> the manual are omitted, as are syscalls which are heavily processed
> and need actual documenation (left as @comments in that list).
> 
> There are a few "lightly processed" syscalls that look like they could
> be migrated to the auto-generated list (noted in @comments) but this
> patch does not intend to actually change the library, only the manual.
> An audit and cleanup of syscall lists and implementations would be a
> separate project.
> 
> Default version of man-pages is in configure.ac but can be overridden
> by --with-man-pages=X.Y
> 
> Co-developed-by: Alejandro Colomar <alx@kernel.org>
> Signed-off-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@
>  
>  # 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
> +
> +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..8cb114b41d 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
>  
>  # 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; \
>  	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
>  	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
>  	touch $@
> @@ -138,6 +140,36 @@ $(objpfx)%.c.texi: examples/%.c
>  	    $< | expand > $@.new
>  	mv -f $@.new $@
>  
> +# Generate a list of potential syscall wrappers (non-cancellable)
> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	find ../sysdeps -name syscalls.list -print \

In general, IME, find(1)'s ability to filter file names is slowish.
It probably has to do with the library it uses.

	alx@debian:~/src$ time find -name syscalls.list -print | wc -l
	108

	real	0m12.624s
	user	0m1.289s
	sys	0m3.323s

This first call sets the cache; let's ignore it.

	alx@debian:~/src$ time find -name syscalls.list -print | wc -l
	108

	real	0m1.240s
	user	0m0.444s
	sys	0m0.799s
	alx@debian:~/src$ time find -name syscalls.list -print | wc -l
	108

	real	0m1.229s
	user	0m0.499s
	sys	0m0.733s
	alx@debian:~/src$ time find -print | grep /syscalls.list$ | wc -l
	108

	real	0m1.060s
	user	0m0.362s
	sys	0m0.797s
	alx@debian:~/src$ time find -print | grep /syscalls.list$ | wc -l
	108

	real	0m1.072s
	user	0m0.416s
	sys	0m0.755s
	alx@debian:~/src$ time find -print | grep /syscalls.list$ | wc -l
	108

	real	0m1.068s
	user	0m0.358s
	sys	0m0.810s
	alx@debian:~/src$ time find -name syscalls.list -print | wc -l
	108

	real	0m1.274s
	user	0m0.511s
	sys	0m0.765s

I made this search in my entire source tree, where I have dozens of
repositories and work trees, to make it take some noticeable time.  ~20%
is not a big deal, but just wanted to let you know that it's somewhat
inefficient, in case you use it in places where you care about speed.

In any case, LGTM.

Have a lovely day!
Alex

> +	| xargs sed -e '/^[^_a-zA-Z]/d' \
> +		    -e '/^$$/d' \
> +	            -e '/[ \t]C/d' \
> +	            -e 's/[ \t].*//' \
> +	            -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	| sed 's/$$/,/; $$s/,//' \
> +	> $(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
> +	find ../sysdeps -name syscalls.list -print \
> +	| xargs sed -e '/^[^_a-zA-Z]/d' \
> +		    -e '/^$$/d' \
> +	            -e '/[ \t]C/!d' \
> +	            -e 's/[ \t].*//' \
> +	            -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	| sed 's/$$/,/; $$s/,//' \
> +	> $(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..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
> +
> +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}.
> +
> +@comment clone
> +@comment clone3
> +
> +@item creat
> +Calls either @code{creat} or @code{__open}.
> +
> +@item epoll_create
> +Calls either @code{epoll_create} or @code{epoll_creat1}.
> +
> +@item epoll_pwait
> +Calls @code{epoll_pwait} passing an additional parameter.
> +
> +@item epoll_wait
> +Calls either @code{epoll_wait} or @code{epoll_pwait}.
> +
> +@item fallocate
> +Calls @code{fallocate} but promotes arguments.
> +
> +@item fanotify_mark
> +Calls @code{fanotify_mark} promoting arguments
> +
> +@item fstatat64
> +Calls @code{fstatat64_time64} then manages 32/64 bit conversions.
> +
> +@item ftime
> +Calls @code{ftime64}  then manages 32/64 bit conversions.
> +
> +@item getdtablesize
> +Calls @code{getrlimit}.
> +
> +@item inotify_init
> +Calls @code{inotify_init} or @code{inotify_init1}.
> +
> +@item mknodat
> +Calls @code{mknodat} handling 32/64 bit pid conversions.
> +
> +@comment mq_notify
> +@comment mq_timedreceive
> +
> +@item msgctl
> +Calls @code{msgctl64} and manages 32/64 bit conversions.
> +
> +@item msgget
> +Calls @code{msgget} directly or via IPC.
> +
> +@item msgrcv
> +Calls @code{msgrcv} directly or via IPC.
> +
> +@item msgsnd
> +Calls @code{msgsnd} directly or via IPC.
> +
> +@item poll
> +Calls @code{poll} or @code{ppoll}.
> +
> +@item prlimit64
> +Provides unique versioning for HPPA.
> +
> +@comment putpmsg
> +
> +@item setresgid
> +Calls @code{setresgid} or @code{setresgid32}.
> +
> +@item setresuid
> +Calls @code{setresuid} or @code{setresuid32}.
> +
> +@item shmat
> +Calls @code{shmat} directly or via IPC.
> +
> +@item shmctl
> +Calls @code{shmctl} directly or via IPC.
> +
> +@item shmdt
> +Calls @code{shmdt} directly or via IPC.
> +
> +@item shmget
> +Calls @code{shmget} directly or via IPC.
> +
> +@item signalfd
> +Calls @code{signalfd4}
> +
> +@comment sigreturn
> +
> +@comment splice
> +@comment should be autogenerated?
> +
> +@item statx
> +Calls @code{statx} or @code{fstata64}
> +
> +@comment tee
> +@comment should be autogenerated?
> +
> +@comment timer_create
> +@comment timer_delete
> +@comment timer_getoverrun
> +@comment timer_gettime
> +@comment timer_settime
> +@comment timerfd_gettime
> +@comment timerfd_settime
> +
> +@comment ustat
> +@comment just calls _old_usat?
> +
> +@item utimensat
> +Calls @code{utimensat} or @code{utimensat_time64}
> +
> +@comment vmsplice
> +@comment should be autogenerated?
> +
> +@item waitpid
> +Calls @code{waitpid} passing an extra parameter the kernel expects.
> +
> +@end table
>  
>  However, there are times when you want to make a system call explicitly,
>  and for that, @theglibc{} provides the @code{syscall} function.
> @@ -712,6 +863,8 @@ we won't describe it here either because anyone who is coding
>  library source code as a specification of the interface between them
>  anyway.
>  
> +@code{syscall} does not provide cancellation logic, even if the system
> +call you're calling is listed as cancellable above.
>  
>  @code{syscall} is declared in @file{unistd.h}.
>  
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [patch v5] manual: add syscall list

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> In general, IME, find(1)'s ability to filter file names is slowish.
> It probably has to do with the library it uses.

If it were more than a fraction of a second, and anything other than the
manual, I'd care more about performance ;-)

Otherwise there's some readability benefit to keeping the commands
simpler.

I don't think it really matters but I'd rather not bikeshed it either.

Re: [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

Re: [patch v5] manual: add syscall list

[DJ Delorie]

Florian Weimer <fweimer@redhat.com> writes:
> I think those lists are still very misleading,

If they're wrong, then the syscalls lists are wrong.  I'm trying to
avoid having yet another manually managed thing.

Would they be less misleading if they'd been in an appendix?

> as the setuid issue remains.

setuid is documented elsewhere in the manual, and my patch includes
"Where the syscall has more specific documentation in this manual that
more specific documentation is considered authoritative."

An alternative is to manually curate the texi lists, or have a much more
complicated script to scan for which ones are documneted already.

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

Personally, I don't think glibc's manual should have any documentation
for functions provided by the kernel, unless we're documnting posix
standard behavior in the context of a "guide" that mostly covers
glibc-provided behavior.

1. We don't control the kernel functionality (or which kernel we're
running on), so our documentation would have to detail which kernels are
known to match which bits of docs.

2. We'd be duplicating the efforts of the man-pages project.  Although
they're not official kernel docs either, the kernel doesn't document its
own interfaces, so they're the best we've got.

3. They'd be Linux-specific, not covering Hurd.

4. The glibc manual is GFDL so we can't even share work with the man
pages project due to incompatible copyrights.

What I'm adding is a way to acknowledge that we provide a C interface to
the kernel, without having to write their documentation for them or
duplicate what the man pages project is already doing.

> I suggest to add references to the man-pages project for the five still
> undocumented functions we need.

Those five are in the new "lightly" managed section, btw.

> We could add a Wikipedia-style stub: “This documentation is a stub.
> Send a patch to improve it.”

That would not solve the downstream problem, though.

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

Is there a way to say what we're doing, without promising to always to
it that way?

Alternatively, we could just list the syscalls that are "lightly"
handled, without documenting the internals.

Re: [patch v5] manual: add syscall list

[Florian Weimer]

* DJ Delorie:

> Florian Weimer <fweimer@redhat.com> writes:
>> I think those lists are still very misleading,
>
> If they're wrong, then the syscalls lists are wrong.  I'm trying to
> avoid having yet another manually managed thing.

No, the syscalls.list entries are only used if there is no separate .c
or .S implementation.

>> We could add a Wikipedia-style stub: “This documentation is a stub.
>> Send a patch to improve it.”
>
> That would not solve the downstream problem, though.

Along with the reference to the man-pages project, I think it would.

>>> +@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.
>
> Is there a way to say what we're doing, without promising to always to
> it that way?
>
> Alternatively, we could just list the syscalls that are "lightly"
> handled, without documenting the internals.

Is there a requirement that we document this?

Thanks,
Florian

Re: [patch v5] manual: add syscall list

[DJ Delorie]

Florian Weimer <fweimer@redhat.com> writes:
> No, the syscalls.list entries are only used if there is no separate .c
> or .S implementation.

If those are target-specific, how do we automatically generate a
target-independent manual?

>>> We could add a Wikipedia-style stub: “This documentation is a stub.
>>> Send a patch to improve it.”
>>
>> That would not solve the downstream problem, though.
>
> Along with the reference to the man-pages project, I think it would.

That's what I'm trying to do, but without having to manually add every
kernel function.  Or any kernel function ;-)

>> Alternatively, we could just list the syscalls that are "lightly"
>> handled, without documenting the internals.
>
> Is there a requirement that we document this?

Well, the remaining functions needing downstream docs are in that
list...