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>


Reply via email to