.. zsh-module-meta::
   :name: zsh/zselect
   :summary: Block and return when file descriptors are ready.

The ``zsh/zselect`` module makes available one builtin command:

.. index:: single: zselect; Function

.. index:: single: select, system call; Command

.. index:: single: file descriptors, waiting for; Command

``zselect`` [ ``-rwe`` ] [ ``-t`` :var:`timeout` ] [ ``-a`` :var:`array` ] [ ``-A`` :var:`assoc` ] [ :var:`fd` ... ]
    
    The ``zselect`` builtin is a front-end to the \`select' system call, which
    blocks until a file descriptor is ready for reading or writing, or has an
    error condition, with an optional timeout.  If this is not available on
    your system, the command prints an error message and returns status 2
    (normal errors return status 1).  For more information, see your system's
    documentation for :manpage:`select(2)`.  Note there is no connection with the
    shell builtin of the same name.
    
    Arguments and options may be intermingled in any order.  Non-option
    arguments are file descriptors, which must be decimal integers.  By
    default, file descriptors are to be tested for reading, i.e. ``zselect``
    will return when data is available to be read from the file descriptor, or
    more precisely, when a read operation from the file descriptor will not
    block.  After a ``-r``, ``-w`` and ``-e``, the given file descriptors are
    to be tested for reading, writing, or error conditions.  These options and
    an arbitrary list of file descriptors may be given in any order.
    
    (The presence of an \`error condition' is not well defined in the
    documentation for many implementations of the select system call.
    According to recent versions of the POSIX specification, it is really an
    :emphasis:`exception` condition, of which the only standard example is out-of-band
    data received on a socket.  So zsh users are unlikely to find the ``-e``
    option useful.)
    
    The option ``-t`` :var:`timeout` specifies a timeout in hundredths of a
    second.  This may be zero, in which case the file descriptors will simply
    be polled and ``zselect`` will return immediately.  It is possible to call
    zselect with no file descriptors and a non-zero timeout for use as a
    finer-grained replacement for \`sleep'; note, however, the return status is
    always 1 for a timeout.
    
    The option ``-a`` :var:`array` indicates that :var:`array` should be set to
    indicate the file descriptor(s) which are ready.  If the option
    is not
    given, the array ``reply`` will be used for this purpose.  The array will
    contain a string similar to the arguments for ``zselect``.  For example,
    
    
    .. code-block:: zsh
       :class: example

        zselect -t 0 -r 0 -w 1
    
    
    might return immediately with status 0 and ``$reply`` containing ``-r 0 -w
    1`` to show that both file descriptors are ready for the requested
    operations.
    
    The option ``-A`` :var:`assoc` indicates that the associative array
    :var:`assoc` should be set to indicate the file descriptor(s)
    which are ready.  This option overrides the option ``-a``, nor will
    ``reply`` be modified.  The keys of ``assoc`` are the file descriptors, and
    the corresponding values are any of the characters ``rwe`` to indicate
    the condition.
    
    The command returns status 0 if some file descriptors are ready for
    reading.  If the operation timed out, or a timeout of 0 was given and no
    file descriptors were ready, or there was an error, it returns status 1 and
    the array will not be set (nor modified in any way).  If there was an error
    in the select operation the appropriate error message is printed.
    

