pollita Fri Jan 3 13:55:46 2003 EDT
Added files:
/phpdoc/en/reference/stream/functions stream-get-options.xml
stream-select.xml
Log:
New documentation.
Index: phpdoc/en/reference/stream/functions/stream-get-options.xml
+++ phpdoc/en/reference/stream/functions/stream-get-options.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.stream-get-options">
<refnamediv>
<refname>stream_get_options</refname>
<refpurpose>Retrieve options for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_get_options</methodname>
<methodparam><type>resource</type><parameter>stream|context</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns an array of options on the specified stream or context.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/reference/stream/functions/stream-select.xml
+++ phpdoc/en/reference/stream/functions/stream-select.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.stream-select">
<refnamediv>
<refname>stream_select</refname>
<refpurpose>Runs the equivalent of the select() system call on the given
arrays of streams with a timeout specified by tv_sec and tv_usec </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_select</methodname>
<methodparam><type>resource</type><parameter>&read</parameter></methodparam>
<methodparam><type>resource</type><parameter>&write</parameter></methodparam>
<methodparam><type>resource</type><parameter>&except</parameter></methodparam>
<methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>tv_usec</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>stream_select</function> function accepts arrays of streams and
waits for them to change status. Its opperation is equivalent to that of
the <function>socket_select</function> function except in that it acts on streams.
</simpara>
<simpara>
The streams listed in the <parameter>read</parameter> 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 <function>fread</function> will return
a zero length string).
</simpara>
<simpara>
The streams listed in the <parameter>write</parameter> array will be
watched to see if a write will not block.
</simpara>
<simpara>
The streams listed in the <parameter>except</parameter> array will be
watched for exceptions.
</simpara>
<warning>
<para>
On exit, the arrays are modified to indicate which stream resource
actually changed status.
</para>
</warning>
<simpara>
You do not need to pass every array to
<function>stream_select</function>. You can leave it out and use an
empty array or &null; instead. Also do not forget that those arrays are
passed <emphasis>by reference</emphasis> and will be modified after
<function>stream_select</function> returns.
</simpara>
<para>
Example:
<programlisting role="php">
<![CDATA[
/* Prepare the read array */
$read = array($stream1, $stream2);
if (false === ($num_changed_streams = stream_select($read, $write = NULL, $except =
NULL, 0))) {
/* Error handling */
else if ($num_changed_streams > 0) {
/* At least on one of the streams something interesting happened */
}
]]>
</programlisting>
</para>
<note>
<para>
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:
<programlisting role="php">
<![CDATA[
stream_select($r, $w, $e = NULL, 0);
]]>
</programlisting>
</para>
</note>
<simpara>
The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter>
together form the <emphasis>timeout</emphasis> parameter. The
<emphasis>timeout</emphasis> is an upper bound on the amount of time
elapsed before <function>stream_select</function> returns.
<parameter>tv_sec</parameter> may be zero , causing
<function>stream_select</function> to return immediately. This is useful
for polling. If <parameter>tv_sec</parameter> is &null; (no timeout),
<function>stream_select</function> can block indefinitely.
</simpara>
<simpara>
On success <function>stream_select</function> returns the number of
stream resorces contained in the modified arrays, which may be zero if
the timeout expires before anything interesting happens. On error &false;
is returned.
</simpara>
<note>
<para>
Be sure to use the <literal>===</literal> operator when checking for an
error. Since the <function>stream_select</function> may return 0 the
comparison with <literal>==</literal> would evaluate to &true;:
<programlisting role="php">
<![CDATA[
if (false === stream_select($r, $w, $e = NULL, 0)) {
echo "stream_select() failed\n";
}
]]>
</programlisting>
</para>
</note>
<note>
<para>
Be aware that some stream implementations need to be handled very
carefully. A few basic rules:
<itemizedlist>
<listitem>
<simpara>
You should always try to use <function>stream_select</function>
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.
</simpara>
</listitem>
<listitem>
<simpara>
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.
</simpara>
</listitem>
</itemizedlist>
</para>
</note>
<para>
See also
<function>stream_set_blocking</function>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
