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

- « socket_recvmsg

- socket_send »

- PHP Manual
- Socket Functions
- Runs the select() system call on the given arrays of sockets with a specified timeout

# socket_select

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

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

### Description

socket_select(
?array `&$read`,
?array `&$write`,
?array `&$except`,
?int `$seconds`,
int `$microseconds` = 0
): int|false

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.

### 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`

Warning

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.

> 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 #1 Using `null` with socket_select()

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

### Return Values

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().

> 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 #2 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";}?>

### Examples

Example #3 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 */}?>

### Notes

> 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 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.

### See Also

- socket_read() - Reads a maximum of length bytes from a socket
- socket_write() - Write to a socket
- socket_last_error() - Returns the last error on the socket
- socket_strerror() - Return a string describing a socket error