-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" 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.
.\"
.\" 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>
.\" 2005-03-11, mtk, modified pselect() text (it is now a system
.\" call in 2.6.16.
.\"
-.TH SELECT 2 2008-12-05 "Linux" "Linux Programmer's Manual"
+.TH SELECT 2 2014-01-31 "Linux" "Linux Programmer's Manual"
.SH NAME
select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \-
synchronous I/O multiplexing
.BR select ()
and
.BR pselect ()
-is identical, with three differences:
+is identical, other than these three differences:
.TP
(i)
.BR select ()
.I nfds
is the highest-numbered file descriptor in any of the three sets, plus 1.
.PP
+The
.I timeout
-is an upper bound on the amount of time elapsed before
+argument specifies the interval that
.BR select ()
-returns.
+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
-stucture are zero, then
+structure are zero, then
.BR select ()
returns immediately.
(This is useful for polling.)
sigset_t origmask;
- sigprocmask(SIG_SETMASK, &sigmask, &origmask);
+ pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
- sigprocmask(SIG_SETMASK, &origmask, NULL);
+ pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.fi
.PP
The reason that
with the desired
.IR sigmask ,
avoiding the race.)
-.SS "The timeout"
+.SS The timeout
The time structures involved are defined in
.I <sys/time.h>
and look like
.\" 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"
+.SH RETURN VALUE
On success,
.BR select ()
and
which may be zero if the timeout expires before anything interesting happens.
On error, \-1 is returned, and
.I errno
-is set appropriately; the sets and
+is set to indicate the error;
+the file descriptor sets are unmodified,
+and
.I timeout
-become undefined, so do not
-rely on their contents after an error.
+becomes undefined.
.SH ERRORS
.TP
.B EBADF
Prior to this,
.BR pselect ()
was emulated in glibc (but see BUGS).
-.SH "CONFORMING TO"
+.SH CONFORMING TO
.BR select ()
conforms to POSIX.1-2001 and
4.4BSD
.B _GNU_SOURCE
is defined.
Since glibc 2.2.2 the requirements are as shown in the SYNOPSIS.
-.SS "Linux Notes"
-The Linux
+.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 Linux notes
+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.
is passed to the system call.
Thus, the glibc
.BR pselect ()
-function does not modify its timeout argument;
+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 ()
.I sigmask
argument.
-Since version 2.1, glibc has provided an emulation of
+Starting with version 2.1, glibc provided an emulation of
.BR pselect ()
-that is implemented using
+that was implemented using
.BR sigprocmask (2)
and
.BR select ().
-This implementation remains vulnerable to the very race condition that
+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
-(where a signal handler writes a byte to a pipe whose other end
+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.)
+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 ()
exit(EXIT_SUCCESS);
}
.fi
-.SH "SEE ALSO"
-For a tutorial with discussion and examples, see
-.BR select_tut (2).
-.LP
-For vaguely related stuff, see
+.SH SEE ALSO
.BR accept (2),
.BR connect (2),
.BR poll (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.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.