[PHP-DOC] cvs: phpdoc /en/functions sockets.xml From: Egon Schmid (eschmid <email protected>)
Date: 09/12/00

eschmid Tue Sep 12 12:58:00 2000 EDT

  Modified files:
    /phpdoc/en/functions sockets.xml
  Log:
  Added socket_get_status() and some formating.
  
Index: phpdoc/en/functions/sockets.xml
diff -u phpdoc/en/functions/sockets.xml:1.3 phpdoc/en/functions/sockets.xml:1.4
--- phpdoc/en/functions/sockets.xml:1.3 Wed Sep 6 19:44:12 2000
+++ phpdoc/en/functions/sockets.xml Tue Sep 12 12:58:00 2000
@@ -1,33 +1,30 @@
  <reference id="ref.sockets">
   <title>Socket functions</title>
   <titleabbrev>Sockets</titleabbrev>
+
   <partintro>
    <simpara>
     The socket extension implements a low-level interface to the
     socket communication functions, providing the possibility to act
     as a socket server as well as a client.
    </simpara>
-
    <para>
     The socket functions described here are part of an extension to
     PHP which must be enabled at compile time by giving the <option
     role="configure">--enable-sockets</option> option to
     <command>configure</command>.
    </para>
-
    <para>
     For a more generic client-side socket interface, see
     <function>fsockopen</function> and
     <function>pfsockopen</function>.
    </para>
-
    <para>
     When using these functions, it is important to remember that while
     many of them have identical names to their C counterparts, they
     often have different declarations. Please be sure to read the
     descriptions to avoid confusion.
    </para>
-
    <para>
     That said, those unfamiliar with socket programming can still find
     a lot of useful material in the appropriate Unix man pages, and
@@ -35,7 +32,6 @@
     programming in C on the web, much of which can be applied, with
     slight modifications, to socket programming in PHP.
    </para>
-
    <para>
     <example>
      <title>Socket example: Simple TCP/IP server</title>
@@ -48,61 +44,60 @@
       setup). Anything you type will then be output on the server
       side, and echoed back to you. To disconnect, enter 'quit'.
      </para>
- <programlisting>
+ <programlisting role="php">
 &lt;?php
-error_reporting(E_ALL);
+error_reporting (E_ALL);
 
 /* Allow the script to hang around waiting for connections. */
-set_time_limit(0);
+set_time_limit (0);
 
 $address = '192.168.1.53';
 $port = 10000;
 
-if (($sock = socket(AF_INET, SOCK_STREAM, 0)) &lt; 0) {
- echo "socket() failed: reason: " . strerror($sock) . "\n";
+if (($sock = socket (AF_INET, SOCK_STREAM, 0)) &lt; 0) {
+ echo "socket() failed: reason: " . strerror ($sock) . "\n";
 }
 
-if (($ret = bind($sock, $address, $port)) &lt; 0) {
- echo "bind() failed: reason: " . strerror($ret) . "\n";
+if (($ret = bind ($sock, $address, $port)) &lt; 0) {
+ echo "bind() failed: reason: " . strerror ($ret) . "\n";
 }
 
-if (($ret = listen($sock, 5)) &lt; 0) {
- echo "listen() failed: reason: " . strerror($ret) . "\n";
+if (($ret = listen ($sock, 5)) &lt; 0) {
+ echo "listen() failed: reason: " . strerror ($ret) . "\n";
 }
 
 do {
     if (($msgsock = accept_connect($sock)) &lt; 0) {
- echo "accept_connect() failed: reason: " . strerror($msgsock) . "\n";
+ echo "accept_connect() failed: reason: " . strerror ($msgsock) . "\n";
         break;
     }
     do {
         $buf = '';
- $ret = read($msgsock, $buf, 2048);
+ $ret = read ($msgsock, $buf, 2048);
         if ($ret &lt; 0) {
- echo "read() failed: reason: " . strerror($ret) . "\n";
+ echo "read() failed: reason: " . strerror ($ret) . "\n";
             break 2;
         }
         if ($ret == 0) {
             break 2;
         }
- $buf = trim($buf);
+ $buf = trim ($buf);
         if ($buf == 'quit') {
- close($msgsock);
+ close ($msgsock);
             break 2;
         }
         $talkback = "PHP: You said '$buf'.\n";
- write($msgsock, $talkback, strlen($talkback));
+ write ($msgsock, $talkback, strlen ($talkback));
         echo "$buf\n";
     } while (true);
- close($msgsock);
+ close ($msgsock);
 } while (true);
 
-close($sock);
+close ($sock);
 ?>
      </programlisting>
     </example>
    </para>
-
    <para>
     <example>
      <title>Socket example: Simple TCP/IP client</title>
@@ -113,26 +108,26 @@
      </para>
      <programlisting>
 &lt;?php
-error_reporting(E_ALL);
+error_reporting (E_ALL);
 
 echo "&lt;h2>TCP/IP Connection&lt;/h2>\n";
 
 /* Get the port for the WWW service. */
-$service_port = getservbyname('www', 'tcp');
+$service_port = getservbyname ('www', 'tcp');
 
 /* Get the IP address for the target host. */
-$address = gethostbyname('www.php.net');
+$address = gethostbyname ('www.php.net');
 
 /* Create a TCP/IP socket. */
-$socket = socket(AF_INET, SOCK_STREAM, 0);
+$socket = socket (AF_INET, SOCK_STREAM, 0);
 if ($socket &lt; 0) {
- echo "socket() failed: reason: " . strerror($socket) . "\n";
+ echo "socket() failed: reason: " . strerror ($socket) . "\n";
 } else {
- "socket() successful: " . strerror($socket) . "\n";
+ "socket() successful: " . strerror ($socket) . "\n";
 }
 
 echo "Attempting to connect to '$address' on port '$service_port'...";
-$result = connect($socket, $address, $service_port);
+$result = connect ($socket, $address, $service_port);
 if ($result &lt; 0) {
     echo "connect() failed.\nReason: ($result) " . strerror($result) . "\n";
 } else {
@@ -143,28 +138,27 @@
 $out = '';
 
 echo "Sending HTTP HEAD request...";
-write($socket, $in, strlen($in));
+write ($socket, $in, strlen ($in));
 echo "OK.\n";
 
 echo "Reading response:\n\n";
-while (read($socket, $out, 2048)) {
+while (read ($socket, $out, 2048)) {
     echo $out;
 }
 
 echo "Closing socket...";
-close($socket);
+close ($socket);
 echo "OK.\n\n";
 ?>
       </programlisting>
      </example>
     </para>
-
   </partintro>
 
   <refentry id="function.accept-connect">
    <refnamediv>
     <refname>accept_connect</refname>
- <refpurpose>Accepts a connection on a socket.</refpurpose>
+ <refpurpose>Accepts a connection on a socket</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -174,7 +168,6 @@
       <paramdef>int <parameter>socket</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      After the socket <parameter>socket</parameter> has been created
      using <function>socket</function>, bound to a name with
@@ -191,7 +184,6 @@
      <function>set_nonblock</function>, an error code will be
      returned.
     </para>
-
     <para>
      The socket descriptor returned by
      <function>accept_connect</function> may not be used to accept new
@@ -199,30 +191,28 @@
      <parameter>socket</parameter>, however, remains open and may be
      reused.
     </para>
-
     <para>
      Returns a new socket descriptor on success, or a negative error
      code on failure. This code may be passed to
      <function>strerror</function> to get a textual explanation of the
      error.
     </para>
-
     <para>
      See also
      <function>bind</function>,
      <function>connect</function>,
      <function>listen</function>,
- <function>socket</function>, and
+ <function>socket</function>,
+ <function>socket_get_status</function>, and
      <function>strerror</function>.
     </para>
-
    </refsect1>
   </refentry>
 
   <refentry id="function.bind">
    <refnamediv>
     <refname>bind</refname>
- <refpurpose>Binds a name to a socket.</refpurpose>
+ <refpurpose>Binds a name to a socket</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -236,14 +226,12 @@
       </paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      <function>bind</function> binds the name given in
      <parameter>address</parameter> to the socket described by
      <parameter>socket</parameter>, which must be a valid socket
      descriptor created with <function>socket</function>.
     </para>
-
     <para>
      The <parameter>address</parameter> parameter is either an IP
      address in dotted-quad notation
@@ -252,36 +240,33 @@
      Unix-domain socket, if the socket family is
      <constant>AF_UNIX</constant>.
     </para>
-
     <para>
      The <parameter>port</parameter> parameter is only used when
      connecting to an <constant>AF_INET</constant> socket, and
      designates the port on the remote host to which a connection
      should be made.
     </para>
-
     <para>
      Returns zero on success, or a negative error code on
      failure. This code may be passed to <function>strerror</function>
      to get a textual explanation of the error.
     </para>
-
     <para>
      See also
      <function>accept_connect</function>,
      <function>connect</function>,
      <function>listen</function>,
- <function>socket</function>, and
+ <function>socket</function>,
+ <function>socket_get_status</function>, and
      <function>strerror</function>.
     </para>
-
    </refsect1>
   </refentry>
 
   <refentry id="function.close">
    <refnamediv>
     <refname>close</refname>
- <refpurpose>Closes a file descriptor.</refpurpose>
+ <refpurpose>Closes a file descriptor</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -291,12 +276,10 @@
       <paramdef>int <parameter>socket</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      <function>close</function> closes the file (or socket) descriptor
      given by <parameter>socket</parameter>.
     </para>
-
     <para>
      Note that <function>close</function> should not be used on PHP
      file descriptors created with <function>fopen</function>,
@@ -305,24 +288,23 @@
      with <function>socket</function> or
      <function>accept_connect</function>.
     </para>
-
     <para>
      Returns true on success, or false if an error occurs (i.e.,
      <parameter>socket</parameter> is invalid).
     </para>
-
     <para>
      See also <function>bind</function>, <function>listen</function>,
- <function>socket</function>, and <function>strerror</function>.
+ <function>socket</function>,
+ <function>socket_get_status</function>, and
+ <function>strerror</function>.
     </para>
-
    </refsect1>
   </refentry>
 
   <refentry id="function.connect">
    <refnamediv>
     <refname>connect</refname>
- <refpurpose>Initiates a connection on a socket.</refpurpose>
+ <refpurpose>Initiates a connection on a socket</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -336,13 +318,11 @@
       </paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      Initiates a connection using the socket descriptor
      <parameter>socket</parameter>, which must be a valid socket
      descriptor created with <function>socket</function>.
     </para>
-
     <para>
      The <parameter>address</parameter> parameter is either an IP
      address in dotted-quad notation
@@ -351,35 +331,32 @@
      Unix-domain socket, if the socket family is
      <constant>AF_UNIX</constant>.
     </para>
-
     <para>
      The <parameter>port</parameter> parameter is only used when
      connecting to an <constant>AF_INET</constant> socket, and
      designates the port on the remote host to which a connection
      should be made.
     </para>
-
     <para>
      Returns zero on success, or a negative error code on
      failure. This code may be passed to <function>strerror</function>
      to get a textual explanation of the error.
     </para>
-
     <para>
      See also
      <function>bind</function>,
      <function>listen</function>,
- <function>socket</function>, and
+ <function>socket</function>,
+ <function>socket_get_status</function>, and
      <function>strerror</function>.
     </para>
-
    </refsect1>
   </refentry>
 
   <refentry id="function.listen">
    <refnamediv>
     <refname>listen</refname>
- <refpurpose>Listens for a connection on a socket.</refpurpose>
+ <refpurpose>Listens for a connection on a socket</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -390,7 +367,6 @@
       <paramdef>int <parameter>backlog</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      After the socket <parameter>socket</parameter> has been created
      using <function>socket</function> and bound to a name with
@@ -399,35 +375,32 @@
      <parameter>backlog</parameter> incoming connections will be
      queued for processing.
     </para>
-
     <para>
      <function>listen</function> is applicable only to sockets with
      type <literal>SOCK_STREAM</literal> or
      <literal>SOCK_SEQPACKET</literal>.
     </para>
-
     <para>
      Returns zero on success, or a negative error code on
      failure. This code may be passed to <function>strerror</function>
      to get a textual explanation of the error.
     </para>
-
     <para>
      See also
      <function>accept_connect</function>,
      <function>bind</function>,
      <function>connect</function>,
- <function>socket</function>, and
+ <function>socket</function>,
+ <function>socket_get_status</function>, and
      <function>strerror</function>.
     </para>
-
    </refsect1>
   </refentry>
 
   <refentry id="function.socket">
    <refnamediv>
     <refname>socket</refname>
- <refpurpose>Create a socket (endpoint for communication).</refpurpose>
+ <refpurpose>Create a socket (endpoint for communication)</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -439,18 +412,15 @@
       <paramdef>int <parameter>protocol</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      Creates a communication endpoint (a socket), and returns a
      descriptor to the socket.
     </para>
-
     <para>
      The <parameter>domain</parameter> parameter sets the
      domain. Currently, <constant>AF_INET</constant> and
      <constant>AF_UNIX</constant> are understood.
     </para>
-
     <para>
      The <parameter>type</parameter> parameter selects the socket
      type. This is one of <constant>SOCK_STREAM</constant>,
@@ -459,24 +429,77 @@
      <constant>SOCK_RAW</constant>, <constant>SOCK_RDM</constant>, or
      <constant>SOCK_PACKET</constant>.
     </para>
-
     <para>
      <parameter>protocol</parameter> sets the protocol.
     </para>
-
     <para>
      Returns a valid socket descriptor on success, or a negative error
      code on failure. This code may be passed to
      <function>strerror</function> to get a textual explanation of the
      error.
     </para>
-
     <para>
      For more information on the usage of <function>socket</function>,
      as well as on the meanings of the various parameters, see the
- Unix man page <filename>socket (2)</filename>.
+ Unix man page socket (2).
+ </para>
+ <para>
+ See also
+ <function>accept_connect</function>,
+ <function>bind</function>,
+ <function>connect</function>,
+ <function>listen</function>,
+ <function>strerror</function>, and
+ <function>socket_get_status</function>.
     </para>
+ </refsect1>
+ </refentry>
 
+ <refentry id="function.socket-get-status">
+ <refnamediv>
+ <refname>socket_get_status</refname>
+ <refpurpose>
+ Returns information about existing socket resource
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>socket_get_status</function></funcdef>
+ <paramdef>resource
+ <parameter>socket_get_status</parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Returns information about existing socket resource. Currently
+ returns 4 entries in the result array:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>timed_out</parameter> (bool) - The socket timed out
+ waiting for data
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>blocked</parameter> (bool) - The socket was blocked
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>eof</parameter> (bool) - Indicates EOF event
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>unread_bytes</parameter> (bool) - Number of bytes
+ left in the socket buffer
+ </para>
+ </listitem>
+ </itemizedlist>
     <para>
      See also
      <function>accept_connect</function>,
@@ -485,14 +508,13 @@
      <function>listen</function>, and
      <function>strerror</function>.
     </para>
-
    </refsect1>
   </refentry>
   
   <refentry id="function.strerror">
    <refnamediv>
     <refname>strerror</refname>
- <refpurpose>Return a string describing a socket error.</refpurpose>
+ <refpurpose>Return a string describing a socket error</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -502,7 +524,6 @@
       <paramdef>int <parameter>errno</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
-
     <para>
      <function>strerror</function> takes as its
      <parameter>errno</parameter> parameter the return value of one of
@@ -513,22 +534,20 @@
      just pass it to <function>strerror</function>, and it tells you
      what happened.
     </para>
-
     <para>
      <example>
       <title><function>strerror</function> example</title>
- <programlisting>
+ <programlisting role="php">
 &lt;?php
-if (($socket = socket(AF_INET, SOCK_STREAM, 0)) &lt; 0) {
- echo "socket() failed: reason: " . strerror($socket) . "\n";
+if (($socket = socket (AF_INET, SOCK_STREAM, 0)) &lt; 0) {
+ echo "socket() failed: reason: " . strerror ($socket) . "\n";
 }
 
-if (($ret = bind($socket, '127.0.0.1', 80)) &lt; 0) {
- echo "bind() failed: reason: " . strerror($ret) . "\n";
+if (($ret = bind ($socket, '127.0.0.1', 80)) &lt; 0) {
+ echo "bind() failed: reason: " . strerror ($ret) . "\n";
 }
 ?>
       </programlisting>
-
       <para>
        The expected output from the above example (assuming the script
        is not run with root privileges):
@@ -536,19 +555,17 @@
         bind() failed: reason: Permission denied
        </screen>
       </para>
-
      </example>
     </para>
-
     <para>
      See also
      <function>accept_connect</function>,
      <function>bind</function>,
      <function>connect</function>,
- <function>listen</function>, and
- <function>socket</function>.
+ <function>listen</function>,
+ <function>socket</function>, and
+ <function>socket_get_status</function>.
     </para>
-
    </refsect1>
   </refentry>