Hi, I recently received karma and was advised to post a first patch on the list to receive feedback (please see attachment). I decided to document an undocumented function (socket_recvfrom) as a first task. Feedback/comments/rants will be greatly appreciated !
Thank you in advance, -- Nicolas Bérard-Nault ([EMAIL PROTECTED]) Étudiant D.E.C. Sciences, Lettres & Arts Cégep de Sherbrooke Homepage: http://nicobn.googlepages.com
Index: socket-recvfrom.xml =================================================================== RCS file: /repository/phpdoc/en/reference/sockets/functions/socket-recvfrom.xml,v retrieving revision 1.10 diff -u -r1.10 socket-recvfrom.xml --- socket-recvfrom.xml 20 Jun 2007 22:25:25 -0000 1.10 +++ socket-recvfrom.xml 25 Jun 2007 07:40:00 -0000 @@ -3,7 +3,7 @@ <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,10 +18,135 @@ <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> </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, <parameter>name</parameter> is the IP address of the remote host. + </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 to fetch the data. + </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="changelog"> &reftitle.changelog; <para> @@ -46,6 +171,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
