cvs: phpdoc /en/reference/stream/functions stream-get-options.xml stream-select.xml

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>&amp;read</parameter></methodparam> <methodparam><type>resource</type><parameter>&amp;write</parameter></methodparam> <methodparam><type>resource</type><parameter>&amp;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 -->