| Message ID | xnzfsh7hyn.fsf@greed.delorie.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v4] manual: add syscall list | expand |
* 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
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. >
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
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
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..d4ef8f8dd7 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,32 @@ $(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 + 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)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.
[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>