(split) LDP: Update original to LDP v3.65

[linuxjm/LDP_man-pages.git] / original / man2 / select.2

diff --git a/original/man2/select.2 b/original/man2/select.2
index ff78008..8dd85ac 100644 (file)
--- a/original/man2/select.2
+++ b/original/man2/select.2
@@ -1,8 +1,7 @@
-.\" 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.
@@ -22,6 +21,7 @@
 .\"
 .\" 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>
@@ -35,7 +35,7 @@
 .\" 2005-03-11, mtk, modified pselect() text (it is now a system
 .\"     call in 2.6.16.
 .\"
-.TH SELECT 2 2012-05-02 "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
@@ -94,7 +94,7 @@ The operation of
 .BR select ()
 and
 .BR pselect ()
-is identical, with three differences:
+is identical, other than these three differences:
 .TP
 (i)
 .BR select ()
@@ -159,12 +159,22 @@ is the highest-numbered file descriptor in any of the three sets, plus 1.
 .PP
 The
 .I timeout
-argument specifies the minimum interval that
+argument specifies the interval that
 .BR select ()
 should block waiting for a file descriptor to become ready.
-(This interval will be rounded up to the system clock granularity,
+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.)
+may overrun by a small amount.
 If both fields of the
 .I timeval
 structure are zero, then
@@ -205,9 +215,9 @@ executing the following calls:
 
     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
@@ -229,7 +239,7 @@ then call
 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
@@ -286,7 +296,7 @@ returns.
 .\" 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
@@ -299,10 +309,11 @@ descriptor sets (that is, the total number of bits that are set in
 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
@@ -328,7 +339,7 @@ was added to Linux in kernel 2.6.16.
 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
@@ -411,13 +422,29 @@ when
 .B _GNU_SOURCE
 is defined.
 Since glibc 2.2.2 the requirements are as shown in the SYNOPSIS.
-.SS "Linux Notes"
+.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 gibc
+This system call has somewhat different behavior from the glibc
 wrapper function.
 
 The Linux
@@ -436,7 +463,7 @@ argument;
 this is the behavior required by POSIX.1-2001.
 
 The final argument of the
-.BR pselect6()
+.BR pselect6 ()
 system call is not a
 .I "sigset_t\ *"
 pointer, but is instead a structure of the form:
@@ -555,11 +582,7 @@ main(void)
     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),
@@ -570,3 +593,14 @@ For vaguely related stuff, see
 .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/.