select.select(): Add note that though this function accepts empty lists,

                  using *only* empty lists may not be acceptable on all
                  platforms, with the specific caveat that it does not
                  work on Windows.  Also clarified list of acceptable
                  objects that may be in the lists, to let the user know
                  that file objects are not usable here on Windows.

1 files changed, 15 insertions, 13 deletions

diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex
index 44398aa..b79f5c2 100644
--- a/Doc/lib/libselect.tex
+++ b/Doc/lib/libselect.tex
@@ -33,14 +33,16 @@ polling objects.
 \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
 This is a straightforward interface to the \UNIX{} \cfunction{select()}
 system call.  The first three arguments are lists of `waitable
-objects': either integers representing \UNIX{} file descriptors or
+objects': either integers representing file descriptors or
 objects with a parameterless method named \method{fileno()} returning
 such an integer.  The three lists of waitable objects are for input,
 output and `exceptional conditions', respectively.  Empty lists are
-allowed.  The optional \var{timeout} argument specifies a time-out as a
-floating point number in seconds.  When the \var{timeout} argument
-is omitted the function blocks until at least one file descriptor is
-ready.  A time-out value of zero specifies a poll and never blocks.
+allowed, but acceptance of three empty lists is platform-dependent.
+(It is known to work on \UNIX{} but not on Windows.)  The optional
+\var{timeout} argument specifies a time-out as a floating point number
+in seconds.  When the \var{timeout} argument is omitted the function
+blocks until at least one file descriptor is ready.  A time-out value
+of zero specifies a poll and never blocks.
 
 The return value is a triple of lists of objects that are ready:
 subsets of the first three arguments.  When the time-out is reached
@@ -52,14 +54,14 @@ objects (e.g. \code{sys.stdin}, or objects returned by
 \function{open()} or \function{os.popen()}), socket objects
 returned by \function{socket.socket()},%
 \withsubitem{(in module socket)}{\ttindex{socket()}}
-\withsubitem{(in module os)}{\ttindex{popen()}}
-and the module \module{stdwin}\refbimodindex{stdwin} which happens to
-define a function
-\function{fileno()}\withsubitem{(in module stdwin)}{\ttindex{fileno()}}
-for just this purpose.  You may
-also define a \dfn{wrapper} class yourself, as long as it has an
-appropriate \method{fileno()} method (that really returns a \UNIX{}
-file descriptor, not just a random integer).
+\withsubitem{(in module os)}{\ttindex{popen()}}.
+You may also define a \dfn{wrapper} class yourself, as long as it has
+an appropriate \method{fileno()} method (that really returns a file
+descriptor, not just a random integer).
+\strong{Note:}\index{WinSock}  File objects on Windows are not
+acceptable, but sockets are.  On Windows, the underlying
+\cfunction{select()} function is provided by the WinSock library, and
+does not handle file desciptors that don't originate from WinSock.
 \end{funcdesc}
 
 \subsection{Polling Objects