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
