   #PHP Manual Socket functions socket_recvmsg socket_send

   PHP Manual
   Prev  Next
   ______________________________________________________________________

                                 socket_select

   (PHP 4 >= 4.1.0)
   socket_select --  Runs the select() system call on the given arrays of
   sockets with a specified timeout

Description

   int socket_select ( array &read, array &write, array &except, int
   tv_sec [, int tv_usec])

   Warning

   This function is EXPERIMENTAL. The behaviour of this function, the
   name of this function, and anything else documented about this
   function may change without notice in a future release of PHP. Use
   this function at your own risk.

   socket_select() accepts arrays of sockets and waits for them to change
   status. Those coming with BSD sockets background will recognize that
   those socket resource arrays are in fact the so-called file descriptor
   sets. Three independent arrays of socket resources are watched.

   The sockets listed in the read array will be watched to see if
   characters become available for reading (more precisely, to see if a
   read will not block - in particular, a socket resource is also ready
   on end-of-file, in which case a socket_read() will return a zero
   length string).

   The sockets listed in the write array will be watched to see if a
   write will not block.

   The sockets listed in the except array will be watched for exceptions.

   Warning

   On exit, the arrays are modified to indicate which socket resource
   actually changed status.

   You do not need to pass every array to socket_select(). You can leave
   it out and use an empty array or NULL instead. Also do not forget that
   those arrays are passed by reference and will be modified after
   socket_select() returns.

   Example 1. socket_select() example
   <?php
   /* Prepare the read array */
   $read = array($socket1, $socket2);
   $num_changed_sockets = socket_select($read, $write = NULL, $except =
   NULL, 0);
   if ($num_changed_sockets === false) {
       /* Error handling */
   } else if ($num_changed_sockets > 0) {
       /* At least at one of the sockets something interesting happened
   */
   }
   ?>

     Note: Due a limitation in the current Zend Engine it is not
     possible to pass a constant modifier like NULL directly as a
     parameter to a function which expects this parameter to be passed
     by reference. Instead use a temporary variable or an expression
     with the leftmost member being a temporary variable:

   Example 2. Using NULL with socket_select()
   <?php
   socket_select($r, $w, $e = NULL, 0);
   ?>

   The tv_sec and tv_usec together form the timeout parameter. The
   timeout is an upper bound on the amount of time elapsed before
   socket_select() return. tv_sec may be zero , causing socket_select()
   to return immediately. This is useful for polling. If tv_sec is NULL
   (no timeout), socket_select() can block indefinitely.

   On success socket_select() returns the number of socket resources
   contained in the modified arrays, which may be zero if the timeout
   expires before anything interesting happens. On error FALSE is
   returned. The error code can be retrieved with socket_last_error().

     Note: Be sure to use the === operator when checking for an error.
     Since the socket_select() may return 0 the comparison with == would
     evaluate to TRUE:

   Example 3. Understanding socket_select()'s result
   <?php
   if (false === socket_select($r, $w, $e = NULL, 0)) {
       echo "socket_select() failed, reason: " .
           socket_strerror(socket_last_error()) . "\n";
   }
   ?>

     Note: Be aware that some socket implementations need to be handled
     very carefully. A few basic rules:

     * You should always try to use socket_select() without timeout. Your
       program should have nothing to do if there is no data available.
       Code that depends on timeouts is not usually portable and
       difficult to debug.
     * No socket resource must be added to any set if you do not intend
       to check its result after the socket_select() call, and respond
       appropriately. After socket_select() returns, all socket resources
       in all arrays must be checked. Any socket resource that is
       available for writing must be written to, and any socket resource
       available for reading must be read from.
     * If you read/write to a socket returns in the arrays be aware that
       they do not necessarily read/write the full amount of data you
       have requested. Be prepared to even only be able to read/write a
       single byte.
     * It's common to most socket implementations that the only exception
       caught with the except array is out-of-bound data received on a
       socket.

   See also socket_read(), socket_write(), socket_last_error() and
   socket_strerror().
   ______________________________________________________________________

   Prev           Home        Next
   socket_recvmsg  Up  socket_send
