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

nicobn Mon Jun 25 17:15:51 2007 UTC Modified files: /phpdoc/en/reference/sockets/functions socket-recvfrom.xml Log: Documented the socket_recvfrom function http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sockets/functions/socket-recvfrom.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/sockets/functions/socket-recvfrom.xml diff -u phpdoc/en/reference/sockets/functions/socket-recvfrom.xml:1.10 phpdoc/en/reference/sockets/functions/socket-recvfrom.xml:1.11 --- phpdoc/en/reference/sockets/functions/socket-recvfrom.xml:1.10 Wed Jun 20 22:25:25 2007 +++ phpdoc/en/reference/sockets/functions/socket-recvfrom.xml Mon Jun 25 17:15:51 2007 @@ -1,9 +1,9 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.10 $ --> +<!-- $Revision: 1.11 $ --> <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.socket-recvfrom"> <refnamediv> <refname>socket_recvfrom</refname> - <refpurpose>Receives data from a socket, connected or not </refpurpose> + <refpurpose>Receives data from a socket whether or not it is connection-oriented</refpurpose> </refnamediv> <refsect1 role="description"> @@ -18,7 +18,170 @@ <methodparam choice="opt"><type>int</type><parameter role="reference">port</parameter></methodparam> </methodsynopsis> <para> - &warn.undocumented.func; + The <function>socket_recvfrom</function> function receives <parameter>len</paramater> + bytes of data in <parameter>buf</parameter> from <parameter>name</parameter> on port + <parameter>port</parameter> (if socket is not of AF_UNIX type) using + <parameter>socket</parameter>. <function>socket_recvfrom</function> can be used to + gather data from either a connected or an unconnected socket. Additionally, one or more + flags can be specified to modify the behaviour of the function. + </para> + <para> + The <parameter>name</parameter> and <parameter>port</parameter> must be passed as a + reference. If the socket is not connection-oriented, <parameter>name</parameter> will + be set to the internet protocol address of the remote host or the path to the UNIX + socket. If the socket is connection-oriented, <parameter>name</parameter> is &null. + Additionnally, the <parameter>port</parameter> will contain the port of the + remote host in the case of a not connection-oriented AF_INET or AF_INET6 socket. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>socket</parameter></term> + <listitem> + <para> + The <parameter>socket</parameter> must be a socket resource previously created with socket_create(). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>buf</parameter></term> + <listitem> + <para> + The data received will be fetched to the variable specified with <parameter>buf</parameter>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>len</parameter></term> + <listitem> + <para> + Up to <parameter>len</parameter> bytes will be fetched from remote host. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para> + The following table contains the different flags that can be set using the + <parameter>flags</parameter> parameter. Use the OR logic operator to use more + than one flag. + </para> + + <table> + <title>Available flags</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Flag</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>MSG_OOB</entry> + <entry> + Receive out-of-band data. + </entry> + </row> + <row> + <entry>MSG_PEEK</entry> + <entry> + Receive data from the beginning of the receive queue without removing + it from the queue. + </entry> + </row> + <row> + <entry>MSG_WAITALL</entry> + <entry> + Block until at least <parameter>len</parameter> are received. However, + if a signal is caught or the remote host disconnects, the function + may return less data. + </entry> + </row> + <row> + <entry>MSG_DONTWAIT</entry> + <entry> + With this flag set, the function returns even if it would normally have + blocked. + </entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + If the socket is of AF_UNIX type, <parameter>name</parameter> is the path to the + file. Else, in the case of non-connection oriented socket <parameter>name</parameter> + is the IP address of the remote host and &null if the socket is connection oriented. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + This argument only applies to AF_INET and AF_INET6 sockets and specifies the + remote port from which the data is received. If the socket is connection + oriented, <parameter>port</parameter> will be &null. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + <function>socket_recvfrom</function> returns the number of bytes received + or -1 if there was an 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> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>socket_recvfrom</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +error_reporting(E_ALL | E_STRICT); + +$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP); +socket_connect($socket, "127.0.0.1", 1223); + +$Ip = ""; +socket_recvfrom($socket, $buf, 12, 0, $Ip, $Port); + +echo "Received data: $buf"; +?> +]]> + </programlisting> + <para> + This will example will initiate a TCP connection to 127.0.0.1 on port 1223 + and print at most 12 characters received from the remote host or block + until no data is received. + </para> + </example> </para> </refsect1> @@ -46,6 +209,17 @@ </para> </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>socket_recv</function></member> + <member><function>socket_send</function></member> + <member><function>socket_sendto</function></member> + <member><function>socket_create</function></member> + </simplelist> + </para> + </refsect1> </refentry> <!-- Keep this comment at the end of the file