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

mfischer                Tue Apr 30 18:48:37 2002 EDT

  Modified files:              
    /phpdoc/en/reference/sockets/functions      socket-create.xml 
  Log:
  - Update docs.
  
  
Index: phpdoc/en/reference/sockets/functions/socket-create.xml
diff -u phpdoc/en/reference/sockets/functions/socket-create.xml:1.2 
phpdoc/en/reference/sockets/functions/socket-create.xml:1.3
--- phpdoc/en/reference/sockets/functions/socket-create.xml:1.2 Wed Apr 17 
02:44:07 2002
+++ phpdoc/en/reference/sockets/functions/socket-create.xml     Tue Apr 30 
18:48:37 2002
@@ -1,5 +1,5 @@
 <?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.4 -->
   <refentry id="function.socket-create">
    <refnamediv>
@@ -16,13 +16,17 @@
      </methodsynopsis>
      &warn.experimental.func;
     <para>
-     Creates a communication endpoint (a socket), and returns a
-     descriptor to the socket.
+     Creates a communication endpoint (a socket), and returns a socket
+     resource.
     </para>
     <para>
-     The <parameter>domain</parameter> parameter sets the
-     domain. Currently, <constant>AF_INET</constant> and
-     <constant>AF_UNIX</constant> are understood.
+     The <parameter>domain</parameter> parameter sets the domain (protocol
+     family) to be used for communication. Currently,
+     <constant>AF_INET</constant> and <constant>AF_UNIX</constant> are
+     understood. <constant>AF_INET</constant> is typical used for internet
+     based communication. <constant>AF_UNIX</constant> uses pathnames to
+     identify sockets and can therefore only be used for local communication
+     (which is faster, on the other hand).
     </para>
     <para>
      The <parameter>type</parameter> parameter selects the socket
@@ -30,14 +34,20 @@
      <constant>SOCK_DGRAM</constant>,
      <constant>SOCK_SEQPACKET</constant>,
      <constant>SOCK_RAW</constant>, <constant>SOCK_RDM</constant>, or
-     <constant>SOCK_PACKET</constant>.
+     <constant>SOCK_PACKET</constant>. The two most common types are
+     <constant>SOCK_DGRAM</constant> for <literal>UDP</literal>
+     (connectionless) communication
+     and <constant>SOCK_STREAM</constant> for <literal>TCP</literal>
+     communication.
     </para>
     <para>
-     <parameter>protocol</parameter> sets the protocol.
+     <parameter>protocol</parameter> sets the protocol which is either
+     <constant>SOL_UDP</constant> or <constant>SOL_TCP</constant>.
     </para>
     <para>
-     Returns a valid socket descriptor on success, or a negative error
-     code on failure. This code may be passed to
+     Returns a socket resource on success, or &false; on error. The actual
+     error code can be retrieved by calling
+     <function>socket_last_error</function>. This error code may be passed to
      <function>socket_strerror</function> to get a textual explanation of the
      error.
     </para>
@@ -46,12 +56,22 @@
      as well as on the meanings of the various parameters, see the
      Unix man page socket (2).
     </para>
+    <note>
+     <para>
+      If an invalid <parameter>domain</parameter> or
+      <parameter>type</parameter> is given, <function>socket_create</function>
+      defaults to <constant>AF_INET</constant> and
+      <constant>SOCK_STREAM</constant> respectively and additionally emits an
+      <constant>E_WARNING</constant> message.
+     </para>
+    </note>
     <para>
      See also 
      <function>socket_accept</function>,
      <function>socket_bind</function>,
      <function>socket_connect</function>,
-     <function>socket_listen</function>, and
+     <function>socket_listen</function>,
+     <function>socket_last_error</function>, and
      <function>socket_strerror</function>.
     </para>
    </refsect1>