[patch v6] manual: add syscalls

[Alejandro Colomar]

Hi DJ,

On Mon, Jun 10, 2024 at 07:00:06PM GMT, DJ Delorie wrote:
> 
> [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
>

[...]

> 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

I think this is not documented in the commit message, is it?

[...]

> 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

s/superceeded/superseded/

Have a lovely night!
Alex

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

-- 
<https://www.alejandro-colomar.es/>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20240611/ab648b2f/attachment-0001.sig>