You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
341 lines
13 KiB
341 lines
13 KiB
From 6c0be74305745c8f78bcfb69442c8c379459d99b Mon Sep 17 00:00:00 2001 |
|
From: DJ Delorie <dj@redhat.com> |
|
Date: Mon, 8 Jul 2024 17:52:15 -0400 |
|
Subject: manual: add syscalls |
|
|
|
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 |
|
@@ -101,6 +101,7 @@ build-hardcoded-path-in-tests= @hardcode |
|
build-pt-chown = @build_pt_chown@ |
|
have-tunables = @have_tunables@ |
|
pthread-in-libc = @pthread_in_libc@ |
|
+man-pages-version = @man_pages_version@ |
|
|
|
# Build tools. |
|
CC = @CC@ |
|
diff --git a/configure b/configure |
|
index 55e8b7563b..36096881b7 100644 |
|
--- a/configure 2024-07-17 15:45:55.033649362 -0400 |
|
+++ b/configure 2024-07-17 15:47:44.281886629 -0400 |
|
@@ -681,6 +681,7 @@ force_install |
|
bindnow |
|
hardcoded_path_in_tests |
|
enable_timezone_tools |
|
+man_pages_version |
|
rtld_early_cflags |
|
extra_nonshared_cflags |
|
use_default_link |
|
@@ -763,6 +764,7 @@ with_headers |
|
with_default_link |
|
with_nonshared_cflags |
|
with_rtld_early_cflags |
|
+with_man_pages |
|
enable_sanity_checks |
|
enable_shared |
|
enable_profile |
|
@@ -1483,6 +1485,8 @@ Optional Packages: |
|
build nonshared libraries with additional CFLAGS |
|
--with-rtld-early-cflags=CFLAGS |
|
build early initialization with additional CFLAGS |
|
+ --with-man-pages=VERSION |
|
+ tie manual to a specific man-pages version |
|
--with-cpu=CPU select code for CPU variant |
|
|
|
Some influential environment variables: |
|
@@ -3396,6 +3400,15 @@ fi |
|
|
|
|
|
|
|
+man_pages_version=6.9.1 |
|
+ |
|
+ |
|
+# Check whether --with-man-pages was given. |
|
+if test "${with_man_pages+set}" = set; then : |
|
+ withval=$with_man_pages; man_pages_version=$withval |
|
+fi |
|
+ |
|
+ |
|
|
|
# Check whether --enable-sanity-checks was given. |
|
if test "${enable_sanity_checks+set}" = set; then : |
|
diff --git a/configure.ac b/configure.ac |
|
index e48957f318..9cbc0bf68f 100644 |
|
--- a/configure.ac 2024-07-17 15:45:52.181538742 -0400 |
|
+++ b/configure.ac 2024-07-17 15:46:29.885001095 -0400 |
|
@@ -169,6 +169,15 @@ AC_ARG_WITH([rtld-early-cflags], |
|
[rtld_early_cflags=]) |
|
AC_SUBST(rtld_early_cflags) |
|
|
|
+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}. |
|
|
|
|