STREAM_SELECT(3) 1 STREAM_SELECT(3)
stream_select - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
SYNOPSIS
int stream_select (array &$read, array &$write, array &$except, int $tv_sec, [int $tv_usec])
DESCRIPTION
The stream_select(3) function accepts arrays of streams and waits for them to change status. Its operation is equivalent to that of the
socket_select(3) function except in that it acts on streams.
PARAMETERS
o $read
- The streams 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 stream resource is also ready on end-of-file, in which case an fread(3) will return a
zero length string).
o $write
- The streams listed in the $write array will be watched to see if a write will not block.
o $except
- The streams listed in the $except array will be watched for high priority exceptional ("out-of-band") data arriving.
Note
When stream_select(3) returns, the arrays $read, $write and $except are modified to indicate which stream resource(s) actu-
ally changed status.
You do not need to pass every array to stream_select(3). 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 stream_select(3) returns.
o $tv_sec
- The $tv_sec and $tv_usec together form the timeout parameter, $tv_sec specifies the number of seconds while $tv_usec the number
of microseconds. The $timeout is an upper bound on the amount of time that stream_select(3) will wait before it returns. If
$tv_sec and $tv_usec are both set to 0, stream_select(3) will not wait for data - instead it will return immediately, indicating
the current status of the streams. If $tv_sec is NULLstream_select(3) can block indefinitely, returning only when an event on one
of the watched streams occurs (or if a signal interrupts the system call).
Warning
Using a timeout value of 0 allows you to instantaneously poll the status of the streams, however, it is NOT a good idea to
use a 0 timeout value in a loop as it will cause your script to consume too much CPU time.
It is much better to specify a timeout value of a few seconds, although if you need to be checking and running other code
concurrently, using a timeout value of at least 200000 microseconds will help reduce the CPU usage of your script.
Remember that the timeout value is the maximum time that will elapse; stream_select(3) will return as soon as the requested
streams are ready for use.
o $tv_usec
- See $tv_sec description.
RETURN VALUES
On success stream_select(3) returns the number of stream resources contained in the modified arrays, which may be zero if the timeout
expires before anything interesting happens. On error FALSE is returned and a warning raised (this can happen if the system call is inter-
rupted by an incoming signal).
EXAMPLES
Example #1
stream_select(3) Example
This example checks to see if data has arrived for reading on either $stream1 or $stream2. Since the timeout value is 0 it will
return immediately:
<?php
/* Prepare the read array */
$read = array($stream1, $stream2);
$write = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
/* Error handling */
} elseif ($num_changed_streams > 0) {
/* At least on one of the streams something interesting happened */
}
?>
NOTES
Note
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 left-
most member being a temporary variable:
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
Note
Be sure to use the === operator when checking for an error. Since the stream_select(3) may return 0 the comparison with == would
evaluate to TRUE:
<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
echo "stream_select() failed
";
}
?>
Note
If you read/write to a stream returned 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.
Note
Some streams (like zlib) cannot be selected by this function.
Note
Windows compatibility: stream_select(3) used on a pipe returned from proc_open(3) may cause data loss under Windows 98.
Use of stream_select(3) on file descriptors returned by proc_open(3) will fail and return FALSE under Windows.
SEE ALSO
stream_set_blocking(3).
PHP Documentation Group STREAM_SELECT(3)