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@
bindnow
hardcoded_path_in_tests
enable_timezone_tools
+man_pages_version
rtld_early_cflags
extra_nonshared_cflags
sysheaders
with_nonshared_cflags
with_rtld_early_cflags
with_timeoutfactor
+with_man_pages
enable_sanity_checks
enable_shared
enable_profile
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:
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
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
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 :
[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@:>@]),
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 $@
* 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
@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
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
* 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
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
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
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
@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
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
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
@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
@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.
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}.
projects / thirdparty / glibc.git / commitdiff
