- Expand introduction a bit

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@80634 c90b9560-bf6c-de11-be94-00142212c4b1

reference/sockets/reference.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
  <reference id="ref.sockets">
   <title>Socket functions</title>
   <titleabbrev>Sockets</titleabbrev>
@@ -7,9 +7,9 @@
   <partintro>
    &warn.experimental;
    <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.
+    The socket extension implements a low-level interface to the socket
+    communication functions based on the popular BSD sockets, 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
@@ -29,11 +29,40 @@
     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
-    there is a great deal of tutorial information on socket
-    programming in C on the web, much of which can be applied, with
-    slight modifications, to socket programming in PHP.
+    The socket extension was written to provide a useable interface to the
+    powerful BSD sockets. Care has been taken that the functions work equaly
+    well on Win32 and Unix implementations. Almost all of the sockets
+    functions may fail under certain conditions and therefore emit an
+    <literal>E_WARNING</literal> message describing the error. Sometimes this
+    doesn't happen to the desire of the developer. For example the function
+    <function>socket_read</function> may suddenly emit an
+    <literal>E_WARNING</literal> message because the connection broke
+    unexpectedly. It's common to suppress the warning with the
+    <literal>@</literal>-operator and catch the error code within the
+    application with the <function>socket_last_error</function> function. You
+    may call the <function>socket_strerror</function> function with this error
+    code to retrieve a string describing the error. See their description for
+    more information.
+   </para>
+   <note>
+    <para>
+     The <literal>E_WARNING</literal> messages generated by the socket
+     extension are in english though the retrieved error message will appear
+     depending on the current locale (<literal>LC_MESSAGES</literal>):
+     <programlisting role="php">
+<![CDATA[
+Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet
+]]>
+     </programlisting>
+    </para>
+   </note>
+   <para>
+    That said, those unfamiliar with socket programming can still find a lot
+    of useful material in the appropriate Unix man pages, and there is a great
+    deal of tutorial information on socket programming in C on the web, much
+    of which can be applied, with slight modifications, to socket programming
+    in PHP. The <ulink url="http://www.developerweb.net/sock-faq/">UNIX Socket
+    FAQ</ulink> might be a good start.
    </para>
    <para>
     <example>