socket_select

Runs the select() system call on the given arrays of sockets with a specified timeout

&reftitle.description; ``int``false```socket_select` ``array``null```read` ``array``null```write` ``array``null```except` ``int``null```seconds` `int` `microseconds` 0

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

&reftitle.parameters;

`read`

- 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 is also ready on end-of-file, in which case a `socket_read` will return a zero length string).

`write`

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

`except`

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

`seconds`

- The `seconds` and `microseconds` together form the `timeout` parameter. The `timeout` is an upper bound on the amount of time elapsed before `socket_select` return. `seconds` may be zero , causing `socket_select` to return immediately. This is useful for polling. If `seconds` is &null; (no timeout), `socket_select` can block indefinitely.

`microseconds`

On exit, the arrays are modified to indicate which socket 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.

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:

#### Using &null; with `socket_select`

    <?php
    $e = NULL;
    socket_select($r, $w, $e, 0);
    ?>

&reftitle.returnvalues;

On success `socket_select` returns the number of sockets 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`.

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;:

#### Understanding `socket_select`'s result

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

&reftitle.examples;

### `socket_select` example

    <?php
    /* Prepare the read array */
    $read   = array($socket1, $socket2);
    $write  = NULL;
    $except = NULL;
    $num_changed_sockets = socket_select($read, $write, $except, 0);

    if ($num_changed_sockets === false) {
        /* Error handling */
    } else if ($num_changed_sockets > 0) {
        /* At least at one of the sockets something interesting happened */
    }
    ?>

&reftitle.notes;

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 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 sockets in all arrays must be checked. Any socket that is available for writing must be written to, and any socket 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.

&reftitle.seealso;

- `socket_read`
- `socket_write`
- `socket_last_error`
- `socket_strerror`