diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 1 | ||||
| -rw-r--r-- | manual/intro.texi | 17 | ||||
| -rw-r--r-- | manual/llio.texi | 34 | ||||
| -rw-r--r-- | manual/macros.texi | 7 | ||||
| -rw-r--r-- | manual/socket.texi | 52 | ||||
| -rw-r--r-- | manual/startup.texi | 22 |
6 files changed, 96 insertions, 37 deletions
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}. |