[patch v4] manual: add syscall list
DJ Delorie
dj@redhat.com
Wed May 22 19:41:04 GMT 2024
[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>
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.
More information about the Libc-alpha
mailing list