cvs: phpdoc /en/reference/sockets/functions socket-accept.xml socket-bind.xml socket-clear-error.xml socket-close.xml socket-connect.xml
socket-create-listen.xml socket-create-pair.xml socket-create.xml socket-get-option.xml socket-getpeername.xml socket-getsockname.xml
socket-last-error.xml socket-listen.xml socket-read.xml socket-recv.xml socket-recvfrom.xml socket-select.xml socket-send.xml socket-sendto.xml
socket-set-block.xml socket-set-nonblock.xml socket-set-option.xml socket-shutdown.xml socket-strerror.xml socket-write.xml

didou Fri Jun 15 00:12:30 2007 UTC Modified files: /phpdoc/en/reference/sockets/functions socket-accept.xml socket-bind.xml socket-clear-error.xml socket-close.xml socket-connect.xml socket-create-listen.xml socket-create-pair.xml socket-create.xml socket-get-option.xml socket-getpeername.xml socket-getsockname.xml socket-last-error.xml socket-listen.xml socket-read.xml socket-recv.xml socket-recvfrom.xml socket-select.xml socket-send.xml socket-sendto.xml socket-set-block.xml socket-set-nonblock.xml socket-set-option.xml socket-shutdown.xml socket-strerror.xml socket-write.xml Log: ref.sockets: new doc style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-accept.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-accept.xml diff -u phpdoc/en/reference/sockets/functions/socket-accept.xml:1.5 phpdoc/en/reference/sockets/functions/socket-accept.xml:1.6 --- phpdoc/en/reference/sockets/functions/socket-accept.xml:1.5 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-accept.xml Fri Jun 15 00:12:29 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.1 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.socket-accept"> <refnamediv> <refname>socket_accept</refname> <refpurpose>Accepts a connection on a socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>resource</type><methodname>socket_accept</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -34,6 +34,25 @@ <parameter>socket</parameter>, however, remains open and may be reused. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> Returns a new socket resource on success, or &false; on error. The actual error code can be retrieved by calling @@ -41,15 +60,21 @@ <function>socket_strerror</function> to get a textual explanation of the error. </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_bind</function>, - <function>socket_connect</function>, - <function>socket_listen</function>, - <function>socket_create</function>, and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_connect</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_create</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-bind.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-bind.xml diff -u phpdoc/en/reference/sockets/functions/socket-bind.xml:1.10 phpdoc/en/reference/sockets/functions/socket-bind.xml:1.11 --- phpdoc/en/reference/sockets/functions/socket-bind.xml:1.10 Sun Oct 2 14:49:52 2005 +++ phpdoc/en/reference/sockets/functions/socket-bind.xml Fri Jun 15 00:12:29 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.10 $ --> +<!-- $Revision: 1.11 $ --> <refentry id="function.socket-bind"> <refnamediv> <refname>socket_bind</refname> @@ -66,7 +66,9 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para>&return.success;</para> + <para> + &return.success; + </para> <para> 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 @@ -140,6 +142,7 @@ </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-clear-error.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-clear-error.xml diff -u phpdoc/en/reference/sockets/functions/socket-clear-error.xml:1.7 phpdoc/en/reference/sockets/functions/socket-clear-error.xml:1.8 --- phpdoc/en/reference/sockets/functions/socket-clear-error.xml:1.7 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-clear-error.xml Fri Jun 15 00:12:30 2007 @@ -1,12 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="function.socket-clear-error"> <refnamediv> <refname>socket_clear_error</refname> <refpurpose>Clears the error on the socket or the last error code</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>socket_clear_error</methodname> <methodparam choice="opt"><type>resource</type><parameter>socket</parameter></methodparam> @@ -20,12 +21,40 @@ a socket or of the extension global last error code. This may be useful to detect within a part of the application if an error occurred or not. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also - <function>socket_last_error</function> and - <function>socket_strerror</function>. + &return.void; </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-close.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-close.xml diff -u phpdoc/en/reference/sockets/functions/socket-close.xml:1.6 phpdoc/en/reference/sockets/functions/socket-close.xml:1.7 --- phpdoc/en/reference/sockets/functions/socket-close.xml:1.6 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-close.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.1 --> +<!-- $Revision: 1.7 $ --> <refentry id="function.socket-close"> <refnamediv> <refname>socket_close</refname> <refpurpose>Closes a socket resource</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>socket_close</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -16,21 +16,50 @@ <function>socket_close</function> closes the socket resource given by <parameter>socket</parameter>. </para> - <note> - <para> - <function>socket_close</function> can't be used on PHP file resources - created with <function>fopen</function>, <function>popen</function>, - <function>fsockopen</function>, or <function>pfsockopen</function>; it is - meant for sockets created with <function>socket_create</function> or - <function>socket_accept</function>. - </para> - </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <note> + <para> + <function>socket_close</function> can't be used on PHP file resources + created with <function>fopen</function>, <function>popen</function>, + <function>fsockopen</function>, or <function>pfsockopen</function>; + it is meant for sockets created with + <function>socket_create</function> or + <function>socket_accept</function>. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also <function>socket_bind</function>, <function>socket_listen</function>, - <function>socket_create</function> and - <function>socket_strerror</function>. + &return.void; </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>socket_bind</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_create</function></member> + <member><function>socket_strerror</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-connect.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-connect.xml diff -u phpdoc/en/reference/sockets/functions/socket-connect.xml:1.8 phpdoc/en/reference/sockets/functions/socket-connect.xml:1.9 --- phpdoc/en/reference/sockets/functions/socket-connect.xml:1.8 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-connect.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.1 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.socket-connect"> <refnamediv> <refname>socket_connect</refname> <refpurpose>Initiates a connection on a socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_connect</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -19,20 +19,47 @@ <parameter>socket</parameter>, which must be a valid socket resource created with <function>socket_create</function>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The <parameter>address</parameter> parameter is either an IP - address in dotted-quad notation - (e.g. <literal>127.0.0.1</literal>), if the socket is of the - <constant>AF_INET</constant> family; or the pathname of a - Unix domain socket, if the socket family is - <constant>AF_UNIX</constant>. - </para> - <para> - The <parameter>port</parameter> parameter is only used when - connecting to an <constant>AF_INET</constant> socket, and - designates the port on the remote host to which a connection - should be made. + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>address</parameter></term> + <listitem> + <para> + The <parameter>address</parameter> parameter is either an IP address + in dotted-quad notation (e.g. <literal>127.0.0.1</literal>), if the + socket is of the <constant>AF_INET</constant> family; or the pathname + of a Unix domain socket, if the socket family is + <constant>AF_UNIX</constant>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + The <parameter>port</parameter> parameter is only used when connecting + to an <constant>AF_INET</constant> socket, and designates the port on + the remote host to which a connection should be made. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> &return.success; The error code can be retrieved with <function>socket_last_error</function>. This code may be passed to @@ -45,15 +72,21 @@ error <literal>Operation now in progress</literal>. </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_bind</function>, - <function>socket_listen</function>, - <function>socket_create</function>, - <function>socket_last_error</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_bind</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_create</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-create-listen.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-create-listen.xml diff -u phpdoc/en/reference/sockets/functions/socket-create-listen.xml:1.6 phpdoc/en/reference/sockets/functions/socket-create-listen.xml:1.7 --- phpdoc/en/reference/sockets/functions/socket-create-listen.xml:1.6 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-create-listen.xml Fri Jun 15 00:12:30 2007 @@ -1,34 +1,58 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.7 $ --> <refentry id="function.socket-create-listen"> <refnamediv> <refname>socket_create_listen</refname> <refpurpose>Opens a socket on port to accept connections </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>resource</type><methodname>socket_create_listen</methodname> <methodparam><type>int</type><parameter>port</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>backlog</parameter></methodparam> </methodsynopsis> <para> - This function is meant to ease the task of creating a new socket which - only listens to accept new connections. - </para> - <para> <function>socket_create_listen</function> creates a new socket resource of type <constant>AF_INET</constant> listening on <emphasis>all</emphasis> local interfaces on the given port waiting for new connections. </para> <para> - The <parameter>backlog</parameter> parameter defines the maximum length - the queue of pending connections may grow to. - <constant>SOMAXCONN</constant> may be passed as - <parameter>backlog</parameter> parameter, see - <function>socket_listen</function> for more information. + This function is meant to ease the task of creating a new socket which + only listens to accept new connections. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>backlog</parameter></term> + <listitem> + <para> + The <parameter>backlog</parameter> parameter defines the maximum length + the queue of pending connections may grow to. + <constant>SOMAXCONN</constant> may be passed as + <parameter>backlog</parameter> parameter, see + <function>socket_listen</function> for more information. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> <function>socket_create_listen</function> returns a new socket resource on success or &false; on error. The error code can be retrieved with @@ -36,6 +60,10 @@ <function>socket_strerror</function> to get a textual explanation of the error. </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> If you want to create a socket which only listens on a certain @@ -43,15 +71,21 @@ <function>socket_bind</function> and <function>socket_listen</function>. </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_create</function>, - <function>socket_bind</function>, - <function>socket_listen</function>, - <function>socket_last_error</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_create</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-create-pair.xml?r1=1.14&r2=1.15&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-create-pair.xml diff -u phpdoc/en/reference/sockets/functions/socket-create-pair.xml:1.14 phpdoc/en/reference/sockets/functions/socket-create-pair.xml:1.15 --- phpdoc/en/reference/sockets/functions/socket-create-pair.xml:1.14 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-create-pair.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.14 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.15 $ --> <refentry id="function.socket-create-pair"> <refnamediv> <refname>socket_create_pair</refname> <refpurpose>Creates a pair of indistinguishable sockets and stores them in an array</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_create_pair</methodname> <methodparam><type>int</type><parameter>domain</parameter></methodparam> @@ -16,156 +16,198 @@ <methodparam><type>array</type><parameter role="reference">fd</parameter></methodparam> </methodsynopsis> <para> - <function>socket_create_pair</function> creates two connected and indistinguishable sockets, and stores - them in <parameter>fd</parameter>. This function is commonly used in IPC (InterProcess Communication). + <function>socket_create_pair</function> creates two connected and + indistinguishable sockets, and stores them in <parameter>fd</parameter>. + This function is commonly used in IPC (InterProcess Communication). </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The <parameter>domain</parameter> parameter specifies the protocol - family to be used by the socket. - </para> - <table> - <title>Available address/protocol families</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Domain</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>AF_INET</entry> - <entry> - IPv4 Internet based protocols. TCP and UDP are common protocols of - this protocol family. Supported only in windows. - </entry> - </row> - <row> - <entry>AF_INET6</entry> - <entry> - IPv6 Internet based protocols. TCP and UDP are common protocols of - this protocol family. Support added in PHP 5.0.0. - Supported only in windows. - </entry> - </row> - <row> - <entry>AF_UNIX</entry> - <entry> - Local communication protocol family. High efficiency and low - overhead make it a great form of IPC (Interprocess Communication). - </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - The <parameter>type</parameter> parameter selects the type of communication - to be used by the socket. + <variablelist> + <varlistentry> + <term><parameter>domain</parameter></term> + <listitem> + <para> + The <parameter>domain</parameter> parameter specifies the protocol + family to be used by the socket. + </para> + <table> + <title>Available address/protocol families</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Domain</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>AF_INET</entry> + <entry> + IPv4 Internet based protocols. TCP and UDP are common protocols of + this protocol family. Supported only in windows. + </entry> + </row> + <row> + <entry>AF_INET6</entry> + <entry> + IPv6 Internet based protocols. TCP and UDP are common protocols of + this protocol family. Support added in PHP 5.0.0. + Supported only in windows. + </entry> + </row> + <row> + <entry>AF_UNIX</entry> + <entry> + Local communication protocol family. High efficiency and low + overhead make it a great form of IPC (Interprocess Communication). + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem> + <para> + The <parameter>type</parameter> parameter selects the type of communication + to be used by the socket. + </para> + <table> + <title>Available socket types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>SOCK_STREAM</entry> + <entry> + Provides sequenced, reliable, full-duplex, connection-based byte streams. + An out-of-band data transmission mechanism may be supported. + The TCP protocol is based on this socket type. + </entry> + </row> + <row> + <entry>SOCK_DGRAM</entry> + <entry> + Supports datagrams (connectionless, unreliable messages of a fixed maximum length). + The UDP protocol is based on this socket type. + </entry> + </row> + <row> + <entry>SOCK_SEQPACKET</entry> + <entry> + Provides a sequenced, reliable, two-way connection-based data transmission path for + datagrams of fixed maximum length; a consumer is required to read an + entire packet with each read call. + </entry> + </row> + <row> + <entry>SOCK_RAW</entry> + <entry> + Provides raw network protocol access. This special type of socket + can be used to manually construct any type of protocol. A common use + for this socket type is to perform ICMP requests (like ping, + traceroute, etc). + </entry> + </row> + <row> + <entry>SOCK_RDM</entry> + <entry> + Provides a reliable datagram layer that does not guarantee ordering. + This is most likely not implemented on your operating system. + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>protocol</parameter></term> + <listitem> + <para> + The <parameter>protocol</parameter> parameter sets the specific + protocol within the specified <parameter>domain</parameter> to be used + when communicating on the returned socket. The proper value can be retrieved by + name by using <function>getprotobyname</function>. If + the desired protocol is TCP, or UDP the corresponding constants + <constant>SOL_TCP</constant>, and <constant>SOL_UDP</constant> + can also be used. + </para> + <table> + <title>Common protocols</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>icmp</entry> + <entry> + The Internet Control Message Protocol is used primarily by gateways + and hosts to report errors in datagram communication. The "ping" + command (present in most modern operating systems) is an example + application of ICMP. + </entry> + </row> + <row> + <entry>udp</entry> + <entry> + The User Datagram Protocol is a connectionless, unreliable, + protocol with fixed record lengths. Due to these aspects, UDP + requires a minimum amount of protocol overhead. + </entry> + </row> + <row> + <entry>tcp</entry> + <entry> + The Transmission Control Protocol is a reliable, connection based, + stream oriented, full duplex protocol. TCP guarantees that all data packets + will be received in the order in which they were sent. If any packet is somehow + lost during communication, TCP will automatically retransmit the packet until + the destination host acknowledges that packet. For reliability and performance + reasons, the TCP implementation itself decides the appropriate octet boundaries + of the underlying datagram communication layer. Therefore, TCP applications must + allow for the possibility of partial record transmission. + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> </para> - <table> - <title>Available socket types</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>SOCK_STREAM</entry> - <entry> - Provides sequenced, reliable, full-duplex, connection-based byte streams. - An out-of-band data transmission mechanism may be supported. - The TCP protocol is based on this socket type. - </entry> - </row> - <row> - <entry>SOCK_DGRAM</entry> - <entry> - Supports datagrams (connectionless, unreliable messages of a fixed maximum length). - The UDP protocol is based on this socket type. - </entry> - </row> - <row> - <entry>SOCK_SEQPACKET</entry> - <entry> - Provides a sequenced, reliable, two-way connection-based data transmission path for - datagrams of fixed maximum length; a consumer is required to read an - entire packet with each read call. - </entry> - </row> - <row> - <entry>SOCK_RAW</entry> - <entry> - Provides raw network protocol access. This special type of socket - can be used to manually construct any type of protocol. A common use - for this socket type is to perform ICMP requests (like ping, - traceroute, etc). - </entry> - </row> - <row> - <entry>SOCK_RDM</entry> - <entry> - Provides a reliable datagram layer that does not guarantee ordering. - This is most likely not implemented on your operating system. - </entry> - </row> - </tbody> - </tgroup> - </table> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - The <parameter>protocol</parameter> parameter sets the specific - protocol within the specified <parameter>domain</parameter> to be used - when communicating on the returned socket. The proper value can be retrieved by - name by using <function>getprotobyname</function>. If - the desired protocol is TCP, or UDP the corresponding constants - <constant>SOL_TCP</constant>, and <constant>SOL_UDP</constant> - can also be used. + &return.success; </para> - <table> - <title>Common protocols</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>icmp</entry> - <entry> - The Internet Control Message Protocol is used primarily by gateways - and hosts to report errors in datagram communication. The "ping" - command (present in most modern operating systems) is an example - application of ICMP. - </entry> - </row> - <row> - <entry>udp</entry> - <entry> - The User Datagram Protocol is a connectionless, unreliable, - protocol with fixed record lengths. Due to these aspects, UDP - requires a minimum amount of protocol overhead. - </entry> - </row> - <row> - <entry>tcp</entry> - <entry> - The Transmission Control Protocol is a reliable, connection based, - stream oriented, full duplex protocol. TCP guarantees that all data packets - will be received in the order in which they were sent. If any packet is somehow - lost during communication, TCP will automatically retransmit the packet until - the destination host acknowledges that packet. For reliability and performance - reasons, the TCP implementation itself decides the appropriate octet boundaries - of the underlying datagram communication layer. Therefore, TCP applications must - allow for the possibility of partial record transmission. - </entry> - </row> - </tbody> - </tgroup> - </table> + </refsect1> + + <refesct1 role="examples"> + &reftitle.examples; <para> <example> <title><function>socket_create_pair</function> example</title> @@ -236,6 +278,7 @@ </example> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-create.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-create.xml diff -u phpdoc/en/reference/sockets/functions/socket-create.xml:1.8 phpdoc/en/reference/sockets/functions/socket-create.xml:1.9 --- phpdoc/en/reference/sockets/functions/socket-create.xml:1.8 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-create.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.4 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.socket-create"> <refnamediv> <refname>socket_create</refname> <refpurpose>Create a socket (endpoint for communication)</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>resource</type><methodname>socket_create</methodname> <methodparam><type>int</type><parameter>domain</parameter></methodparam> @@ -19,159 +19,192 @@ of communication. A typical network connection is made up of 2 sockets, one performing the role of the client, and another performing the role of the server. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The <parameter>domain</parameter> parameter specifies the protocol - family to be used by the socket. - </para> - <table> - <title>Available address/protocol families</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Domain</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>AF_INET</entry> - <entry> - IPv4 Internet based protocols. TCP and UDP are common protocols of - this protocol family. - </entry> - </row> - <row> - <entry>AF_INET6</entry> - <entry> - IPv6 Internet based protocols. TCP and UDP are common protocols of - this protocol family. Support added in PHP 5.0.0. - </entry> - </row> - <row> - <entry>AF_UNIX</entry> - <entry> - Local communication protocol family. High efficiency and low - overhead make it a great form of IPC (Interprocess Communication). - </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - The <parameter>type</parameter> parameter selects the type of communication - to be used by the socket. - </para> - <table> - <title>Available socket types</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>SOCK_STREAM</entry> - <entry> - Provides sequenced, reliable, full-duplex, connection-based byte streams. - An out-of-band data transmission mechanism may be supported. - The TCP protocol is based on this socket type. - </entry> - </row> - <row> - <entry>SOCK_DGRAM</entry> - <entry> - Supports datagrams (connectionless, unreliable messages of a fixed maximum length). - The UDP protocol is based on this socket type. - </entry> - </row> - <row> - <entry>SOCK_SEQPACKET</entry> - <entry> - Provides a sequenced, reliable, two-way connection-based data transmission path for - datagrams of fixed maximum length; a consumer is required to read an - entire packet with each read call. - </entry> - </row> - <row> - <entry>SOCK_RAW</entry> - <entry> - Provides raw network protocol access. This special type of socket - can be used to manually construct any type of protocol. A common use - for this socket type is to perform ICMP requests (like ping, - traceroute, etc). - </entry> - </row> - <row> - <entry>SOCK_RDM</entry> - <entry> - Provides a reliable datagram layer that does not guarantee ordering. - This is most likely not implemented on your operating system. - </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - The <parameter>protocol</parameter> parameter sets the specific - protocol within the specified <parameter>domain</parameter> to be used - when communicating on the returned socket. The proper value can be retrieved by - name by using <function>getprotobyname</function>. If - the desired protocol is TCP, or UDP the corresponding constants - <constant>SOL_TCP</constant>, and <constant>SOL_UDP</constant> - can also be used. + <variablelist> + <varlistentry> + <term><parameter>domain</parameter></term> + <listitem> + <para> + The <parameter>domain</parameter> parameter specifies the protocol + family to be used by the socket. + </para> + <table> + <title>Available address/protocol families</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Domain</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>AF_INET</entry> + <entry> + IPv4 Internet based protocols. TCP and UDP are common protocols of + this protocol family. + </entry> + </row> + <row> + <entry>AF_INET6</entry> + <entry> + IPv6 Internet based protocols. TCP and UDP are common protocols of + this protocol family. Support added in PHP 5.0.0. + </entry> + </row> + <row> + <entry>AF_UNIX</entry> + <entry> + Local communication protocol family. High efficiency and low + overhead make it a great form of IPC (Interprocess Communication). + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem> + <para> + The <parameter>type</parameter> parameter selects the type of communication + to be used by the socket. + </para> + <table> + <title>Available socket types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>SOCK_STREAM</entry> + <entry> + Provides sequenced, reliable, full-duplex, connection-based byte streams. + An out-of-band data transmission mechanism may be supported. + The TCP protocol is based on this socket type. + </entry> + </row> + <row> + <entry>SOCK_DGRAM</entry> + <entry> + Supports datagrams (connectionless, unreliable messages of a fixed maximum length). + The UDP protocol is based on this socket type. + </entry> + </row> + <row> + <entry>SOCK_SEQPACKET</entry> + <entry> + Provides a sequenced, reliable, two-way connection-based data transmission path for + datagrams of fixed maximum length; a consumer is required to read an + entire packet with each read call. + </entry> + </row> + <row> + <entry>SOCK_RAW</entry> + <entry> + Provides raw network protocol access. This special type of socket + can be used to manually construct any type of protocol. A common use + for this socket type is to perform ICMP requests (like ping, + traceroute, etc). + </entry> + </row> + <row> + <entry>SOCK_RDM</entry> + <entry> + Provides a reliable datagram layer that does not guarantee ordering. + This is most likely not implemented on your operating system. + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>protocol</parameter></term> + <listitem> + <para> + The <parameter>protocol</parameter> parameter sets the specific + protocol within the specified <parameter>domain</parameter> to be used + when communicating on the returned socket. The proper value can be + retrieved by name by using <function>getprotobyname</function>. If + the desired protocol is TCP, or UDP the corresponding constants + <constant>SOL_TCP</constant>, and <constant>SOL_UDP</constant> + can also be used. + </para> + <table> + <title>Common protocols</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>icmp</entry> + <entry> + The Internet Control Message Protocol is used primarily by gateways + and hosts to report errors in datagram communication. The "ping" + command (present in most modern operating systems) is an example + application of ICMP. + </entry> + </row> + <row> + <entry>udp</entry> + <entry> + The User Datagram Protocol is a connectionless, unreliable, + protocol with fixed record lengths. Due to these aspects, UDP + requires a minimum amount of protocol overhead. + </entry> + </row> + <row> + <entry>tcp</entry> + <entry> + The Transmission Control Protocol is a reliable, connection based, + stream oriented, full duplex protocol. TCP guarantees that all data packets + will be received in the order in which they were sent. If any packet is somehow + lost during communication, TCP will automatically retransmit the packet until + the destination host acknowledges that packet. For reliability and performance + reasons, the TCP implementation itself decides the appropriate octet boundaries + of the underlying datagram communication layer. Therefore, TCP applications must + allow for the possibility of partial record transmission. + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + </variablelist> </para> - <table> - <title>Common protocols</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>icmp</entry> - <entry> - The Internet Control Message Protocol is used primarily by gateways - and hosts to report errors in datagram communication. The "ping" - command (present in most modern operating systems) is an example - application of ICMP. - </entry> - </row> - <row> - <entry>udp</entry> - <entry> - The User Datagram Protocol is a connectionless, unreliable, - protocol with fixed record lengths. Due to these aspects, UDP - requires a minimum amount of protocol overhead. - </entry> - </row> - <row> - <entry>tcp</entry> - <entry> - The Transmission Control Protocol is a reliable, connection based, - stream oriented, full duplex protocol. TCP guarantees that all data packets - will be received in the order in which they were sent. If any packet is somehow - lost during communication, TCP will automatically retransmit the packet until - the destination host acknowledges that packet. For reliability and performance - reasons, the TCP implementation itself decides the appropriate octet boundaries - of the underlying datagram communication layer. Therefore, TCP applications must - allow for the possibility of partial record transmission. - </entry> - </row> - </tbody> - </tgroup> - </table> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - <function>socket_create</function> 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. + <function>socket_create</function> 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> + </refsect1> <note> + + </note> + <refsect1 role="errors"> + &reftitle.errors; <para> If an invalid <parameter>domain</parameter> or <parameter>type</parameter> is given, <function>socket_create</function> @@ -179,17 +212,22 @@ <constant>SOCK_STREAM</constant> respectively and additionally emits an <constant>E_WARNING</constant> message. </para> - </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_accept</function>, - <function>socket_bind</function>, - <function>socket_connect</function>, - <function>socket_listen</function>, - <function>socket_last_error</function>, and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_accept</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_connect</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-get-option.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-get-option.xml diff -u phpdoc/en/reference/sockets/functions/socket-get-option.xml:1.8 phpdoc/en/reference/sockets/functions/socket-get-option.xml:1.9 --- phpdoc/en/reference/sockets/functions/socket-get-option.xml:1.8 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-get-option.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.socket-get-option"> <refnamediv> <refname>socket_get_option</refname> <refpurpose>Gets socket options for the socket </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</type><methodname>socket_get_option</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -17,137 +17,189 @@ <para> The <function>socket_get_option</function> function retrieves the value for the option specified by the <parameter>optname</parameter> parameter for the - socket specified by the <parameter>socket</parameter> parameter. <function>socket_get_option</function> - will return &false; on failure. + specified <parameter>socket</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>level</parameter></term> + <listitem> + <para> + The <parameter>level</parameter> parameter specifies the protocol + level at which the option resides. For example, to retrieve options at + the socket level, a <parameter>level</parameter> parameter of + SOL_SOCKET would be used. Other levels, such as TCP, can be used by + specifying the protocol number of that level. Protocol numbers can be + found by using the <function>getprotobyname</function> function. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>optname</parameter></term> + <listitem> + <table> + <title>Available Socket Options</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>SO_DEBUG</entry> + <entry> + Reports whether debugging information is being recorded. + </entry> + </row> + <row> + <entry>SO_ACCEPTCONN</entry> + <entry> + Reports whether socket listening is enabled. + </entry> + </row> + <row> + <entry>SO_BROADCAST</entry> + <entry> + Reports whether transmission of broadcast messages is supported. + </entry> + </row> + <row> + <entry>SO_REUSEADDR</entry> + <entry> + Reports whether local addresses can be reused. + </entry> + </row> + <row> + <entry>SO_KEEPALIVE</entry> + <entry> + Reports whether connections are kept active with periodic transmission + of messages. If the connected socket fails to respond to these messages, + the connection is broken and processes writing to that socket are notified + with a SIGPIPE signal. + </entry> + </row> + <row> + <entry>SO_LINGER</entry> + <entry> + Reports whether the <parameter>socket</parameter> lingers on <function>socket_close</function> if data is present. + </entry> + </row> + <row> + <entry>SO_OOBINLINE</entry> + <entry> + Reports whether the <parameter>socket</parameter> leaves out-of-band data inline. + </entry> + </row> + <row> + <entry>SO_SNDBUF</entry> + <entry> + Reports send buffer size information. + </entry> + </row> + <row> + <entry>SO_RCVBUF</entry> + <entry> + Reports recieve buffer size information. + </entry> + </row> + <row> + <entry>SO_ERROR</entry> + <entry> + Reports information about error status and clears it. + </entry> + </row> + <row> + <entry>SO_TYPE</entry> + <entry> + Reports the <parameter>socket</parameter> type. + </entry> + </row> + <row> + <entry>SO_DONTROUTE</entry> + <entry> + Reports whether outgoing messages bypass the standard routing facilities. + </entry> + </row> + <row> + <entry>SO_RCVLOWAT</entry> + <entry> + Reports the minimum number of bytes to process for <parameter>socket</parameter> input operations. + ( Defaults to 1 ) + </entry> + </row> + <row> + <entry>SO_RCVTIMEO</entry> + <entry> + Reports the timeout value for input operations. + </entry> + </row> + <row> + <entry>SO_SNDLOWAT</entry> + <entry> + Reports the minimum number of bytes to process for <parameter>socket</parameter> output operations. + </entry> + </row> + <row> + <entry>SO_SNDTIMEO</entry> + <entry> + Reports the timeout value specifying the amount of time that an output + function blocks because flow control prevents data from being sent. + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - The <parameter>level</parameter> parameter specifies the protocol level at - which the option resides. For example, to retrieve options at the socket level, - a <parameter>level</parameter> parameter of SOL_SOCKET would be used. Other - levels, such as TCP, can be used by specifying the protocol number of that level. - Protocol numbers can be found by using the <function>getprotobyname</function> function. + Returns the value of the given option, or &false; on errors. </para> - <table> - <title>Available Socket Options</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Option</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>SO_DEBUG</entry> - <entry> - Reports whether debugging information is being recorded. - </entry> - </row> - <row> - <entry>SO_ACCEPTCONN</entry> - <entry> - Reports whether socket listening is enabled. - </entry> - </row> - <row> - <entry>SO_BROADCAST</entry> - <entry> - Reports whether transmission of broadcast messages is supported. - </entry> - </row> - <row> - <entry>SO_REUSEADDR</entry> - <entry> - Reports whether local addresses can be reused. - </entry> - </row> - <row> - <entry>SO_KEEPALIVE</entry> - <entry> - Reports whether connections are kept active with periodic transmission - of messages. If the connected socket fails to respond to these messages, - the connection is broken and processes writing to that socket are notified - with a SIGPIPE signal. - </entry> - </row> - <row> - <entry>SO_LINGER</entry> - <entry> - Reports whether the <parameter>socket</parameter> lingers on <function>socket_close</function> if data is present. - </entry> - </row> - <row> - <entry>SO_OOBINLINE</entry> - <entry> - Reports whether the <parameter>socket</parameter> leaves out-of-band data inline. - </entry> - </row> - <row> - <entry>SO_SNDBUF</entry> - <entry> - Reports send buffer size information. - </entry> - </row> - <row> - <entry>SO_RCVBUF</entry> - <entry> - Reports recieve buffer size information. - </entry> - </row> - <row> - <entry>SO_ERROR</entry> - <entry> - Reports information about error status and clears it. - </entry> - </row> - <row> - <entry>SO_TYPE</entry> - <entry> - Reports the <parameter>socket</parameter> type. - </entry> - </row> - <row> - <entry>SO_DONTROUTE</entry> - <entry> - Reports whether outgoing messages bypass the standard routing facilities. - </entry> - </row> - <row> - <entry>SO_RCVLOWAT</entry> - <entry> - Reports the minimum number of bytes to process for <parameter>socket</parameter> input operations. - ( Defaults to 1 ) - </entry> - </row> - <row> - <entry>SO_RCVTIMEO</entry> - <entry> - Reports the timeout value for input operations. - </entry> - </row> - <row> - <entry>SO_SNDLOWAT</entry> - <entry> - Reports the minimum number of bytes to process for <parameter>socket</parameter> output operations. - </entry> - </row> - <row> - <entry>SO_SNDTIMEO</entry> - <entry> - Reports the timeout value specifying the amount of time that an output - function blocks because flow control prevents data from being sent. - </entry> - </row> - </tbody> - </tgroup> - </table> - <note> - <para> - This function used to be called <literal>socket_getopt()</literal> prior - to PHP 4.3.0 - </para> - </note> </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + The name of this function was changed. It used to be called + <literal>socket_getopt()</literal>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-getpeername.xml?r1=1.11&r2=1.12&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-getpeername.xml diff -u phpdoc/en/reference/sockets/functions/socket-getpeername.xml:1.11 phpdoc/en/reference/sockets/functions/socket-getpeername.xml:1.12 --- phpdoc/en/reference/sockets/functions/socket-getpeername.xml:1.11 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-getpeername.xml Fri Jun 15 00:12:30 2007 @@ -1,55 +1,103 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.11 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.12 $ --> <refentry id="function.socket-getpeername"> <refnamediv> <refname>socket_getpeername</refname> <refpurpose>Queries the remote side of the given socket which may either result in host/port or in a Unix filesystem path, dependent on its type</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_getpeername</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> - <methodparam><type>string</type><parameter role="reference">addr</parameter></methodparam> + <methodparam><type>string</type><parameter role="reference">address</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter role="reference">port</parameter></methodparam> </methodsynopsis> <para> - If the given socket is of type <constant>AF_INET</constant> - or <constant>AF_INET6</constant>, <function>socket_getpeername</function> - will return the peers (remote) <emphasis>IP address</emphasis> in appropriate notation (e.g. - <literal>127.0.0.1</literal> or <literal>fe80::1</literal>) in the - <parameter>address</parameter> parameter and, if the optional - <parameter>port</parameter> parameter is present, also the associated port. + Queries the remote side of the given socket which may either result in + host/port or in a Unix filesystem path, dependent on its type. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If the given socket is of type <constant>AF_UNIX</constant>, - <function>socket_getpeername</function> will return the Unix filesystem - path (e.g. <literal>/var/run/daemon.sock</literal>) in the - <parameter>address</parameter> parameter. + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>address</parameter></term> + <listitem> + <para> + If the given socket is of type <constant>AF_INET</constant> or + <constant>AF_INET6</constant>, <function>socket_getpeername</function> + will return the peers (remote) <emphasis>IP address</emphasis> in + appropriate notation (e.g. <literal>127.0.0.1</literal> or + <literal>fe80::1</literal>) in the <parameter>address</parameter> + parameter and, if the optional <parameter>port</parameter> parameter is + present, also the associated port. + </para> + <para> + If the given socket is of type <constant>AF_UNIX</constant>, + <function>socket_getpeername</function> will return the Unix filesystem + path (e.g. <literal>/var/run/daemon.sock</literal>) in the + <parameter>address</parameter> parameter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + If given, this will hold the port associated to + <parameter>address</parameter>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; <function>socket_getpeername</function> may also return + &false; if the socket type is not any of <constant>AF_INET</constant>, + <constant>AF_INET6</constant>, or <constant>AF_UNIX</constant>, in which + case the last socket error code is <emphasis>not</emphasis> updated. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <simpara> + <para> <function>socket_getpeername</function> should not be used with <constant>AF_UNIX</constant> sockets created with <function>socket_accept</function>. Only sockets created with <function>socket_connect</function> or a primary server socket following a call to <function>socket_bind</function> will return meaningful values. - </simpara> + </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - &return.success; <function>socket_getpeername</function> may also return - &false; if the socket type is not any of <constant>AF_INET</constant>, - <constant>AF_INET6</constant>, or <constant>AF_UNIX</constant>, in which - case the last socket error code is <emphasis>not</emphasis> updated. - </para> - <para> - See also - <function>socket_getsockname</function>, - <function>socket_last_error</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_getsockname</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-getsockname.xml?r1=1.9&r2=1.10&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-getsockname.xml diff -u phpdoc/en/reference/sockets/functions/socket-getsockname.xml:1.9 phpdoc/en/reference/sockets/functions/socket-getsockname.xml:1.10 --- phpdoc/en/reference/sockets/functions/socket-getsockname.xml:1.9 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-getsockname.xml Fri Jun 15 00:12:30 2007 @@ -1,33 +1,19 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.10 $ --> <refentry id="function.socket-getsockname"> <refnamediv> <refname>socket_getsockname</refname> <refpurpose>Queries the local side of the given socket which may either result in host/port or in a Unix filesystem path, dependent on its type</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_getsockname</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> <methodparam><type>string</type><parameter role="reference">addr</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter role="reference">port</parameter></methodparam> </methodsynopsis> - <para> - If the given socket is of type <constant>AF_INET</constant> - or <constant>AF_INET6</constant>, <function>socket_getsockname</function> - will return the local <emphasis>IP address</emphasis> in appropriate notation (e.g. - <literal>127.0.0.1</literal> or <literal>fe80::1</literal>) in the - <parameter>address</parameter> parameter and, if the optional - <parameter>port</parameter> parameter is present, also the associated port. - </para> - <para> - If the given socket is of type <constant>AF_UNIX</constant>, - <function>socket_getsockname</function> will return the Unix filesystem - path (e.g. <literal>/var/run/daemon.sock</literal>) in the - <parameter>address</parameter> parameter. - </para> <note> <simpara> <function>socket_getsockname</function> should not be used with @@ -37,19 +23,71 @@ meaningful values. </simpara> </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>addr</parameter></term> + <listitem> + <para> + If the given socket is of type <constant>AF_INET</constant> + or <constant>AF_INET6</constant>, <function>socket_getsockname</function> + will return the local <emphasis>IP address</emphasis> in appropriate notation (e.g. + <literal>127.0.0.1</literal> or <literal>fe80::1</literal>) in the + <parameter>address</parameter> parameter and, if the optional + <parameter>port</parameter> parameter is present, also the associated port. + </para> + <para> + If the given socket is of type <constant>AF_UNIX</constant>, + <function>socket_getsockname</function> will return the Unix filesystem + path (e.g. <literal>/var/run/daemon.sock</literal>) in the + <parameter>address</parameter> parameter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + If provided, this will hold the associated port. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> &return.success; <function>socket_getsockname</function> may also return &false; if the socket type is not any of <constant>AF_INET</constant>, <constant>AF_INET6</constant>, or <constant>AF_UNIX</constant>, in which case the last socket error code is <emphasis>not</emphasis> updated. </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_getpeername</function>, - <function>socket_last_error</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_getpeername</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-last-error.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-last-error.xml diff -u phpdoc/en/reference/sockets/functions/socket-last-error.xml:1.8 phpdoc/en/reference/sockets/functions/socket-last-error.xml:1.9 --- phpdoc/en/reference/sockets/functions/socket-last-error.xml:1.8 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-last-error.xml Fri Jun 15 00:12:30 2007 @@ -1,21 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.1 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.socket-last-error"> <refnamediv> <refname>socket_last_error</refname> <refpurpose>Returns the last error on the socket </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_last_error</methodname> <methodparam choice="opt"><type>resource</type><parameter>socket</parameter></methodparam> </methodsynopsis> <para> - This function returns a socket error code. - </para> - <para> If a socket resource is passed to this function, the last error which occurred on this particular socket is returned. If the socket resource is omitted, the error code of the last failed socket function is returned. @@ -36,6 +33,32 @@ ]]> </programlisting> </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + This function returns a socket error code. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> <function>socket_last_error</function> does not clear the error code, use @@ -43,6 +66,7 @@ </para> </note> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-listen.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-listen.xml diff -u phpdoc/en/reference/sockets/functions/socket-listen.xml:1.6 phpdoc/en/reference/sockets/functions/socket-listen.xml:1.7 --- phpdoc/en/reference/sockets/functions/socket-listen.xml:1.6 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-listen.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.1 --> +<!-- $Revision: 1.7 $ --> <refentry id="function.socket-listen"> <refnamediv> <refname>socket_listen</refname> <refpurpose>Listens for a connection on a socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_listen</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -20,43 +20,73 @@ connections on <parameter>socket</parameter>. </para> <para> - 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> <function>socket_listen</function> is applicable only to sockets of type <constant>SOCK_STREAM</constant> or <constant>SOCK_SEQPACKET</constant>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>backlog</parameter></term> + <listitem> + <para> + 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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> &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> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_accept</function>, - <function>socket_bind</function>, - <function>socket_connect</function>, - <function>socket_create</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_accept</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_connect</function></member> + <member><function>socket_create</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-read.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-read.xml diff -u phpdoc/en/reference/sockets/functions/socket-read.xml:1.7 phpdoc/en/reference/sockets/functions/socket-read.xml:1.8 --- phpdoc/en/reference/sockets/functions/socket-read.xml:1.7 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-read.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.8 --> +<!-- $Revision: 1.8 $ --> <refentry id="function.socket-read"> <refnamediv> <refname>socket_read</refname> <refpurpose>Reads a maximum of length bytes from a socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>socket_read</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -18,14 +18,62 @@ The function <function>socket_read</function> reads from the socket resource <parameter>socket</parameter> created by the <function>socket_create</function> or - <function>socket_accept</function> functions. The maximum number of bytes read - is specified by the <parameter>length</parameter> parameter. Otherwise - you can use \r, \n, or \0 to end reading - (depending on the <parameter>type</parameter> parameter, see below). + <function>socket_accept</function> functions. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + The maximum number of bytes read is specified by the + <parameter>length</parameter> parameter. Otherwise you can use \r, \n, + or \0 to end reading (depending on the <parameter>type</parameter> + parameter, see below). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem> + <para> + Optional <parameter>type</parameter> parameter is a named constant: + <itemizedlist> + <listitem> + <simpara> + <constant>PHP_BINARY_READ</constant> (Default) - use the system + <literal>recv()</literal> function. Safe for reading binary data. + </simpara> + </listitem> + <listitem> + <simpara> + <constant>PHP_NORMAL_READ</constant> - reading stops at \n or \r. + </simpara> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - <function>socket_read</function> returns the data as a string on success, or - &false; on error (including if the remote host has closed the + <function>socket_read</function> returns the data as a string on success, + or &false; on error (including if the remote host has closed the connection). 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 representation of @@ -37,33 +85,49 @@ when there is no more data to read. </para> </note> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; <para> - Optional <parameter>type</parameter> parameter is a named constant: - <itemizedlist> - <listitem> - <simpara> - PHP_BINARY_READ - use the system <literal>recv()</literal> function. - Safe for reading binary data. (Default in PHP &gt;= 4.1.0) - </simpara> - </listitem> - <listitem> - <simpara> - PHP_NORMAL_READ - reading stops at \n or \r. (Default in PHP &lt;= 4.0.6) - </simpara> - </listitem> - </itemizedlist> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.1.0</entry> + <entry> + The default value for <parameter>type</parameter> was changed from + <constant>PHP_NORMAL_READ</constant> to + <constant>PHP_BINARY_READ</constant> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_accept</function>, - <function>socket_bind</function>, - <function>socket_connect</function>, - <function>socket_listen</function>, - <function>socket_last_error</function>, - <function>socket_strerror</function> and - <function>socket_write</function>. + <simplelist> + <member><function>socket_accept</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_connect</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + <member><function>socket_write</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-recv.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-recv.xml diff -u phpdoc/en/reference/sockets/functions/socket-recv.xml:1.7 phpdoc/en/reference/sockets/functions/socket-recv.xml:1.8 --- phpdoc/en/reference/sockets/functions/socket-recv.xml:1.7 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-recv.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.8 $ --> <refentry id="function.socket-recv"> <refnamediv> <refname>socket_recv</refname> <refpurpose>Receives data from a connected socket </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_recv</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -19,6 +19,7 @@ &warn.undocumented.func; </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-recvfrom.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-recvfrom.xml diff -u phpdoc/en/reference/sockets/functions/socket-recvfrom.xml:1.8 phpdoc/en/reference/sockets/functions/socket-recvfrom.xml:1.9 --- phpdoc/en/reference/sockets/functions/socket-recvfrom.xml:1.8 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-recvfrom.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.socket-recvfrom"> <refnamediv> <refname>socket_recvfrom</refname> <refpurpose>Receives data from a socket, connected or not </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_recvfrom</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -20,10 +20,32 @@ <para> &warn.undocumented.func; </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; <para> - <function>socket_recvfrom</function> has been binary safe since PHP 4.3.0 + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + <function>socket_recvfrom</function> is now binary safe. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-select.xml?r1=1.15&r2=1.16&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-select.xml diff -u phpdoc/en/reference/sockets/functions/socket-select.xml:1.15 phpdoc/en/reference/sockets/functions/socket-select.xml:1.16 --- phpdoc/en/reference/sockets/functions/socket-select.xml:1.15 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-select.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.16 $ --> <refentry id="function.socket-select"> <refnamediv> <refname>socket_select</refname> <refpurpose>Runs the select() system call on the given arrays of sockets with a specified timeout</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_select</methodname> <methodparam><type>array</type><parameter role="reference">read</parameter></methodparam> @@ -17,26 +17,70 @@ <methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter></methodparam> </methodsynopsis> <para> - <function>socket_select</function> accepts arrays of sockets and - waits for them to change status. Those coming with BSD sockets background - will recognize that those socket resource arrays are in fact the - so-called file descriptor sets. Three independent arrays of socket - resources are watched. - </para> - <para> - The sockets listed in the <parameter>read</parameter> array will be watched to - see if characters become available for reading (more precisely, to see if - a read will not block - in particular, a socket resource is also ready on - end-of-file, in which case a <function>socket_read</function> will return - a zero length string). - </para> - <para> - The sockets listed in the <parameter>write</parameter> array will be - watched to see if a write will not block. + <function>socket_select</function> accepts arrays of sockets and waits for + them to change status. Those coming with BSD sockets background will + recognize that those socket resource arrays are in fact the so-called file + descriptor sets. Three independent arrays of socket resources are watched. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The sockets listed in the <parameter>except</parameter> array will be - watched for exceptions. + <variablelist> + <varlistentry> + <term><parameter>read</parameter></term> + <listitem> + <para> + The sockets listed in the <parameter>read</parameter> array will be + watched to see if characters become available for reading (more + precisely, to see if a read will not block - in particular, a socket + resource is also ready on end-of-file, in which case a + <function>socket_read</function> will return a zero length string). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>write</parameter></term> + <listitem> + <para> + The sockets listed in the <parameter>write</parameter> array will be + watched to see if a write will not block. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>except</parameter></term> + <listitem> + <para> + The sockets listed in the <parameter>except</parameter> array will be + watched for exceptions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>tv_sec</parameter></term> + <listitem> + <para> + The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter> + together form the <emphasis>timeout</emphasis> parameter. The + <emphasis>timeout</emphasis> is an upper bound on the amount of time + elapsed before <function>socket_select</function> return. + <parameter>tv_sec</parameter> may be zero , causing + <function>socket_select</function> to return immediately. This is useful + for polling. If <parameter>tv_sec</parameter> is &null; (no timeout), + <function>socket_select</function> can block indefinitely. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>tv_usec</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> </para> <warning> <para> @@ -51,28 +95,6 @@ passed <emphasis>by reference</emphasis> and will be modified after <function>socket_select</function> returns. </para> - <para> - <example> - <title><function>socket_select</function> example</title> - <programlisting role="php"> -<![CDATA[ -<?php -/* Prepare the read array */ -$read = array($socket1, $socket2); -$write = NULL; -$except = NULL; -$num_changed_sockets = socket_select($read, $write, $except, 0); - -if ($num_changed_sockets === false) { - /* Error handling */ -} else if ($num_changed_sockets > 0) { - /* At least at one of the sockets something interesting happened */ -} -?> -]]> - </programlisting> - </example> - </para> <note> <para> Due a limitation in the current Zend Engine it is not possible to pass a @@ -93,16 +115,10 @@ </example> </para> </note> - <para> - The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter> - together form the <emphasis>timeout</emphasis> parameter. The - <emphasis>timeout</emphasis> is an upper bound on the amount of time - elapsed before <function>socket_select</function> return. - <parameter>tv_sec</parameter> may be zero , causing - <function>socket_select</function> to return immediately. This is useful - for polling. If <parameter>tv_sec</parameter> is &null; (no timeout), - <function>socket_select</function> can block indefinitely. - </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> On success <function>socket_select</function> returns the number of socket resources contained in the modified arrays, which may be zero if @@ -112,12 +128,12 @@ </para> <note> <para> - Be sure to use the <literal>===</literal> operator when checking for an - error. Since the <function>socket_select</function> may return 0 the - comparison with <literal>==</literal> would evaluate to &true;: - <example> - <title>Understanding <function>socket_select</function>'s result</title> - <programlisting role="php"> + Be sure to use the <literal>===</literal> operator when checking for an + error. Since the <function>socket_select</function> may return 0 the + comparison with <literal>==</literal> would evaluate to &true;: + <example> + <title>Understanding <function>socket_select</function>'s result</title> + <programlisting role="php"> <![CDATA[ <?php $e = NULL; @@ -131,6 +147,36 @@ </example> </para> </note> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>socket_select</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +/* Prepare the read array */ +$read = array($socket1, $socket2); +$write = NULL; +$except = NULL; +$num_changed_sockets = socket_select($read, $write, $except, 0); + +if ($num_changed_sockets === false) { + /* Error handling */ +} else if ($num_changed_sockets > 0) { + /* At least at one of the sockets something interesting happened */ +} +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Be aware that some socket implementations need to be handled very @@ -172,14 +218,20 @@ </itemizedlist> </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_read</function>, - <function>socket_write</function>, - <function>socket_last_error</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_read</function></member> + <member><function>socket_write</function></member> + <member><function>socket_last_error</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-send.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-send.xml diff -u phpdoc/en/reference/sockets/functions/socket-send.xml:1.5 phpdoc/en/reference/sockets/functions/socket-send.xml:1.6 --- phpdoc/en/reference/sockets/functions/socket-send.xml:1.5 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-send.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.socket-send"> <refnamediv> <refname>socket_send</refname> - <refpurpose>Sends data to a connected socket </refpurpose> + <refpurpose>Sends data to a connected socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_send</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -20,53 +20,100 @@ <parameter>len</parameter> bytes to the socket <parameter>socket</parameter> from <parameter>buf</parameter> </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The value of <parameter>flags</parameter> can be any - <literal>ORed</literal> combination of the following: - <table> - <title>possible values for <parameter>flags</parameter></title> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>0x1</literal></entry> - <entry> - Process OOB (out-of-band) data - </entry> - </row> - <row> - <entry><literal>0x2</literal></entry> - <entry> - Peek at incoming message - </entry> - </row> - <row> - <entry><literal>0x4</literal></entry> - <entry> - Bypass routing, use direct interface - </entry> - </row> - <row> - <entry><literal>0x8</literal></entry> - <entry> - Data completes record - </entry> - </row> - <row> - <entry><literal>0x100</literal></entry> - <entry> - Data completes transaction - </entry> - </row> - </tbody> - </tgroup> - </table> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>buf</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>len</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para> + The value of <parameter>flags</parameter> can be any + <literal>ORed</literal> combination of the following: + <table> + <title>possible values for <parameter>flags</parameter></title> + <tgroup cols="2"> + <tbody> + <row> + <entry><literal>0x1</literal></entry> + <entry> + Process OOB (out-of-band) data + </entry> + </row> + <row> + <entry><literal>0x2</literal></entry> + <entry> + Peek at incoming message + </entry> + </row> + <row> + <entry><literal>0x4</literal></entry> + <entry> + Bypass routing, use direct interface + </entry> + </row> + <row> + <entry><literal>0x8</literal></entry> + <entry> + Data completes record + </entry> + </row> + <row> + <entry><literal>0x100</literal></entry> + <entry> + Data completes transaction + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also - <function>socket_sendmsg</function> and - <function>socket_sendto</function>. + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>socket_sendmsg</function></member> + <member><function>socket_sendto</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-sendto.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-sendto.xml diff -u phpdoc/en/reference/sockets/functions/socket-sendto.xml:1.6 phpdoc/en/reference/sockets/functions/socket-sendto.xml:1.7 --- phpdoc/en/reference/sockets/functions/socket-sendto.xml:1.6 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-sendto.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.7 $ --> <refentry id="function.socket-sendto"> <refnamediv> <refname>socket_sendto</refname> <refpurpose>Sends a message to a socket, whether it is connected or not </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_sendto</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -23,50 +23,111 @@ through the socket <parameter>socket</parameter> to the <parameter>port</parameter> at the address <parameter>addr</parameter> </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The value of <parameter>flags</parameter> can be one of the - following: - <table> - <title>possible values for <parameter>flags</parameter></title> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>0x1</literal></entry> - <entry> - Process OOB (out-of-band) data. - </entry> - </row> - <row> - <entry><literal>0x2</literal></entry> - <entry> - Peek at incoming message. - </entry> - </row> - <row> - <entry><literal>0x4</literal></entry> - <entry> - Bypass routing, use direct interface. - </entry> - </row> - <row> - <entry><literal>0x8</literal></entry> - <entry> - Data completes record. - </entry> - </row> - <row> - <entry><literal>0x100</literal></entry> - <entry> - Data completes transaction. - </entry> - </row> - </tbody> - </tgroup> - </table> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>buf</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>len</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para> + The value of <parameter>flags</parameter> can be one of the + following: + <table> + <title>possible values for <parameter>flags</parameter></title> + <tgroup cols="2"> + <tbody> + <row> + <entry><literal>0x1</literal></entry> + <entry> + Process OOB (out-of-band) data. + </entry> + </row> + <row> + <entry><literal>0x2</literal></entry> + <entry> + Peek at incoming message. + </entry> + </row> + <row> + <entry><literal>0x4</literal></entry> + <entry> + Bypass routing, use direct interface. + </entry> + </row> + <row> + <entry><literal>0x8</literal></entry> + <entry> + Data completes record. + </entry> + </row> + <row> + <entry><literal>0x100</literal></entry> + <entry> + Data completes transaction. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>addr</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> </para> - <example> - <title><function>socket_sendto</function> Example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + + </para> + </refsect1> + + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>socket_sendto</function> Example</title> + <programlisting role="php"> <![CDATA[ <?php $sh = socket_create(AF_INET, SOCK_STREAM, SOL_TCP); @@ -81,14 +142,21 @@ socket_close($sh); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_send</function> and - <function>socket_sendmsg</function>. + <simplelist> + <member><function>socket_send</function></member> + <member><function>socket_sendmsg</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-set-block.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-set-block.xml diff -u phpdoc/en/reference/sockets/functions/socket-set-block.xml:1.6 phpdoc/en/reference/sockets/functions/socket-set-block.xml:1.7 --- phpdoc/en/reference/sockets/functions/socket-set-block.xml:1.6 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-set-block.xml Fri Jun 15 00:12:30 2007 @@ -1,12 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.socket-set-block"> <refnamediv> <refname>socket_set_block</refname> <refpurpose>Sets blocking mode on a socket resource</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_set_block</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -15,6 +16,32 @@ The <function>socket_set_block</function> function removes the O_NONBLOCK flag on the socket specified by the <parameter>socket</parameter> parameter. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>socket_set_block</function> example</title> @@ -44,14 +71,18 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - &return.success; - </para> - <para> - See also <function>socket_set_nonblock</function> and - <function>socket_set_option</function> + <simplelist> + <member><function>socket_set_nonblock</function></member> + <member><function>socket_set_option</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-set-nonblock.xml?r1=1.9&r2=1.10&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-set-nonblock.xml diff -u phpdoc/en/reference/sockets/functions/socket-set-nonblock.xml:1.9 phpdoc/en/reference/sockets/functions/socket-set-nonblock.xml:1.10 --- phpdoc/en/reference/sockets/functions/socket-set-nonblock.xml:1.9 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-set-nonblock.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.10 $ --> <refentry id="function.socket-set-nonblock"> <refnamediv> <refname>socket_set_nonblock</refname> <refpurpose>Sets nonblocking mode for file descriptor fd </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_set_nonblock</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -16,6 +16,32 @@ The <function>socket_set_nonblock</function> function sets the O_NONBLOCK flag on the socket specified by the <parameter>socket</parameter> parameter. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>socket_set_nonblock</function> example</title> @@ -39,14 +65,18 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - &return.success; - </para> - <para> - See also <function>socket_set_block</function> and - <function>socket_set_option</function> + <simplelist> + <member><function>socket_set_block</function></member> + <member><function>socket_set_option</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-set-option.xml?r1=1.9&r2=1.10&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-set-option.xml diff -u phpdoc/en/reference/sockets/functions/socket-set-option.xml:1.9 phpdoc/en/reference/sockets/functions/socket-set-option.xml:1.10 --- phpdoc/en/reference/sockets/functions/socket-set-option.xml:1.9 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-set-option.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.10 $ --> <refentry id="function.socket-set-option"> <refnamediv> <refname>socket_set_option</refname> <refpurpose>Sets socket options for the socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_set_option</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -16,29 +16,92 @@ <methodparam><type>mixed</type><parameter>optval</parameter></methodparam> </methodsynopsis> <para> - The <function>socket_set_option</function> function sets the option specified by the <parameter>optname</parameter> - parameter, at the protocol level specified by the <parameter>level</parameter> parameter, to the - value pointed to by the <parameter>optval</parameter> parameter for the socket - specified by the <parameter>socket</parameter> parameter. <function>socket_set_option</function> - will return &false; on failure. + The <function>socket_set_option</function> function sets the option + specified by the <parameter>optname</parameter> parameter, at the + specified protocol <parameter>level</parameter>, to the value pointed to + by the <parameter>optval</parameter> parameter for the + <parameter>socket</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The <parameter>level</parameter> parameter specifies the protocol level at - which the option resides. For example, to retrieve options at the socket level, - a <parameter>level</parameter> parameter of SOL_SOCKET would be used. Other - levels, such as TCP, can be used by specifying the protocol number of that level. - Protocol numbers can be found by using the <function>getprotobyname</function> function. + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>level</parameter></term> + <listitem> + <para> + The <parameter>level</parameter> parameter specifies the protocol + level at which the option resides. For example, to retrieve options at + the socket level, a <parameter>level</parameter> parameter of + <constant>SOL_SOCKET</constant> would be used. Other levels, such as + TCP, can be used by specifying the protocol number of that level. + Protocol numbers can be found by using the + <function>getprotobyname</function> function. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>optname</parameter></term> + <listitem> + <para> + The available socket options are the same as those for the + <function>socket_get_option</function> function. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>optval</parameter></term> + <listitem> + <para> + The option value. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - The available socket options are the same as those for the <function>socket_get_option</function> function. + &return.success; </para> - <note> - <para> - This function used to be called <function>socket_setopt</function> prior - to PHP 4.3.0. - </para> - </note> </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + This function was renamed. It used to be called + <function>socket_setopt</function>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-shutdown.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-shutdown.xml diff -u phpdoc/en/reference/sockets/functions/socket-shutdown.xml:1.6 phpdoc/en/reference/sockets/functions/socket-shutdown.xml:1.7 --- phpdoc/en/reference/sockets/functions/socket-shutdown.xml:1.6 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-shutdown.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.7 $ --> <refentry id="function.socket-shutdown"> <refnamediv> <refname>socket_shutdown</refname> <refpurpose>Shuts down a socket for receiving, sending, or both</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>socket_shutdown</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -18,35 +18,63 @@ incoming, outgoing or all data (the default) from being sent through the <parameter>socket</parameter> </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The value of <parameter>how</parameter> can be one of the following: - <table> - <title>possible values for <parameter>how</parameter></title> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>0</literal></entry> - <entry> - Shutdown socket reading - </entry> - </row> - <row> - <entry><literal>1</literal></entry> - <entry> - Shutdown socket writing - </entry> - </row> - <row> - <entry><literal>2</literal></entry> - <entry> - Shutdown socket reading and writing - </entry> - </row> - </tbody> - </tgroup> - </table> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>how</parameter></term> + <listitem> + <para> + The value of <parameter>how</parameter> can be one of the following: + <table> + <title>possible values for <parameter>how</parameter></title> + <tgroup cols="2"> + <tbody> + <row> + <entry><literal>0</literal></entry> + <entry> + Shutdown socket reading + </entry> + </row> + <row> + <entry><literal>1</literal></entry> + <entry> + Shutdown socket writing + </entry> + </row> + <row> + <entry><literal>2</literal></entry> + <entry> + Shutdown socket reading and writing + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> </para> </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-strerror.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-strerror.xml diff -u phpdoc/en/reference/sockets/functions/socket-strerror.xml:1.8 phpdoc/en/reference/sockets/functions/socket-strerror.xml:1.9 --- phpdoc/en/reference/sockets/functions/socket-strerror.xml:1.8 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-strerror.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.8 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.socket-strerror"> <refnamediv> <refname>socket_strerror</refname> <refpurpose>Return a string describing a socket error</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>socket_strerror</methodname> <methodparam><type>int</type><parameter>errno</parameter></methodparam> @@ -21,6 +21,33 @@ system include file to find out what '-111' means, you just pass it to <function>socket_strerror</function>, and it tells you what happened. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>errno</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the error message associated with the <parameter>errno</parameter> + parameter. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>socket_strerror</function> example</title> @@ -48,15 +75,21 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_accept</function>, - <function>socket_bind</function>, - <function>socket_connect</function>, - <function>socket_listen</function>, and - <function>socket_create</function>. + <simplelist> + <member><function>socket_accept</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_connect</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_create</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-write.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-write.xml diff -u phpdoc/en/reference/sockets/functions/socket-write.xml:1.5 phpdoc/en/reference/sockets/functions/socket-write.xml:1.6 --- phpdoc/en/reference/sockets/functions/socket-write.xml:1.5 Fri Jun 15 00:12:05 2007 +++ phpdoc/en/reference/sockets/functions/socket-write.xml Fri Jun 15 00:12:30 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.socket-write"> <refnamediv> <refname>socket_write</refname> <refpurpose>Write to a socket</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>socket_write</methodname> <methodparam><type>resource</type><parameter>socket</parameter></methodparam> @@ -15,16 +15,48 @@ <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> </methodsynopsis> <para> - The function <function>socket_write</function> writes to the socket - <parameter>socket</parameter> from + The function <function>socket_write</function> writes to the + <parameter>socket</parameter> from the given <parameter>buffer</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The optional parameter <parameter>length</parameter> can specify an - alternate length of bytes written to the socket. If this length is - greater then the buffer length, it is silently truncated to the length of - the buffer. + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>buffer</parameter></term> + <listitem> + <para> + The buffer to be written. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + The optional parameter <parameter>length</parameter> can specify an + alternate length of bytes written to the socket. If this length is + greater then the buffer length, it is silently truncated to the length + of the buffer. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> Returns the number of bytes successfully written to the socket or &false; one error. The error code can be retrieved with @@ -34,6 +66,18 @@ </para> <note> <para> + It is perfectly valid for <function>socket_write</function> to + return zero which means no bytes have been written. Be sure to use the + <literal>===</literal> operator to check for &false; in case of an + error. + </para> + </note> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> <function>socket_write</function> does not necessarily write all bytes from the given buffer. It's valid that, depending on the network buffers etc., only a certain amount of data, even one byte, is written @@ -41,24 +85,22 @@ unintentionally forget to transmit the rest of your data. </para> </note> - <note> - <para> - It is perfectly valid for <function>socket_write</function> to - return zero which means no bytes have been written. Be sure to use the - <literal>===</literal> operator to check for &false; in case of an - error. - </para> - </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>socket_accept</function>, - <function>socket_bind</function>, - <function>socket_connect</function>, - <function>socket_listen</function>, - <function>socket_read</function> and - <function>socket_strerror</function>. + <simplelist> + <member><function>socket_accept</function></member> + <member><function>socket_bind</function></member> + <member><function>socket_connect</function></member> + <member><function>socket_listen</function></member> + <member><function>socket_read</function></member> + <member><function>socket_strerror</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file