From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by sourceware.org (Postfix) with ESMTPS id D74AA38432D0 for ; Fri, 31 May 2024 20:11:11 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org D74AA38432D0 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=kernel.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=kernel.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org D74AA38432D0 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=139.178.84.217 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1717186274; cv=none; b=LuLfxepRrW2vuSEw+pXOYyUK3GHrfFOQy34bTrlIBcdCdpqavmrmUFlBsbDz7PxaiJ2k1Spr727/DYgnYZiYY4BaWPK/sHsn4DqPwf/vfc4ixMG1rXCVicQIukIUB8cT/Jc8lNCXmaXOnv6sGs8ACKT/qG4sg0U/yez2Atm4wJY= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1717186274; c=relaxed/simple; bh=Lo1p1tBGbpv99uR2brxTD32clFl9Uz4WAhFlWbhwBqM=; h=DKIM-Signature:Date:From:To:Subject:Message-ID:MIME-Version; b=j3o9w8sbyQz6Zgujcacm0qmtCtKkHdxtlhzGP9LCvraNNhyC7J0q6US1AWcl84infa8fNSIza3a3Ayo6jtjyJhw1LdEUy+Un//QbxMVMBDtOh58nOQx5Vvvv6QkfECARU1RWLEEEDMYtMbHmWzz0TqxzozfOtlVGCKqcWLlsRrQ= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 535896286E; Fri, 31 May 2024 20:11:11 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 351D8C116B1; Fri, 31 May 2024 20:11:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1717186271; bh=Lo1p1tBGbpv99uR2brxTD32clFl9Uz4WAhFlWbhwBqM=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=XzLBp/kXhC3k+71vd4ihCMiaJuOj8dozzQz++I03Shir6nSqhtQ/GZc3d5rr8K+0n v8RXzix57n69omsxOvnODMum4pw5k6Wv/Na7OAQUwdTZqu8zv61h8WyAO9u+7X/O04 WiAbV6mCz8u662gIl1RLtHXzIcqfT3Eh2oRxqH7Bb/I41k3roWQKlx6/z/ErfPEn+S fXywPWfUCrOq/lHx3yaYY43n4eMjSV+xSMuJJOx76KtNuw6HYwLj952BZqJmesL4Je v92eJH0fGx5Rd0gVWXztBDGHqW+Dd3PmMjHsNQjbzw2hXakMBCi+Vk6FzxFzXIkduc DovEFVMeOwl+g== Date: Fri, 31 May 2024 22:11:08 +0200 From: Alejandro Colomar To: DJ Delorie Cc: Carlos O'Donell , libc-alpha@sourceware.org Subject: Re: [patch v5] manual: add syscall list Message-ID: References: MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="5wqacc3nq757qqz6" Content-Disposition: inline In-Reply-To: X-Spam-Status: No, score=-10.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,SPF_HELO_NONE,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: --5wqacc3nq757qqz6 Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable From: Alejandro Colomar To: DJ Delorie Cc: Carlos O'Donell , libc-alpha@sourceware.org Subject: Re: [patch v5] manual: add syscall list References: MIME-Version: 1.0 In-Reply-To: Hi DJ, On Fri, May 31, 2024 at 12:26:44AM GMT, DJ Delorie wrote: >=20 > [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] >=20 >=20 > 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. >=20 > 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). >=20 > 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. >=20 > Default version of man-pages is in configure.ac but can be overridden > by --with-man-pages=3DX.Y >=20 > Co-developed-by: Alejandro Colomar > Signed-off-by: Alejandro Colomar >=20 > 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 =3D @use_nscd@ > build-hardcoded-path-in-tests=3D @hardcoded_path_in_tests@ > build-pt-chown =3D @build_pt_chown@ > pthread-in-libc =3D @pthread_in_libc@ > +man-pages-version =3D @man_pages_version@ > =20 > # Build tools. > CC =3D @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 CFL= AGS > --with-timeoutfactor=3DNUM > specify an integer to scale the timeout > + --with-man-pages=3DVERSION > + tie manual to a specific man-pages version > --with-cpu=3DCPU select code for CPU variant > =20 > Some influential environment variables: > @@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx =3D 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=3Dno > + ac_cv_prog_cxx_11=3Dno > ac_save_CXX=3D$CXX > cat confdefs.h - <<_ACEOF >conftest.$ac_ext > /* end confdefs.h. */ > @@ -4137,11 +4141,11 @@ if test x$ac_prog_cxx_stdcxx =3D 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=3Dno > + ac_cv_prog_cxx_98=3Dno > ac_save_CXX=3D$CXX > cat confdefs.h - <<_ACEOF >conftest.$ac_ext > /* end confdefs.h. */ > @@ -4374,6 +4378,17 @@ fi > printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h > =20 > =20 > +man_pages_version=3D6.8 > + > + > +# Check whether --with-man-pages was given. > +if test ${with_man_pages+y} > +then : > + withval=3D$with_man_pages; man_pages_version=3D$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=3D1]) > AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor) > =20 > +man_pages_version=3D6.8 > + > +AC_ARG_WITH([man-pages], > + AS_HELP_STRING([--with-man-pages=3DVERSION], > + [tie manual to a specific man-pages version]), > + [man_pages_version=3D$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=3Dyes@:>@]), > diff --git a/manual/Makefile b/manual/Makefile > index b5fda4a7ae..8cb114b41d 100644 > --- a/manual/Makefile > +++ b/manual/Makefile > @@ -55,7 +55,8 @@ examples =3D $(filter %.c.texi, $(texis)) > =20 > # Generated files directly included from libc.texinfo. > libc-texi-generated =3D 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 > =20 > # Add path to build dir for generated files > texis-path :=3D $(filter-out $(libc-texi-generated) summary.texi $(examp= les), \ > @@ -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 $@ > =20 > +# 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=3DC LC_ALL=3DC $(MAKEINFO) -P $(objpfx) --output=3D$@ $< > =20 > 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 jus= t use @theglibc{}'s > @code{chmod} function. > =20 > @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 > =20 > 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 i= s coding > library source code as a specification of the interface between them > anyway. > =20 > +@code{syscall} does not provide cancellation logic, even if the system > +call you're calling is listed as cancellable above. > =20 > @code{syscall} is declared in @file{unistd.h}. > =20 >=20 --=20 --5wqacc3nq757qqz6 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEE6jqH8KTroDDkXfJAnowa+77/2zIFAmZaLtUACgkQnowa+77/ 2zKfwhAAj7lpCkdJSlfHcBnkt8bZoexJFC3YTd1Ypjy5w5QnGkSYgOFVLD8X/K/i pNRf1pLWmInPHta516gR+mrc2ANlP94aGkKIrN+7iougOSs6jL6penEJrB8yecHo YYg1GlCAD4o9FluEFB8psY4pREITL9tVz0MB8QN4UvaUn220Gyx5Di2XYuxo7AI4 vy1W0eoo1C1hEQEpkMzr4Aai8qKM+XOvRNArIdFDBbZsYt++xt2Z+vTTmp2rQDcr d3lO1Woi63AqhfAPl5EaCXkHfbH77ivzBZ9TI57oYGQahTEKHEXPAF/1EVX5yDpd Un0lGq1EjLrKgsaFNRxk2stDaBAQYdZh71o0GaJWc32/KiR/BqpNsQB5akAnRaMW FGC5BhFIVvNoNpNG99HU7FWgoKLC3zYIkF+lKKrtX7o1dajtSxO1RPit0h3SfwmN cBmsZMvKpnzcvZxiAOslTkUMwNxZZUrMtia7r0wyk1JDsmqtboFP/wGMtR1G2NDo SsjGVRZniZrOrCiyXNZod9agVb0HpwrROr18CjvPGJ92SPzupUWJhrEKmOe8WZLs 6ZNMjU+QYwbC9/k3cdq/abG3JaY4OiSLpWjOOO75RyuGug3Hpd5+pHsKkDbq7aKW W8ydsiwvcV7ad0+tutOXl50Ty/0gXJO3NzQlx5qR1642soHKEPE= =YiHm -----END PGP SIGNATURE----- --5wqacc3nq757qqz6--