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>