+++ /dev/null
-.\" This manpage is copyright (C) 1992 Drew Eckhardt,
-.\" copyright (C) 1995 Michael Shields.
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.\" 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 2.6.16.
-.\"
-.TH SELECT 2 2015-01-22 "Linux" "Linux Programmer's Manual"
-.SH NAME
-select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \-
-synchronous I/O multiplexing
-.SH SYNOPSIS
-.nf
-/* According to POSIX.1-2001 */
-.br
-.B #include <sys/select.h>
-.sp
-/* According to earlier standards */
-.br
-.B #include <sys/time.h>
-.br
-.B #include <sys/types.h>
-.br
-.B #include <unistd.h>
-.sp
-.BI "int select(int " nfds ", fd_set *" readfds ", fd_set *" writefds ,
-.BI " fd_set *" exceptfds ", struct timeval *" timeout );
-.sp
-.BI "void FD_CLR(int " fd ", fd_set *" set );
-.br
-.BI "int FD_ISSET(int " fd ", fd_set *" set );
-.br
-.BI "void FD_SET(int " fd ", fd_set *" set );
-.br
-.BI "void FD_ZERO(fd_set *" set );
-.sp
-.B #include <sys/select.h>
-.sp
-.BI "int pselect(int " nfds ", fd_set *" readfds ", fd_set *" writefds ,
-.BI " fd_set *" exceptfds ", const struct timespec *" timeout ,
-.BI " const sigset_t *" sigmask );
-.fi
-.sp
-.in -4n
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.BR pselect ():
-_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
-.SH DESCRIPTION
-.BR select ()
-and
-.BR pselect ()
-allow 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)
-without blocking, or a sufficiently small
-.BR write (2)).
-.PP
-The operation of
-.BR select ()
-and
-.BR pselect ()
-is identical, other than these three differences:
-.TP
-(i)
-.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).
-.TP
-(ii)
-.BR select ()
-may update the
-.I timeout
-argument to indicate how much time was left.
-.BR pselect ()
-does not change this argument.
-.TP
-(iii)
-.BR select ()
-has no
-.I sigmask
-argument, and behaves as
-.BR pselect ()
-called with NULL
-.IR sigmask .
-.PP
-Three independent sets of file descriptors are watched.
-Those listed in
-.I readfds
-will be watched to see if characters become
-available for reading (more precisely, to see if a read will not
-block; in particular, a file descriptor is also ready on end-of-file),
-those in
-.I writefds
-will be watched to see if space is available for write (though a large
-write may still block), and those in
-.I exceptfds
-will be watched for exceptions.
-On exit, the sets are modified in place
-to indicate which file descriptors actually changed status.
-Each of the three file descriptor sets may be specified as NULL
-if no file descriptors are to be watched for the corresponding class
-of events.
-.PP
-Four macros are provided to manipulate the sets.
-.BR FD_ZERO ()
-clears a set.
-.BR FD_SET ()
-and
-.BR FD_CLR ()
-respectively add and remove a given file descriptor from a set.
-.BR FD_ISSET ()
-tests to see if a file descriptor is part of the set;
-this is useful after
-.BR select ()
-returns.
-.PP
-.I nfds
-is the highest-numbered file descriptor in any of the three sets, plus 1.
-.PP
-The
-.I timeout
-argument specifies the interval that
-.BR select ()
-should block waiting for a file descriptor to become ready.
-The call will block until either:
-.IP * 3
-a file descriptor becomes ready;
-.IP *
-the call is interrupted by a signal handler; or
-.IP *
-the timeout expires.
-.PP
-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.
-If both fields of the
-.I timeval
-structure are zero, then
-.BR select ()
-returns immediately.
-(This is useful for polling.)
-If
-.I timeout
-is NULL (no timeout),
-.BR select ()
-can block indefinitely.
-.PP
-.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.
-.PP
-Other than the difference in the precision of the
-.I timeout
-argument, the following
-.BR pselect ()
-call:
-.nf
-
- ready = pselect(nfds, &readfds, &writefds, &exceptfds,
- timeout, &sigmask);
-
-.fi
-is equivalent to
-.I atomically
-executing the following calls:
-.nf
-
- sigset_t origmask;
-
- pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
- ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
- pthread_sigmask(SIG_SETMASK, &origmask, NULL);
-.fi
-.PP
-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 time structures involved are defined in
-.I <sys/time.h>
-and look like
-
-.in +4n
-.nf
-struct timeval {
- long tv_sec; /* seconds */
- long tv_usec; /* microseconds */
-};
-.fi
-.in
-
-and
-
-.in +4n
-.nf
-struct timespec {
- long tv_sec; /* seconds */
- long tv_nsec; /* nanoseconds */
-};
-.fi
-.in
-
-(However, see below on the POSIX.1-2001 versions.)
-.PP
-Some code calls
-.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.
-.PP
-On Linux,
-.BR select ()
-modifies
-.I timeout
-to reflect the amount of time not slept; most other implementations
-do not do this.
-(POSIX.1-2001 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.
-.\" .PP - 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 )
-which may be zero if the timeout expires before anything interesting happens.
-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.)
-.TP
-.B EINTR
-A signal was caught; see
-.BR signal (7).
-.TP
-.B EINVAL
-.I nfds
-is negative or exceeds the
-.BR 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
-.BR pselect ()
-was added to Linux in kernel 2.6.16.
-Prior to this,
-.BR pselect ()
-was emulated in glibc (but see BUGS).
-.SH CONFORMING TO
-.BR select ()
-conforms to POSIX.1-2001 and
-4.4BSD
-.RB ( select ()
-first appeared in 4.2BSD).
-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 exit, but the BSD variant does not.
-.PP
-.BR pselect ()
-is defined in POSIX.1g, and in
-POSIX.1-2001.
-.SH NOTES
-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.
-
-Concerning the types involved, the classical situation is that
-the two fields of a
-.I timeval
-structure are typed as
-.I long
-(as shown above), and the structure is defined in
-.IR <sys/time.h> .
-The POSIX.1-2001 situation is
-
-.in +4n
-.nf
-struct timeval {
- time_t tv_sec; /* seconds */
- suseconds_t tv_usec; /* microseconds */
-};
-.fi
-.in
-
-where the structure is defined in
-.I <sys/select.h>
-and the data types
-.I time_t
-and
-.I suseconds_t
-are defined in
-.IR <sys/types.h> .
-.LP
-Concerning prototypes, the classical situation is that one should
-include
-.I <time.h>
-for
-.BR select ().
-The POSIX.1-2001 situation is that one should include
-.I <sys/select.h>
-for
-.BR select ()
-and
-.BR pselect ().
-
-Under glibc 2.0,
-.I <sys/select.h>
-gives the wrong prototype for
-.BR pselect ().
-Under glibc 2.1 to 2.2.1, it gives
-.BR pselect ()
-when
-.B _GNU_SOURCE
-is defined.
-Since glibc 2.2.2, the requirements are as shown in the SYNOPSIS.
-.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 the file descriptor reopened between the time
-.BR select ()
-returned and the I/O operations was 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 ABI differences
-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.
-
-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.
-
-The final argument of the
-.BR pselect6 ()
-system call is not a
-.I "sigset_t\ *"
-pointer, but is instead a structure of the form:
-.in +4
-.nf
-
-struct {
- const sigset_t *ss; /* Pointer to signal set */
- size_t ss_len; /* Size (in bytes) of object pointed
- to by 'ss' */
-};
-
-.fi
-.in
-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.
-.SH BUGS
-Glibc 2.0 provided a version of
-.BR pselect ()
-that did not take a
-.I sigmask
-argument.
-
-Starting with version 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.
-
-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.)
-
-Under 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 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?
-
-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-2001.
-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 EXAMPLE
-.nf
-#include <stdio.h>
-#include <stdlib.h>
-#include <sys/time.h>
-#include <sys/types.h>
-#include <unistd.h>
-
-int
-main(void)
-{
- fd_set rfds;
- struct timeval tv;
- int retval;
-
- /* 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't rely on the value of tv now! */
-
- if (retval == \-1)
- perror("select()");
- else if (retval)
- printf("Data is available now.\\n");
- /* FD_ISSET(0, &rfds) will be true. */
- else
- printf("No data within five seconds.\\n");
-
- exit(EXIT_SUCCESS);
-}
-.fi
-.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 epoll (7),
-.BR time (7)
-
-For a tutorial with discussion and examples, see
-.BR select_tut (2).
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
