Doc/libselect.tex

   1 \section{Built-in Module \sectcode{select}}
   2 \bimodindex{select}
   3
   4 This module provides access to the function \code{select} available in
   5 most \UNIX{} versions.  It defines the following:
   6
   7 \renewcommand{\indexsubitem}{(in module select)}
   8 \begin{excdesc}{error}
   9 The exception raised when an error occurs.  The accompanying value is
  10 a pair containing the numeric error code from \code{errno} and the
  11 corresponding string, as would be printed by the C function
  12 \code{perror()}.
  13 \end{excdesc}
  14
  15 \begin{funcdesc}{select}{iwtd\, owtd\, ewtd\optional{\, timeout}}
  16 This is a straightforward interface to the \UNIX{} \code{select()}
  17 system call.  The first three arguments are lists of `waitable
  18 objects': either integers representing \UNIX{} file descriptors or
  19 objects with a parameterless method named \code{fileno()} returning
  20 such an integer.  The three lists of waitable objects are for input,
  21 output and `exceptional conditions', respectively.  Empty lists are
  22 allowed.  The optional \var{timeout} argument specifies a time-out as a
  23 floating point number in seconds.  When the \var{timeout} argument
  24 is omitted the function blocks until at least one file descriptor is
  25 ready.  A time-out value of zero specifies a poll and never blocks.
  26
  27 The return value is a triple of lists of objects that are ready:
  28 subsets of the first three arguments.  When the time-out is reached
  29 without a file descriptor becoming ready, three empty lists are
  30 returned.
  31
  32 Amongst the acceptable object types in the lists are Python file
  33 objects (e.g. \code{sys.stdin}, or objects returned by \code{open()}
  34 or \code{posix.popen()}), socket objects returned by
  35 \code{socket.socket()}, and the module \code{stdwin} which happens to
  36 define a function \code{fileno()} for just this purpose.  You may
  37 also define a \dfn{wrapper} class yourself, as long as it has an
  38 appropriate \code{fileno()} method (that really returns a \UNIX{} file
  39 descriptor, not just a random integer).
  40 \end{funcdesc}
  41 \ttindex{socket}
  42 \ttindex{stdwin}