From patchwork Wed May 22 19:41:04 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 90698 X-Patchwork-Delegate: fweimer@redhat.com Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 467E838654B0 for ; Wed, 22 May 2024 19:41:38 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id C197C3858C62 for ; Wed, 22 May 2024 19:41:08 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org C197C3858C62 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org C197C3858C62 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1716406871; cv=none; b=UI/8/I/9vUbJK8zqfhP+Y7386Aeb9xA7rC6aPw0VXFULubpyYkmxobvx/kCOe1I5zSaSb/La06M4K1Ng7PSE7mIJ2T8gjfRJjoZWcGRFANOJwcKi8J26l8BC4sf579Hpks7PC6UYeGcer+KsKoBZSoXLYBN6C5T26IAZKpboyyE= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1716406871; c=relaxed/simple; bh=dVr6uvkm0j4Awl+NRNglPhUdElHT9Tijn22JDZwAkLE=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=wJ99SLmaXudOYDAIgIYTAmjXu+InwDYowpwfdTRPtNjcm20Z9PdtPyisPg7Hc8mS444ga7co92bq1hVVLiixDPWsyKmfk6Lli6CVUkyEuCO3I/bp/EWD1Fr5ZmhXRMbus1/DMIwW9wEQIe3Z5i1hdHNP9TJxalnLAplMamY6k8E= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1716406868; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to; bh=CRj42BPg/qDP70zfiOS8OJi1bBfAFP1wWy37ODaQ8SM=; b=H8XMQYl1Y4iHbG/3TVKlzT5/s8sHmfFTuqcedl/uku4JS7qartf5VhAVNx1yGg0PSC5OzX l4tisljVCMQfw0lzeyBv2SVatZYuUM3Qelfp/05P+KN2Qzk7LLwva3g2zzOsLvIWxqAgYl VFi+xq6TO9xCeUcxx4IanZTI8n65igU= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-392-MpC-eYHjNmWom49pgAtZbQ-1; Wed, 22 May 2024 15:41:06 -0400 X-MC-Unique: MpC-eYHjNmWom49pgAtZbQ-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id DC8FE185A78E; Wed, 22 May 2024 19:41:05 +0000 (UTC) Received: from greed.delorie.com (unknown [10.22.8.114]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B364B40C6CB4; Wed, 22 May 2024 19:41:05 +0000 (UTC) Received: from greed.delorie.com.redhat.com (localhost [127.0.0.1]) by greed.delorie.com (8.16.1/8.16.1) with ESMTP id 44MJf4Or3323656; Wed, 22 May 2024 15:41:04 -0400 From: DJ Delorie To: "Carlos O'Donell" Cc: alx@kernel.org, libc-alpha@sourceware.org Subject: [patch v4] manual: add syscall list In-Reply-To: (carlos@redhat.com) Date: Wed, 22 May 2024 15:41:04 -0400 Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-10.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org [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 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.