mfischer Wed May 1 12:21:42 2002 EDT
Modified files:
/phpdoc/en/reference/sockets/functions socket-listen.xml
Log:
- Update docs.
Index: phpdoc/en/reference/sockets/functions/socket-listen.xml
diff -u phpdoc/en/reference/sockets/functions/socket-listen.xml:1.2
phpdoc/en/reference/sockets/functions/socket-listen.xml:1.3
--- phpdoc/en/reference/sockets/functions/socket-listen.xml:1.2 Wed Apr 17 02:44:09
2002
+++ phpdoc/en/reference/sockets/functions/socket-listen.xml Wed May 1 12:21:42
+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.1 -->
<refentry id="function.socket-listen">
<refnamediv>
@@ -9,35 +9,52 @@
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>int</type><methodname>socket_listen</methodname>
+ <type>bool</type><methodname>socket_listen</methodname>
<methodparam><type>resource</type><parameter>socket</parameter></methodparam>
- <methodparam><type>int</type><parameter>backlog</parameter></methodparam>
+ <methodparam
+choice="opt"><type>int</type><parameter>backlog</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
<para>
After the socket <parameter>socket</parameter> has been created
using <function>socket_create</function> and bound to a name with
<function>socket_bind</function>, it may be told to listen for incoming
- connections on <parameter>socket</parameter>. A maximum of
- <parameter>backlog</parameter> incoming connections will be
- queued for processing.
+ connections on <parameter>socket</parameter>.
</para>
<para>
- <function>socket_listen</function> is applicable only to sockets with
- type <literal>SOCK_STREAM</literal> or
- <literal>SOCK_SEQPACKET</literal>.
+ A maximum of <parameter>backlog</parameter> incoming connections will be
+ queued for processing. If a connection request arrives with the queue
+ full the client may receive an error with an indication of
+ <literal>ECONNREFUSED</literal>, or, if the underlying protocol supports
+ retransmission, the request may be ignored so that retries may succeed.
</para>
+ <note>
+ <para>
+ The maximum number passed to the <parameter>backlog</parameter>
+ parameter highly depends on the underlying platform. On linux, it is
+ silently truncated to <constant>SOMAXCONN</constant>. On win32, if
+ passed <constant>SOMAXCONN</constant>, the underlying service provider
+ responsible for the socket will set the backlog to a maximum
+ <emphasis>reasonable</emphasis> value. There is no standard provision to
+ find out the actual backlog value on this platform.
+ </para>
+ </note>
<para>
- Returns zero on success, or a negative error code on
- failure. This code may be passed to <function>socket_strerror</function>
- to get a textual explanation of the error.
+ <function>socket_listen</function> is applicable only to sockets of
+ type <constant>SOCK_STREAM</constant> or
+ <constant>SOCK_SEQPACKET</constant>.
</para>
<para>
- See also
+ &return.success; The error code can be retrieved with
+ <function>socket_last_error</function>. This code may be passed to
+ <function>socket_strerror</function> to get a textual explanation of the
+ error.
+ </para>
+ <para>
+ See also
<function>socket_accept</function>,
<function>socket_bind</function>,
<function>socket_connect</function>,
- <function>socket_create</function>, and
+ <function>socket_create</function> and
<function>socket_strerror</function>.
</para>
</refsect1>
