socket_select
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
Runs the select() system call on the given arrays of sockets with a specified timeout
Description
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
readThe sockets listed in the
readarray 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 asocket_read()will return a zero length string).writeThe sockets listed in the
writearray will be watched to see if a write will not block.exceptThe sockets listed in the
exceptarray will be watched for exceptions.secondsThe
secondsandmicrosecondstogether form thetimeoutparameter. Thetimeoutis an upper bound on the amount of time elapsed beforesocket_select()returns.secondsmay be zero, causingsocket_select()to return immediately. This is useful for polling. Ifsecondsis null (no timeout),socket_select()can block indefinitely.microsecondsSee
secondsdescription.
On exit, the arrays are modified to indicate which socket actually changed status. The original keys of the Arrays are preserved.
The three arrays all have to be passed, but an array that is of no interest can be an empty Array or null; at least one of them must be a non-empty Array. They are passed by reference and are modified once socket_select() returns.
Due to 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);
?>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().
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";
}
?>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 */
}
?>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. Aftersocket_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. - When reading from or writing to a socket returned in the arrays, be aware that the full amount of data requested is not necessarily read or written. Be prepared for as little as a single byte.
- It's common to most socket implementations that the only exception caught with the
exceptarray is out-of-bound data received on a socket.