[v10] manual: add syscalls
Checks
Context |
Check |
Description |
redhat-pt-bot/TryBot-apply_patch |
success
|
Patch applied to master at the time it was sent
|
redhat-pt-bot/TryBot-32bit |
success
|
Build for i686
|
linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 |
success
|
Build passed
|
linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 |
success
|
Test passed
|
linaro-tcwg-bot/tcwg_glibc_build--master-arm |
success
|
Build passed
|
linaro-tcwg-bot/tcwg_glibc_check--master-arm |
success
|
Test passed
|
Commit Message
"Andreas K. Huettel" <dilfridge@gentoo.org> writes:
> I dont see a v10 - do we need one?
Here's a v10, it only changes the man pages version...
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, so
can refer to their documentation; and define a standard way of doing
so in the future. A more detailed explaination of how system calls
are wrapped is added along with reference to the Linux Man-Pages
project.
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>
Comments
Hi DJ,
On Mon, Jul 08, 2024 at 05:52:15PM GMT, DJ Delorie wrote:
> "Andreas K. Huettel" <dilfridge@gentoo.org> writes:
> > I dont see a v10 - do we need one?
>
> Here's a v10, it only changes the man pages version...
>
> 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, so
> can refer to their documentation; and define a standard way of doing
> so in the future. A more detailed explaination of how system calls
> are wrapped is added along with reference to the Linux Man-Pages
> project.
>
> 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/manual/intro.texi b/manual/intro.texi
> index ff43c5a7fb..879c1b38d9 100644
> --- a/manual/intro.texi
> +++ b/manual/intro.texi
[...]
> @@ -941,7 +942,7 @@ inter-process communication and shared memory, the @code{hsearch} and
> @code{drand48} families of functions, @code{fmtmsg} and several of the
> mathematical functions.
>
> -@node XPG, , SVID, Standards and Portability
> +@node XPG, Linux Kernel, SVID, Standards and Portability
> @subsection XPG (The X/Open Portability Guide)
>
> The X/Open Portability Guide, published by the X/Open Company, Ltd., is
> @@ -960,6 +961,20 @@ fulfilling the XPG standard with the Unix extensions is a
> precondition for getting the Unix brand chances are good that the
> functionality is available on commercial systems.
>
> +@node Linux Kernel, , XPG, Standards and Portability
Is this empty comma OK, or is it a typo?
> +@subsection Linux (The Linux Kernel)
Have a lovely night!
Alex
Alejandro Colomar <alx@kernel.org> writes:
>> +@node Linux Kernel, , XPG, Standards and Portability
>
> Is this empty comma OK, or is it a typo?
It's an empty "next" node.
Pushed this since it already had a R-B and as far as I can see all issues
had been addressed.
Thanks!
Am Montag, 8. Juli 2024, 23:52:15 CEST schrieb DJ Delorie:
> "Andreas K. Huettel" <dilfridge@gentoo.org> writes:
> > I dont see a v10 - do we need one?
>
> Here's a v10, it only changes the man pages version...
>
> 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, so
> can refer to their documentation; and define a standard way of doing
> so in the future. A more detailed explaination of how system calls
> are wrapped is added along with reference to the Linux Man-Pages
> project.
>
> 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 1bae55b45b..1d543548cd 100755
> --- a/configure
> +++ b/configure
> @@ -699,6 +699,7 @@ force_install
> bindnow
> hardcoded_path_in_tests
> enable_timezone_tools
> +man_pages_version
> rtld_early_cflags
> extra_nonshared_cflags
> sysheaders
> @@ -782,6 +783,7 @@ with_headers
> with_nonshared_cflags
> with_rtld_early_cflags
> with_timeoutfactor
> +with_man_pages
> enable_sanity_checks
> enable_shared
> enable_profile
> @@ -1508,6 +1510,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:
> @@ -3868,8 +3872,9 @@ config_vars=
> if test ${enable_static_c___tests+y}
> then :
> enableval=$enable_static_c___tests; static_cxx_tests=$enableval
> -else $as_nop
> - static_cxx_tests=yes
> +else case e in #(
> + e) static_cxx_tests=yes ;;
> +esac
> fi
>
> config_vars="$config_vars
> @@ -3879,8 +3884,9 @@ static-cxx-tests = $static_cxx_tests"
> if test ${enable_static_c___link_check+y}
> then :
> enableval=$enable_static_c___link_check; static_cxx_link_check=$enableval
> -else $as_nop
> - static_cxx_link_check=yes
> +else case e in #(
> + e) static_cxx_link_check=yes ;;
> +esac
> fi
>
>
> @@ -4469,6 +4475,17 @@ fi
> printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
>
>
> +man_pages_version=6.9.1
> +
> +
> +# 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 e48957f318..9cbc0bf68f 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -183,6 +183,15 @@ AC_ARG_WITH([timeoutfactor],
> [timeoutfactor=1])
> AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
>
> +man_pages_version=6.9.1
> +
> +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/intro.texi b/manual/intro.texi
> index ff43c5a7fb..879c1b38d9 100644
> --- a/manual/intro.texi
> +++ b/manual/intro.texi
> @@ -85,6 +85,7 @@ standards each function or symbol comes from.
> * Berkeley Unix:: BSD and SunOS.
> * SVID:: The System V Interface Description.
> * XPG:: The X/Open Portability Guide.
> +* Linux Kernel:: The Linux kernel.
> @end menu
>
> @node ISO C, POSIX, , Standards and Portability
> @@ -941,7 +942,7 @@ inter-process communication and shared memory, the @code{hsearch} and
> @code{drand48} families of functions, @code{fmtmsg} and several of the
> mathematical functions.
>
> -@node XPG, , SVID, Standards and Portability
> +@node XPG, Linux Kernel, SVID, Standards and Portability
> @subsection XPG (The X/Open Portability Guide)
>
> The X/Open Portability Guide, published by the X/Open Company, Ltd., is
> @@ -960,6 +961,20 @@ fulfilling the XPG standard with the Unix extensions is a
> precondition for getting the Unix brand chances are good that the
> functionality is available on commercial systems.
>
> +@node Linux Kernel, , XPG, Standards and Portability
> +@subsection Linux (The Linux 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.
> +
> +Additional details on the Linux system call interface can be found in
> +@xref{System Calls}.
>
> @node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction
> @section Using the Library
> diff --git a/manual/llio.texi b/manual/llio.texi
> index 78c7c79913..6f0a48609b 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
>
>
> @@ -2324,6 +2325,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
> @@ -3407,7 +3410,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
> @@ -4743,5 +4748,28 @@ 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 pollfd}
> +@standards{POSIX.1,poll.h}
> +@end deftp
> +
> +@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})
> +
> +@manpagefunctionstub{poll,2}
> +@end deftypefun
> +
> +@deftypefun int epoll_create(int @var{size})
> +
> +@manpagefunctionstub{epoll_create,2}
> +@end deftypefun
> +
> +@deftypefun int epoll_wait(int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout})
> +
> +@manpagefunctionstub{epoll_wait,2}
> +@end deftypefun
> diff --git a/manual/macros.texi b/manual/macros.texi
> index 4a2e22f473..579da3fb81 100644
> --- a/manual/macros.texi
> +++ b/manual/macros.texi
> @@ -282,4 +282,11 @@ cwd\comments\
> @macro standardsx {element, standard, header}
> @end macro
>
> +@macro manpagefunctionstub {func,sec}
> +This documentation is a stub. For additional information on this
> +function, consult the manual page
> +@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}.
> +@xref{Linux Kernel}.
> +@end macro
> +
> @end ifclear
> diff --git a/manual/socket.texi b/manual/socket.texi
> index f0e35d9e13..8708cbb07c 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,20 @@ 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})
> +
> +@manpagefunctionstub{sendmsg,2}
> +@end deftypefun
> +
> +@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
> +
> +@manpagefunctionstub{recvmsg,2}
> +@end deftypefun
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 224dd98c1e..747beed4d9 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -689,7 +689,25 @@ 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.
> +
> +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.
> @@ -711,6 +729,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}.
>
>
>
@@ -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@
@@ -699,6 +699,7 @@ force_install
bindnow
hardcoded_path_in_tests
enable_timezone_tools
+man_pages_version
rtld_early_cflags
extra_nonshared_cflags
sysheaders
@@ -782,6 +783,7 @@ with_headers
with_nonshared_cflags
with_rtld_early_cflags
with_timeoutfactor
+with_man_pages
enable_sanity_checks
enable_shared
enable_profile
@@ -1508,6 +1510,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:
@@ -3868,8 +3872,9 @@ config_vars=
if test ${enable_static_c___tests+y}
then :
enableval=$enable_static_c___tests; static_cxx_tests=$enableval
-else $as_nop
- static_cxx_tests=yes
+else case e in #(
+ e) static_cxx_tests=yes ;;
+esac
fi
config_vars="$config_vars
@@ -3879,8 +3884,9 @@ static-cxx-tests = $static_cxx_tests"
if test ${enable_static_c___link_check+y}
then :
enableval=$enable_static_c___link_check; static_cxx_link_check=$enableval
-else $as_nop
- static_cxx_link_check=yes
+else case e in #(
+ e) static_cxx_link_check=yes ;;
+esac
fi
@@ -4469,6 +4475,17 @@ fi
printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
+man_pages_version=6.9.1
+
+
+# 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 :
@@ -183,6 +183,15 @@ AC_ARG_WITH([timeoutfactor],
[timeoutfactor=1])
AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
+man_pages_version=6.9.1
+
+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@:>@]),
@@ -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 $@
@@ -85,6 +85,7 @@ standards each function or symbol comes from.
* Berkeley Unix:: BSD and SunOS.
* SVID:: The System V Interface Description.
* XPG:: The X/Open Portability Guide.
+* Linux Kernel:: The Linux kernel.
@end menu
@node ISO C, POSIX, , Standards and Portability
@@ -941,7 +942,7 @@ inter-process communication and shared memory, the @code{hsearch} and
@code{drand48} families of functions, @code{fmtmsg} and several of the
mathematical functions.
-@node XPG, , SVID, Standards and Portability
+@node XPG, Linux Kernel, SVID, Standards and Portability
@subsection XPG (The X/Open Portability Guide)
The X/Open Portability Guide, published by the X/Open Company, Ltd., is
@@ -960,6 +961,20 @@ fulfilling the XPG standard with the Unix extensions is a
precondition for getting the Unix brand chances are good that the
functionality is available on commercial systems.
+@node Linux Kernel, , XPG, Standards and Portability
+@subsection Linux (The Linux 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.
+
+Additional details on the Linux system call interface can be found in
+@xref{System Calls}.
@node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction
@section Using the Library
@@ -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
@@ -2324,6 +2325,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
@@ -3407,7 +3410,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
@@ -4743,5 +4748,28 @@ 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 pollfd}
+@standards{POSIX.1,poll.h}
+@end deftp
+
+@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})
+
+@manpagefunctionstub{poll,2}
+@end deftypefun
+
+@deftypefun int epoll_create(int @var{size})
+
+@manpagefunctionstub{epoll_create,2}
+@end deftypefun
+
+@deftypefun int epoll_wait(int @var{epfd}, struct epoll_event *@var{events}, int @var{maxevents}, int @var{timeout})
+
+@manpagefunctionstub{epoll_wait,2}
+@end deftypefun
@@ -282,4 +282,11 @@ cwd\comments\
@macro standardsx {element, standard, header}
@end macro
+@macro manpagefunctionstub {func,sec}
+This documentation is a stub. For additional information on this
+function, consult the manual page
+@url{https://man7.org/linux/man-pages/man\sec\/\func\.\sec\.html}.
+@xref{Linux Kernel}.
+@end macro
+
@end ifclear
@@ -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,20 @@ 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})
+
+@manpagefunctionstub{sendmsg,2}
+@end deftypefun
+
+@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
+
+@manpagefunctionstub{recvmsg,2}
+@end deftypefun
@@ -689,7 +689,25 @@ 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.
+
+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.
@@ -711,6 +729,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}.