Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 0 insertions, 765 deletions

diff --git a/man2/select.2 b/man2/select.2
deleted file mode 100644
index e544918..0000000
--- a/man2/select.2
+++ /dev/null
@@ -1,765 +0,0 @@
-.\" This manpage is copyright (C) 1992 Drew Eckhardt,
-.\"     copyright (C) 1995 Michael Shields,
-.\"     copyright (C) 2001 Paul Sheer,
-.\"     copyright (C) 2006, 2019 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
-.\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com>
-.\" Sun Feb 11 14:07:00 MET 1996  Martin Schulze  <joey@linux.de>
-.\"	* layout slightly modified
-.\"
-.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
-.\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb
-.\" Modified Thu Feb  9 22:32:09 CET 2001 by bert hubert <ahu@ds9a.nl>, aeb
-.\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard <ben@zork.net>
-.\" 2005-03-11, mtk, modified pselect() text (it is now a system
-.\"     call in Linux 2.6.16.
-.\"
-.TH select 2 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \-
-synchronous I/O multiplexing
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <sys/select.h>
-.P
-.BR typedef " /* ... */ " fd_set;
-.P
-.BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds ,
-.BI "           fd_set *_Nullable restrict " writefds ,
-.BI "           fd_set *_Nullable restrict " exceptfds ,
-.BI "           struct timeval *_Nullable restrict " timeout );
-.P
-.BI "void FD_CLR(int " fd ", fd_set *" set );
-.BI "int  FD_ISSET(int " fd ", fd_set *" set );
-.BI "void FD_SET(int " fd ", fd_set *" set );
-.BI "void FD_ZERO(fd_set *" set );
-.P
-.BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds ,
-.BI "           fd_set *_Nullable restrict " writefds ,
-.BI "           fd_set *_Nullable restrict " exceptfds ,
-.BI "           const struct timespec *_Nullable restrict " timeout ,
-.BI "           const sigset_t *_Nullable restrict " sigmask );
-.fi
-.P
-.RS -4
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.RE
-.P
-.BR pselect ():
-.nf
-    _POSIX_C_SOURCE >= 200112L
-.fi
-.SH DESCRIPTION
-.BR "WARNING" :
-.BR select ()
-can monitor only file descriptors numbers that are less than
-.B FD_SETSIZE
-(1024)\[em]an unreasonably low limit for many modern applications\[em]and
-this limitation will not change.
-All modern applications should instead use
-.BR poll (2)
-or
-.BR epoll (7),
-which do not suffer this limitation.
-.P
-.BR select ()
-allows a program to monitor multiple file descriptors,
-waiting until one or more of the file descriptors become "ready"
-for some class of I/O operation (e.g., input possible).
-A file descriptor is considered ready if it is possible to
-perform a corresponding I/O operation (e.g.,
-.BR read (2),
-or a sufficiently small
-.BR write (2))
-without blocking.
-.\"
-.SS fd_set
-A structure type that can represent a set of file descriptors.
-According to POSIX,
-the maximum number of file descriptors in an
-.I fd_set
-structure is the value of the macro
-.BR FD_SETSIZE .
-.\"
-.SS File descriptor sets
-The principal arguments of
-.BR select ()
-are three "sets" of file descriptors (declared with the type
-.IR fd_set ),
-which allow the caller to wait for three classes of events
-on the specified set of file descriptors.
-Each of the
-.I fd_set
-arguments may be specified as NULL if no file descriptors are
-to be watched for the corresponding class of events.
-.P
-.BR "Note well" :
-Upon return, each of the file descriptor sets is modified in place
-to indicate which file descriptors are currently "ready".
-Thus, if using
-.BR select ()
-within a loop, the sets \fImust be reinitialized\fP before each call.
-.P
-The contents of a file descriptor set can be manipulated
-using the following macros:
-.TP
-.BR FD_ZERO ()
-This macro clears (removes all file descriptors from)
-.IR set .
-It should be employed as the first step in initializing a file descriptor set.
-.TP
-.BR FD_SET ()
-This macro adds the file descriptor
-.I fd
-to
-.IR set .
-Adding a file descriptor that is already present in the set is a no-op,
-and does not produce an error.
-.TP
-.BR FD_CLR ()
-This macro removes the file descriptor
-.I fd
-from
-.IR set .
-Removing a file descriptor that is not present in the set is a no-op,
-and does not produce an error.
-.TP
-.BR FD_ISSET ()
-.BR select ()
-modifies the contents of the sets according to the rules
-described below.
-After calling
-.BR select (),
-the
-.BR FD_ISSET ()
-macro
-can be used to test if a file descriptor is still present in a set.
-.BR FD_ISSET ()
-returns nonzero if the file descriptor
-.I fd
-is present in
-.IR set ,
-and zero if it is not.
-.\"
-.SS Arguments
-The arguments of
-.BR select ()
-are as follows:
-.TP
-.I readfds
-The file descriptors in this set are watched to see if they are
-ready for reading.
-A file descriptor is ready for reading if a read operation will not
-block; in particular, a file descriptor is also ready on end-of-file.
-.IP
-After
-.BR select ()
-has returned, \fIreadfds\fP will be
-cleared of all file descriptors except for those that are ready for reading.
-.TP
-.I writefds
-The file descriptors in this set are watched to see if they are
-ready for writing.
-A file descriptor is ready for writing if a write operation will not block.
-However, even if a file descriptor indicates as writable,
-a large write may still block.
-.IP
-After
-.BR select ()
-has returned, \fIwritefds\fP will be
-cleared of all file descriptors except for those that are ready for writing.
-.TP
-.I exceptfds
-The file descriptors in this set are watched for "exceptional conditions".
-For examples of some exceptional conditions, see the discussion of
-.B POLLPRI
-in
-.BR poll (2).
-.IP
-After
-.BR select ()
-has returned,
-\fIexceptfds\fP will be cleared of all file descriptors except for those
-for which an exceptional condition has occurred.
-.TP
-.I nfds
-This argument should be set to the highest-numbered file descriptor in any
-of the three sets, plus 1.
-The indicated file descriptors in each set are checked, up to this limit
-(but see BUGS).
-.TP
-.I timeout
-The
-.I timeout
-argument is a
-.I timeval
-structure (shown below) that specifies the interval that
-.BR select ()
-should block waiting for a file descriptor to become ready.
-The call will block until either:
-.RS
-.IP \[bu] 3
-a file descriptor becomes ready;
-.IP \[bu]
-the call is interrupted by a signal handler; or
-.IP \[bu]
-the timeout expires.
-.RE
-.IP
-Note that the
-.I timeout
-interval will be rounded up to the system clock granularity,
-and kernel scheduling delays mean that the blocking interval
-may overrun by a small amount.
-.IP
-If both fields of the
-.I timeval
-structure are zero, then
-.BR select ()
-returns immediately.
-(This is useful for polling.)
-.IP
-If
-.I timeout
-is specified as NULL,
-.BR select ()
-blocks indefinitely waiting for a file descriptor to become ready.
-.\"
-.SS pselect()
-The
-.BR pselect ()
-system call allows an application to safely wait until either
-a file descriptor becomes ready or until a signal is caught.
-.P
-The operation of
-.BR select ()
-and
-.BR pselect ()
-is identical, other than these three differences:
-.IP \[bu] 3
-.BR select ()
-uses a timeout that is a
-.I struct timeval
-(with seconds and microseconds), while
-.BR pselect ()
-uses a
-.I struct timespec
-(with seconds and nanoseconds).
-.IP \[bu]
-.BR select ()
-may update the
-.I timeout
-argument to indicate how much time was left.
-.BR pselect ()
-does not change this argument.
-.IP \[bu]
-.BR select ()
-has no
-.I sigmask
-argument, and behaves as
-.BR pselect ()
-called with NULL
-.IR sigmask .
-.P
-.I sigmask
-is a pointer to a signal mask (see
-.BR sigprocmask (2));
-if it is not NULL, then
-.BR pselect ()
-first replaces the current signal mask by the one pointed to by
-.IR sigmask ,
-then does the "select" function, and then restores the original
-signal mask.
-(If
-.I sigmask
-is NULL,
-the signal mask is not modified during the
-.BR pselect ()
-call.)
-.P
-Other than the difference in the precision of the
-.I timeout
-argument, the following
-.BR pselect ()
-call:
-.P
-.in +4n
-.EX
-ready = pselect(nfds, &readfds, &writefds, &exceptfds,
-                timeout, &sigmask);
-.EE
-.in
-.P
-is equivalent to
-.I atomically
-executing the following calls:
-.P
-.in +4n
-.EX
-sigset_t origmask;
-\&
-pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
-ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
-pthread_sigmask(SIG_SETMASK, &origmask, NULL);
-.EE
-.in
-.P
-The reason that
-.BR pselect ()
-is needed is that if one wants to wait for either a signal
-or for a file descriptor to become ready, then
-an atomic test is needed to prevent race conditions.
-(Suppose the signal handler sets a global flag and
-returns.
-Then a test of this global flag followed by a call of
-.BR select ()
-could hang indefinitely if the signal arrived just after the test
-but just before the call.
-By contrast,
-.BR pselect ()
-allows one to first block signals, handle the signals that have come in,
-then call
-.BR pselect ()
-with the desired
-.IR sigmask ,
-avoiding the race.)
-.SS The timeout
-The
-.I timeout
-argument for
-.BR select ()
-is a structure of the following type:
-.P
-.in +4n
-.EX
-struct timeval {
-    time_t      tv_sec;         /* seconds */
-    suseconds_t tv_usec;        /* microseconds */
-};
-.EE
-.in
-.P
-The corresponding argument for
-.BR pselect ()
-is a
-.BR timespec (3)
-structure.
-.P
-On Linux,
-.BR select ()
-modifies
-.I timeout
-to reflect the amount of time not slept; most other implementations
-do not do this.
-(POSIX.1 permits either behavior.)
-This causes problems both when Linux code which reads
-.I timeout
-is ported to other operating systems, and when code is ported to Linux
-that reuses a \fIstruct timeval\fP for multiple
-.BR select ()s
-in a loop without reinitializing it.
-Consider
-.I timeout
-to be undefined after
-.BR select ()
-returns.
-.\" .P - it is rumored that:
-.\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
-.\" - it is certainly true that:
-.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
-.SH RETURN VALUE
-On success,
-.BR select ()
-and
-.BR pselect ()
-return the number of file descriptors contained in the three returned
-descriptor sets (that is, the total number of bits that are set in
-.IR readfds ,
-.IR writefds ,
-.IR exceptfds ).
-The return value may be zero if the timeout expired before any
-file descriptors became ready.
-.P
-On error, \-1 is returned, and
-.I errno
-is set to indicate the error;
-the file descriptor sets are unmodified,
-and
-.I timeout
-becomes undefined.
-.SH ERRORS
-.TP
-.B EBADF
-An invalid file descriptor was given in one of the sets.
-(Perhaps a file descriptor that was already closed,
-or one on which an error has occurred.)
-However, see BUGS.
-.TP
-.B EINTR
-A signal was caught; see
-.BR signal (7).
-.TP
-.B EINVAL
-.I nfds
-is negative or exceeds the
-.B RLIMIT_NOFILE
-resource limit (see
-.BR getrlimit (2)).
-.TP
-.B EINVAL
-The value contained within
-.I timeout
-is invalid.
-.TP
-.B ENOMEM
-Unable to allocate memory for internal tables.
-.SH VERSIONS
-On some other UNIX systems,
-.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
-.BR select ()
-can fail with the error
-.B EAGAIN
-if the system fails to allocate kernel-internal resources, rather than
-.B ENOMEM
-as Linux does.
-POSIX specifies this error for
-.BR poll (2),
-but not for
-.BR select ().
-Portable programs may wish to check for
-.B EAGAIN
-and loop, just as with
-.BR EINTR .
-.SH STANDARDS
-POSIX.1-2008.
-.SH HISTORY
-.TP
-.BR select ()
-POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD).
-.IP
-Generally portable to/from
-non-BSD systems supporting clones of the BSD socket layer (including
-System\ V variants).
-However, note that the System\ V variant typically
-sets the timeout variable before returning, but the BSD variant does not.
-.TP
-.BR pselect ()
-Linux 2.6.16.
-POSIX.1g, POSIX.1-2001.
-.IP
-Prior to this,
-it was emulated in glibc (but see BUGS).
-.TP
-.B fd_set
-POSIX.1-2001.
-.SH NOTES
-The following header also provides the
-.I fd_set
-type:
-.IR <sys/time.h> .
-.P
-An
-.I fd_set
-is a fixed size buffer.
-Executing
-.BR FD_CLR ()
-or
-.BR FD_SET ()
-with a value of
-.I fd
-that is negative or is equal to or larger than
-.B FD_SETSIZE
-will result
-in undefined behavior.
-Moreover, POSIX requires
-.I fd
-to be a valid file descriptor.
-.P
-The operation of
-.BR select ()
-and
-.BR pselect ()
-is not affected by the
-.B O_NONBLOCK
-flag.
-.\"
-.SS The self-pipe trick
-On systems that lack
-.BR pselect (),
-reliable (and more portable) signal trapping can be achieved
-using the self-pipe trick.
-In this technique,
-a signal handler writes a byte to a pipe whose other end
-is monitored by
-.BR select ()
-in the main program.
-(To avoid possibly blocking when writing to a pipe that may be full
-or reading from a pipe that may be empty,
-nonblocking I/O is used when reading from and writing to the pipe.)
-.\"
-.SS Emulating usleep(3)
-Before the advent of
-.BR usleep (3),
-some code employed a call to
-.BR select ()
-with all three sets empty,
-.I nfds
-zero, and a non-NULL
-.I timeout
-as a fairly portable way to sleep with subsecond precision.
-.\"
-.SS Correspondence between select() and poll() notifications
-Within the Linux kernel source,
-.\" fs/select.c
-we find the following definitions which show the correspondence
-between the readable, writable, and exceptional condition notifications of
-.BR select ()
-and the event notifications provided by
-.BR poll (2)
-and
-.BR epoll (7):
-.P
-.in +4n
-.EX
-#define POLLIN_SET  (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
-                     EPOLLHUP | EPOLLERR)
-                   /* Ready for reading */
-#define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT |
-                     EPOLLERR)
-                   /* Ready for writing */
-#define POLLEX_SET  (EPOLLPRI)
-                   /* Exceptional condition */
-.EE
-.in
-.\"
-.SS Multithreaded applications
-If a file descriptor being monitored by
-.BR select ()
-is closed in another thread, the result is unspecified.
-On some UNIX systems,
-.BR select ()
-unblocks and returns, with an indication that the file descriptor is ready
-(a subsequent I/O operation will likely fail with an error,
-unless another process reopens the file descriptor between the time
-.BR select ()
-returned and the I/O operation is performed).
-On Linux (and some other systems),
-closing the file descriptor in another thread has no effect on
-.BR select ().
-In summary, any application that relies on a particular behavior
-in this scenario must be considered buggy.
-.\"
-.SS C library/kernel differences
-The Linux kernel allows file descriptor sets of arbitrary size,
-determining the length of the sets to be checked from the value of
-.IR nfds .
-However, in the glibc implementation, the
-.I fd_set
-type is fixed in size.
-See also BUGS.
-.P
-The
-.BR pselect ()
-interface described in this page is implemented by glibc.
-The underlying Linux system call is named
-.BR pselect6 ().
-This system call has somewhat different behavior from the glibc
-wrapper function.
-.P
-The Linux
-.BR pselect6 ()
-system call modifies its
-.I timeout
-argument.
-However, the glibc wrapper function hides this behavior
-by using a local variable for the timeout argument that
-is passed to the system call.
-Thus, the glibc
-.BR pselect ()
-function does not modify its
-.I timeout
-argument;
-this is the behavior required by POSIX.1-2001.
-.P
-The final argument of the
-.BR pselect6 ()
-system call is not a
-.I "sigset_t\ *"
-pointer, but is instead a structure of the form:
-.P
-.in +4n
-.EX
-struct {
-    const kernel_sigset_t *ss;   /* Pointer to signal set */
-    size_t ss_len;               /* Size (in bytes) of object
-                                    pointed to by \[aq]ss\[aq] */
-};
-.EE
-.in
-.P
-This allows the system call to obtain both
-a pointer to the signal set and its size,
-while allowing for the fact that most architectures
-support a maximum of 6 arguments to a system call.
-See
-.BR sigprocmask (2)
-for a discussion of the difference between the kernel and libc
-notion of the signal set.
-.\"
-.SS Historical glibc details
-glibc 2.0 provided an incorrect version of
-.BR pselect ()
-that did not take a
-.I sigmask
-argument.
-.P
-From glibc 2.1 to glibc 2.2.1,
-one must define
-.B _GNU_SOURCE
-in order to obtain the declaration of
-.BR pselect ()
-from
-.IR <sys/select.h> .
-.SH BUGS
-POSIX allows an implementation to define an upper limit,
-advertised via the constant
-.BR FD_SETSIZE ,
-on the range of file descriptors that can be specified
-in a file descriptor set.
-The Linux kernel imposes no fixed limit, but the glibc implementation makes
-.I fd_set
-a fixed-size type, with
-.B FD_SETSIZE
-defined as 1024, and the
-.BR FD_* ()
-macros operating according to that limit.
-To monitor file descriptors greater than 1023, use
-.BR poll (2)
-or
-.BR epoll (7)
-instead.
-.P
-The implementation of the
-.I fd_set
-arguments as value-result arguments is a design error that is avoided in
-.BR poll (2)
-and
-.BR epoll (7).
-.P
-According to POSIX,
-.BR select ()
-should check all specified file descriptors in the three file descriptor sets,
-up to the limit
-.IR nfds\-1 .
-However, the current implementation ignores any file descriptor in
-these sets that is greater than the maximum file descriptor number
-that the process currently has open.
-According to POSIX, any such file descriptor that is specified in one
-of the sets should result in the error
-.BR EBADF .
-.P
-Starting with glibc 2.1, glibc provided an emulation of
-.BR pselect ()
-that was implemented using
-.BR sigprocmask (2)
-and
-.BR select ().
-This implementation remained vulnerable to the very race condition that
-.BR pselect ()
-was designed to prevent.
-Modern versions of glibc use the (race-free)
-.BR pselect ()
-system call on kernels where it is provided.
-.P
-On Linux,
-.BR select ()
-may report a socket file descriptor as "ready for reading", while
-nevertheless a subsequent read blocks.
-This could for example
-happen when data has arrived but upon examination has the wrong
-checksum and is discarded.
-There may be other circumstances
-in which a file descriptor is spuriously reported as ready.
-.\" Stevens discusses a case where accept can block after select
-.\" returns successfully because of an intervening RST from the client.
-Thus it may be safer to use
-.B O_NONBLOCK
-on sockets that should not block.
-.\" Maybe the kernel should have returned EIO in such a situation?
-.P
-On Linux,
-.BR select ()
-also modifies
-.I timeout
-if the call is interrupted by a signal handler (i.e., the
-.B EINTR
-error return).
-This is not permitted by POSIX.1.
-The Linux
-.BR pselect ()
-system call has the same behavior,
-but the glibc wrapper hides this behavior by internally copying the
-.I timeout
-to a local variable and passing that variable to the system call.
-.SH EXAMPLES
-.\" SRC BEGIN (select.c)
-.EX
-#include <stdio.h>
-#include <stdlib.h>
-#include <sys/select.h>
-\&
-int
-main(void)
-{
-    int             retval;
-    fd_set          rfds;
-    struct timeval  tv;
-\&
-    /* Watch stdin (fd 0) to see when it has input. */
-\&
-    FD_ZERO(&rfds);
-    FD_SET(0, &rfds);
-\&
-    /* Wait up to five seconds. */
-\&
-    tv.tv_sec = 5;
-    tv.tv_usec = 0;
-\&
-    retval = select(1, &rfds, NULL, NULL, &tv);
-    /* Don\[aq]t rely on the value of tv now! */
-\&
-    if (retval == \-1)
-        perror("select()");
-    else if (retval)
-        printf("Data is available now.\en");
-        /* FD_ISSET(0, &rfds) will be true. */
-    else
-        printf("No data within five seconds.\en");
-\&
-    exit(EXIT_SUCCESS);
-}
-.EE
-.\" SRC END
-.SH SEE ALSO
-.BR accept (2),
-.BR connect (2),
-.BR poll (2),
-.BR read (2),
-.BR recv (2),
-.BR restart_syscall (2),
-.BR send (2),
-.BR sigprocmask (2),
-.BR write (2),
-.BR timespec (3),
-.BR epoll (7),
-.BR time (7)
-.P
-For a tutorial with discussion and examples, see
-.BR select_tut (2).