| Message ID | xn5xtfmu0g.fsf@greed.delorie.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v10] manual: add syscalls | expand |
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
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}. > > >
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}.