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>
