[v8] manual: add syscalls

Message ID xnr0cqp5pv.fsf@greed.delorie.com
State Superseded
Headers
Series [v8] manual: add syscalls |

Checks

Context Check Description
redhat-pt-bot/TryBot-apply_patch fail Patch failed to apply to master at the time it was sent
redhat-pt-bot/TryBot-32bit fail Patch series failed to apply

Commit Message

DJ Delorie June 21, 2024, 5:26 p.m. UTC
  "Carlos O'Donell" <carlos@redhat.com> writes:
> 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.

[v8: moved man pages reference to intro, to be reworded when pthreads
docs are added]

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>
  

Comments

Florian Weimer July 1, 2024, 3:30 p.m. UTC | #1
* DJ Delorie:

> [v8: moved man pages reference to intro, to be reworded when pthreads
> docs are added]
>
> 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>

Are the commit message and commit subject still up to date?


> diff --git a/manual/intro.texi b/manual/intro.texi
> index ff43c5a7fb..990ba2202d 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

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

Missing double space before “Where”.

> 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

Okay.

> diff --git a/manual/socket.texi b/manual/socket.texi
> index f0e35d9e13..66f893d219 100644
> --- a/manual/socket.texi
> +++ b/manual/socket.texi

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

“is cancelled.” I think.

> +@c @xref{pthread_cleanup_push}, for a method how to do this.
> +@end deftypefun

I think this should use @manpagefunctionstub as well.


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

Likewise.

Thanks,
Florian
  
Alejandro Colomar July 1, 2024, 8:03 p.m. UTC | #2
On Mon, Jul 01, 2024 at 05:30:06PM GMT, Florian Weimer wrote:
> * DJ Delorie:
> 
> > [v8: moved man pages reference to intro, to be reworded when pthreads
> > docs are added]
> >
> > 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>
> 
> Are the commit message and commit subject still up to date?

Regarding my review, yeah; I've been having a look at the changes after
my review, and they seem all reasonable.

> > diff --git a/manual/intro.texi b/manual/intro.texi
> > index ff43c5a7fb..990ba2202d 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
> 
> > +@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.
> 
> Missing double space before “Where”.
> 
> > 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
> 
> Okay.
> 
> > diff --git a/manual/socket.texi b/manual/socket.texi
> > index f0e35d9e13..66f893d219 100644
> > --- a/manual/socket.texi
> > +++ b/manual/socket.texi
> 
> > +@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.
> 
> “is cancelled.” I think.
> 
> > +@c @xref{pthread_cleanup_push}, for a method how to do this.
> > +@end deftypefun
> 
> I think this should use @manpagefunctionstub as well.
> 
> 
> > +@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
> 
> Likewise.
> 
> Thanks,
> Florian
>
  
DJ Delorie July 1, 2024, 9:20 p.m. UTC | #3
Florian Weimer <fweimer@redhat.com> writes:
> Are the commit message and commit subject still up to date?

I tweaked the text a bit:

  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.

> Missing double space before “Where”.

Fixed.

> “is cancelled.” I think.

Yup, fixed.

>> +@c @xref{pthread_cleanup_push}, for a method how to do this.
>> +@end deftypefun
>
> I think this should use @manpagefunctionstub as well.

connect()?  Or pthread_cleanup_push?  connect is documented (although
perhaps not completely, but enough) and if we put a man page reference
for pthread_cleanup_push here, we'd have to put it everywhere we mention
cancellation points.  Plus, that line is commented out.

Note that the manual does not visibly mention pthread_cleanup_push at
all, and we don't seem to document anything about how cancellation
happens.
  
Florian Weimer July 3, 2024, 12:53 p.m. UTC | #4
* DJ Delorie:

>>> +@c @xref{pthread_cleanup_push}, for a method how to do this.
>>> +@end deftypefun
>>
>> I think this should use @manpagefunctionstub as well.
>
> connect()?  Or pthread_cleanup_push?  connect is documented (although
> perhaps not completely, but enough) and if we put a man page reference
> for pthread_cleanup_push here, we'd have to put it everywhere we mention
> cancellation points.  Plus, that line is commented out.

I don't see where connect is coming from suddenly.  It's the stub
documentation for recvmsg and sendmsg.

Thanks,
Florian
  

Patch

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/intro.texi b/manual/intro.texi
index ff43c5a7fb..990ba2202d 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 fe1807a849..caaf001857 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,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..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..310b822458 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -690,7 +690,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.
@@ -712,6 +730,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}.