cvs: phpdoc /en/reference/sockets/functions socket-select.xml

mfischer Wed May 1 04:49:57 2002 EDT Modified files: /phpdoc/en/reference/sockets/functions socket-select.xml Log: - Update docs. Index: phpdoc/en/reference/sockets/functions/socket-select.xml diff -u phpdoc/en/reference/sockets/functions/socket-select.xml:1.2 phpdoc/en/reference/sockets/functions/socket-select.xml:1.3 --- phpdoc/en/reference/sockets/functions/socket-select.xml:1.2 Wed Apr 17 02:44:10 2002 +++ phpdoc/en/reference/sockets/functions/socket-select.xml Wed May 1 04:49:56 2002 @@ -1,24 +1,147 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> <refentry id="function.socket-select"> <refnamediv> <refname>socket_select</refname> - <refpurpose>Runs the select() system call on the sets mentioned with a timeout specified by tv_sec and tv_usec </refpurpose> + <refpurpose>Runs the select() system call on the given arrays of sockets with a timeout specified by tv_sec and tv_usec </refpurpose> </refnamediv> <refsect1> <title>Description</title> <methodsynopsis> <type>int</type><methodname>socket_select</methodname> - <methodparam><type>resource</type><parameter>read_fd</parameter></methodparam> - <methodparam><type>resource</type><parameter>write_fd</parameter></methodparam> - <methodparam><type>resource</type><parameter>except_fd</parameter></methodparam> + <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> &warn.experimental.func; <para> - &warn.undocumented.func; + The <function>socket_select</function> accepts arrays of sockets and + waits for them to change status. Those coming with BSD sockets background + will recognize that those socket resource arrays are in fact the + so-called file descriptor sets. Three independent arrays of socket + resources are watched. + </para> + <para> + The sockets 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 socket resource is also ready on + end-of-file, in which case a <function>socket_read</function> will return + a zero length string). + </para> + <para> + The sockets listed in the <parameter>write</parameter> array will be + watched to see if a write will not block. + </para> + <para> + The sockets listed in the <parameter>except</parameter> array will be + watched for exceptions. + </para> + <para> + On exit, the arrays are modified to indicate which socket resource + actually changed status. + </para> + <para> + You do not need to pass every array to + <function>socket_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>socket_select</function> returns. + </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[ +socket_select($r, $w, $e = NULL, 0); +]]> + </programlisting> + </para> + </note> + <para> + 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>socket_select</function> return. + <parameter>tv_sec</parameter> may be zero , causing + <function>socket_select</function> to return immediately. This is useful + for polling. If <parameter>tv_sec</parameter> is &null; (no timeout), + <function>socket_select</function> can block indefinitely. + </para> + <para> + On success <function>socket_select</function> returns the number of + socket resorces 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 + <function>socket_last_error</function>. + </para> + <note> + <para> + Be sure to use the <literal>===</literal> operator when checking for an + error. Since the <function>socket_select</function> may return 0 the + comparison with <literal>==</literal> would evaluate to &true;: + <programlisting role="php"> +<![CDATA[ +if (false === socket_select($r, $w, $e = NULL, 0)) { + echo "socket_select() failed, reason: " . socket_strerror(socket_last_error()) . "\n"; +} +]]> + </programlisting> + </para> + </note> + <note> + <para> + Be aware that some socket imeplementations need to be handled very + carefully. A few basic rules: + <itemizedlist> + <listitem> + <simpara> + You should always try to use <function>socket_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> + No socket resource must be added to any set if you do not intend to + check its result after the <function>socket_select</function> call, + and respond appropriately. After <function>socket_select</function> + returns, all socket resources in all arrays must be checked. Any + socket resource that is available for writing must be written to, and + any socket resource available for reading must be read from. + </simpara> + </listitem> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + <listitem> + <simpara> + It's common to most socket implementations that the only exception + caught with the <parameter>except</parameter> array is out-of-bound + data received on a socket. + </simpara> + </listitem> + </itemizedlist> + </para> + </note> + <para> + See also + <function>socket_read</function>, + <function>socket_write</function>, + <function>socket_last_error</function> and + <function>socket_strerror</function>. </para> </refsect1> </refentry>