From patchwork Mon Jun 10 23:00:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 1946028 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=BIgM+De5; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=8.43.85.97; helo=server2.sourceware.org; envelope-from=libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4VynMp1JBGz20Py for ; Tue, 11 Jun 2024 09:00:37 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 8EF3E385B50B for ; Mon, 10 Jun 2024 23:00:34 +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.129.124]) by sourceware.org (Postfix) with ESMTPS id 8F5153858D29 for ; Mon, 10 Jun 2024 23:00:13 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 8F5153858D29 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 8F5153858D29 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718060416; cv=none; b=v9P5RMVPNcGcME6M8G1dU+ZaKZOCblynzKCKN/n3FsbYrfGlR89tJ3ju9C4Pd80DSwZ0gBv5uFoDQUdYMMQgM+hHWdgWZA+C+qIvkujkhO2ArGlC+u3NffS6iHitf0HVlugcykxp4hc/aQ9WWczPG7Ney4VFSyWV62R2pKAUrWg= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718060416; c=relaxed/simple; bh=p06tVkzjx27voO/PYtCTkpBq4MVzxK+EYnQMBxqJ5Ug=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=GHUqk3AMPJoCyqytJVg5AyyWJHfXxTCbMH7GryfTW7aqc0tHu1kqdbhJjO7XlgAMi86oUa6PU50L4228HSv4654WtkcnS3LG1b1i1oHx6o1Qg1eLISqC+BL/rpoE1Au3mnS9vpPn3oDaTynk9Qc6EgGbW/5muQSKB+lOqjGLMqM= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1718060413; 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; bh=dgGtFUJc58K55e+dZxTrdGmr5+ZyJMylCfWBXvPsCQY=; b=BIgM+De5/rEapFUYmZxHgKH9OgjIrOe5ev21qaK9sa44lHIMXFk8KR/nntFe9LBlxZoKys gSzaruv8iGB98s98YFJS4EWGbmRPHCN2mDZNDmU1E5Wls4jLEQym6YwelFTbQc9Xhm2n72 tptxI1zu6DawSXf9xVWl5oTXDoWv49Q= Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-681-o5QfcKYtNSm0CDUxjpX4tg-1; Mon, 10 Jun 2024 19:00:10 -0400 X-MC-Unique: o5QfcKYtNSm0CDUxjpX4tg-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (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 mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 42DDD1956096; Mon, 10 Jun 2024 23:00:09 +0000 (UTC) Received: from greed.delorie.com (unknown [10.22.8.94]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 93B8B1956048; Mon, 10 Jun 2024 23:00:08 +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 45AN06Nw1371693; Mon, 10 Jun 2024 19:00:06 -0400 From: DJ Delorie To: libc-alpha@sourceware.org Cc: Florian Weimer , carlos@redhat.com, alx@kernel.org Subject: [patch v6] manual: add syscalls Date: Mon, 10 Jun 2024 19:00:06 -0400 Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-9.3 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, RCVD_IN_SBL_CSS, SPF_HELO_NONE, SPF_NONE, 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 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+incoming=patchwork.ozlabs.org@sourceware.org [v6: removed generated tables, added two "other APIs" sections with xrefs] The purpose of this patch is to add some system calls that (1) aren't otherwise documented, and (2) are merely redirected to the kernel; and define a standard way of doing so in the future. A more detailed explaination of how system calls are wrapped is added with reference to the Linux Man-Pages project for further details. 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..a6c05db540 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -117,6 +117,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 $@ diff --git a/manual/llio.texi b/manual/llio.texi index fe1807a849..c4def45a2a 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -65,6 +65,7 @@ directly.) * Interrupt Input:: Getting an asynchronous signal when input arrives. * IOCTLs:: Generic I/O Control operations. +* Other Low-Level I/O APIs:: Other low-level-I/O-related functions. @end menu @@ -2214,6 +2215,8 @@ file descriptor, or until the timeout period expires. There is another example showing the use of @code{select} to multiplex input from multiple sockets in @ref{Server Example}. +For an alternate interface to this functionality, see @code{poll} +(@pxref{Other Low-Level I/O APIs}). @node Synchronizing I/O @section Synchronizing I/O operations @@ -4633,5 +4636,24 @@ Most IOCTLs are OS-specific and/or only used in special system utilities, and are thus beyond the scope of this document. For an example of the use of an IOCTL, see @ref{Out-of-Band Data}. -@c FIXME this is undocumented: -@c dup3 +@node{Other Low-Level I/O APIs} +@section{Other low-level-I/O-related functions} + +@deftp {Data Type} {struct epoll_event} +@standards{Linux, sys/epoll.h} +@end deftp + +@deftypefun int poll (struct pollfd *@var{fds}, nfds_t @var{nfds}, int @var{timeout}) + +@xref{System Calls} for information on this and other system calls. +@end deftypefun + +@deftypefun int epoll_create(int @var{size}) + +@xref{System Calls} for information on this and other system calls. +@end deftypefun + +@deftypefun int epoll_wait(int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout}) + +@xref{System Calls} for information on this and other system calls. +@end deftypefun diff --git a/manual/socket.texi b/manual/socket.texi index f0e35d9e13..33a9722bbb 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -41,6 +41,7 @@ aren't documented either so far. is to make it work with Inetd. * Socket Options:: Miscellaneous low-level socket options. * Networks Database:: Accessing the database of network names. +* Other Socket APIs:: Other socket-related functions. @end menu @node Socket Concepts @@ -3134,38 +3135,8 @@ You can use plain @code{recv} (@pxref{Receiving Data}) instead of treat all possible senders alike). Even @code{read} can be used if you don't want to specify @var{flags} (@pxref{I/O Primitives}). -@ignore -@c sendmsg and recvmsg are like readv and writev in that they -@c use a series of buffers. It's not clear this is worth -@c supporting or that we support them. -@c !!! they can do more; it is hairy - -@deftp {Data Type} {struct msghdr} -@standards{BSD, sys/socket.h} -@end deftp - -@deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) -@standards{BSD, sys/socket.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, files descriptors, semaphores or -whatever) are freed even if the thread is cancel. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) -@standards{BSD, sys/socket.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, files descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun -@end ignore +If you need more flexibility and/or control over sending and receiving +packets, see @code{sendmsg} and @code{recvmsg} (@pxref{Other Related APIs}). @node Datagram Example @subsection Datagram Socket Example @@ -3664,3 +3635,36 @@ returns a null pointer if there are no more entries. @c libc_lock_unlock @aculock This function closes the networks database. @end deftypefun + +@node Other Socket APIs +@section Other Socket APIs + +@deftp {Data Type} {struct msghdr} +@standards{BSD, sys/socket.h} +@end deftp + +@deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) +@standards{BSD, sys/socket.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +@xref{System Calls} for information on this and other system calls. + +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is cancel. +@c @xref{pthread_cleanup_push}, for a method how to do this. +@end deftypefun + +@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) +@standards{BSD, sys/socket.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +@xref{System Calls} for information on this and other system calls. + +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. +@c @xref{pthread_cleanup_push}, for a method how to do this. +@end deftypefun diff --git a/manual/startup.texi b/manual/startup.texi index 96a7a472bb..6eafb20549 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -690,7 +690,34 @@ 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. + +In some cases, if @theglibc{} detects 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. In general, though, such processing is only to make the +system call better match the C ABI, rather than change its +functionality. However, there are times when you want to make a system call explicitly, and for that, @theglibc{} provides the @code{syscall} function. @@ -712,6 +739,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}.