[patch v7] manual: add syscalls

[patch v7] manual: add syscalls

[DJ Delorie]

[v7: fix typos, add note to fcntl() to see syscalls section for
man-pages reference]

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 <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..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..0d1a32e3e1 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
@@ -3297,7 +3300,9 @@ require additional arguments to be supplied.  These additional arguments
 and the return value and error conditions are given in the detailed
 descriptions of the individual commands.
 
-Briefly, here is a list of what the various commands are.
+Briefly, here is a list of what the various commands are.  For an
+exhaustive list of kernel-specific options, please see @xref{System
+Calls}.
 
 @vtable @code
 @item F_DUPFD
@@ -4633,5 +4638,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..66f893d219 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 Socket 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..600f6abc3c 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
+superseded 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}.
 

Re: [patch v7] manual: add syscalls

[Florian Weimer]

* DJ Delorie:

> diff --git a/manual/llio.texi b/manual/llio.texi
> index fe1807a849..0d1a32e3e1 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
> +@node Other Low-Level I/O APIs
> +@section Other low-level-I/O-related functions

No need to create a new section/node, we already have “Waiting for I/O”.

> +@deftp {Data Type} {struct epoll_event}
> +@standards{Linux, sys/epoll.h}
> +@end deftp

I think you should mention struct pollfd (from <poll.h>) before the poll
function.

> +@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

I think we could have a macro, then we could write this:

@manpagefunctionstub{poll, 2}

And it would expand to something like this:

This documentation is a stub.  For additional information on this
function, consult the manual page
@url{https://man7.org/linux/man-pages/man2/poll.2.html}.
@xref{Linux Manual Pages}.

> +@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.

Could you make this system-call-agnostic and put this into a new node
under Standards and Portability?

Thanks,
Florian

Re: [patch v7] manual: add syscalls

[DJ Delorie]

Florian Weimer <fweimer@redhat.com> writes:
>> +* Other Low-Level I/O APIs::            Other low-level-I/O-related functions
>> +@node Other Low-Level I/O APIs
>> +@section Other low-level-I/O-related functions
>
> No need to create a new section/node, we already have “Waiting for I/O”.

Carlos's idea was to create a template for how to add kernel API
functions that might be difficult to fit into the documentation.  This
is part of that; there are two examples of "add a section at the end of
the chapter for listing, but not documenting, related functions; provide
a template for referring those functions to the section where we talk
about the man-pages project."

Re: [patch v7] manual: add syscalls

[DJ Delorie]

Florian Weimer <fweimer@redhat.com> writes:
>> +@deftp {Data Type} {struct epoll_event}
>> +@standards{Linux, sys/epoll.h}
>> +@end deftp
>
> I think you should mention struct pollfd (from <poll.h>) before the poll
> function.

Done.

> I think we could have a macro, then we could write this:
>
> @manpagefunctionstub{poll, 2}
>
> And it would expand to something like this:
>
> This documentation is a stub.  For additional information on this
> function, consult the manual page
> @url{https://man7.org/linux/man-pages/man2/poll.2.html}.
> @xref{Linux Manual Pages}.

Done, although I xref'd the existing syscall chapter.

>> +@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.
>
> Could you make this system-call-agnostic and put this into a new node
> under Standards and Portability?

That would refer glibc's own functions to the man pages, which I think
is not what we want.  We should document our own APIs.  The referal for
syscalls specifically is so that we don't have to document the kernel's
APIs.

Re: [patch v7] manual: add syscalls

[Florian Weimer]

* DJ Delorie:

>> Could you make this system-call-agnostic and put this into a new node
>> under Standards and Portability?
>
> That would refer glibc's own functions to the man pages, which I think
> is not what we want.  We should document our own APIs.  The referal for
> syscalls specifically is so that we don't have to document the kernel's
> APIs.

Carlos mentioned that we'll need this documentation mechanism for some
of the pthread functions as well.  Those aren't kernel interfaces.

Thanks,
Florian

Re: [patch v7] manual: add syscalls

[Carlos O'Donell]

On 6/15/24 9:21 AM, Florian Weimer wrote:
> * DJ Delorie:
> 
>>> Could you make this system-call-agnostic and put this into a new node
>>> under Standards and Portability?
>>
>> That would refer glibc's own functions to the man pages, which I think
>> is not what we want.  We should document our own APIs.  The referal for
>> syscalls specifically is so that we don't have to document the kernel's
>> APIs.
> 
> Carlos mentioned that we'll need this documentation mechanism for some
> of the pthread functions as well.  Those aren't kernel interfaces.

Correct, and I recognize that this means we are *changing the goal posts*, but that's
where we are right now.

We can either accept this patch as it is, or move it somewhere more "generic" since
when we get to documenting POSIX Threads APIs we're going to need to reference the
same Linux Man Pages note with an xref.

DJ, My deepest apologies for the evolving requirements.

-- 
Cheers,
Carlos.