I have an attached patch file that I am about to commit, but once again as I am
pretty new to the documentation team, I wanted to know if anyone had any
feedback before I did so.
-Logan
? cURL.patch
? en/reference/posix/functions/posix.patch
? scripts/semantic.cache
Index: en/reference/curl/functions/curl-multi-add-handle.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-add-handle.xml,v
retrieving revision 1.3
diff -u -r1.3 curl-multi-add-handle.xml
--- en/reference/curl/functions/curl-multi-add-handle.xml 17 Jan 2007 00:14:52 -0000 1.3
+++ en/reference/curl/functions/curl-multi-add-handle.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<refentry id="function.curl-multi-add-handle">
<refnamediv>
<refname>curl_multi_add_handle</refname>
@@ -36,7 +36,56 @@
code.
</para>
</refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>curl_multi_init</function> example</title>
+ <para>
+ This example will create two cURL handles, add them to a multi
+ handle, and then run them in parallel.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+//create a status flag
+$running=0;
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh,&$running);
+//wait until it's no longer running
+while($running) {
+ sleep(1);
+}
+
+curl_multi_close();
+
+echo 'Done!';
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
Index: en/reference/curl/functions/curl-multi-close.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-close.xml,v
retrieving revision 1.3
diff -u -r1.3 curl-multi-close.xml
--- en/reference/curl/functions/curl-multi-close.xml 17 Jan 2007 00:14:52 -0000 1.3
+++ en/reference/curl/functions/curl-multi-close.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<refentry id="function.curl-multi-close">
<refnamediv>
<refname>curl_multi_close</refname>
@@ -33,6 +33,55 @@
</para>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>curl_multi_init</function> example</title>
+ <para>
+ This example will create two cURL handles, add them to a multi
+ handle, and then run them in parallel.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+//create a status flag
+$running=0;
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh,&$running);
+
+//wait until it's no longer running
+while($running) {
+ sleep(1);
+}
+
+curl_multi_close();
+
+echo 'Done!';
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
Index: en/reference/curl/functions/curl-multi-exec.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-exec.xml,v
retrieving revision 1.5
diff -u -r1.5 curl-multi-exec.xml
--- en/reference/curl/functions/curl-multi-exec.xml 17 Jan 2007 00:14:52 -0000 1.5
+++ en/reference/curl/functions/curl-multi-exec.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<refentry id="function.curl-multi-exec">
<refnamediv>
<refname>curl_multi_exec</refname>
@@ -13,9 +13,10 @@
<methodparam><type>resource</type><parameter>mh</parameter></methodparam>
<methodparam><type>int</type><parameter role="reference">still_running</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ Processes each of the handles in the stack. This method can be called whether or not a handle
+ needs to read or write data.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -27,13 +28,63 @@
<term><parameter>still_running</parameter></term>
<listitem>
<para>
+ A reference to a flag to tell whether the operations are still running.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>curl_multi_init</function> example</title>
+ <para>
+ This example will create two cURL handles, add them to a multi
+ handle, and then run them in parallel.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+//create a status flag
+$running=0;
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh,&$running);
+
+//wait until it's no longer running
+while($running) {
+ sleep(1);
+}
+
+curl_multi_close();
+
+echo 'Done!';
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
Index: en/reference/curl/functions/curl-multi-getcontent.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-getcontent.xml,v
retrieving revision 1.4
diff -u -r1.4 curl-multi-getcontent.xml
--- en/reference/curl/functions/curl-multi-getcontent.xml 5 Feb 2007 10:09:00 -0000 1.4
+++ en/reference/curl/functions/curl-multi-getcontent.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<refentry id="function.curl-multi-getcontent">
<refnamediv>
<refname>curl_multi_getcontent</refname>
@@ -12,9 +12,11 @@
<type>string</type><methodname>curl_multi_getcontent</methodname>
<methodparam><type>resource</type><parameter>ch</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ If CURLOPT_RETURNTRANSFER is an option that is set for a specific handle,
+ then this function will return the content of that cURL handle in the form
+ of a string.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -25,6 +27,13 @@
</variablelist>
</para>
</refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Return the content of a cURL handle if CURLOPT_RETURNTRANSFER is set.
+ </para>
+ </refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
Index: en/reference/curl/functions/curl-multi-info-read.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-info-read.xml,v
retrieving revision 1.4
diff -u -r1.4 curl-multi-info-read.xml
--- en/reference/curl/functions/curl-multi-info-read.xml 28 Jan 2007 16:49:30 -0000 1.4
+++ en/reference/curl/functions/curl-multi-info-read.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<refentry id="function.curl-multi-info-read">
<refnamediv>
<refname>curl_multi_info_read</refname>
@@ -13,20 +13,48 @@
<methodparam><type>resource</type><parameter>mh</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>msgs_in_queue</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ Ask the multi handle if there are any messages/informationals from the individual transfers.
+ Messages may include informationals such as an error code from the transfer or just the fact
+ that a transfer is completed.
+
+ Repeated calls to this function will return a new result each time, until a &false; is returned
+ as a signal that there is no more to get at this point. The integer pointed to with
+ <parameter>msgs_in_queue</parameter> will contain the number of remaining messages after this
+ function was called.
+ </para>
+ <warning>
+ <para>
+ The data the returned resource points to will not survive calling
+ <function>curl_multi_remove_handle</function>.
+ </para>
+ </warning>
</refsect1>
-
+
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
&curl.mh.description;
+ <varlistentry>
+ <term><parameter>msgs_in_queue</parameter></term>
+ <listitem>
+ <para>
+ Number of messages that are still in the queue
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
</refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ On success, returns an associative array for the message, &false; on failure.
+ </para>
+ </refsect1>
+
<refsect1 role="changelog">
&reftitle.changelog;
<para>
Index: en/reference/curl/functions/curl-multi-init.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-init.xml,v
retrieving revision 1.3
diff -u -r1.3 curl-multi-init.xml
--- en/reference/curl/functions/curl-multi-init.xml 17 Jan 2007 00:14:52 -0000 1.3
+++ en/reference/curl/functions/curl-multi-init.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<refentry id="function.curl-multi-init">
<refnamediv>
<refname>curl_multi_init</refname>
@@ -12,9 +12,9 @@
<type>resource</type><methodname>curl_multi_init</methodname>
<void />
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ Allows the processing of multiple cURL handles in parallel.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -26,6 +26,68 @@
</para>
</refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns a cURL on handle on success, &false; on failure.
+ </para>
+ <note>
+ <para>
+ This only returns errors regarding the whole multi stack. There might still have
+ occurred problems on individual transfers even when this function returns CURLM_OK.
+ </para>
+ </note>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>curl_multi_init</function> example</title>
+ <para>
+ This example will create two cURL handles, add them to a multi
+ handle, and then run them in parallel.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/";);
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+//create a status flag
+$running=0;
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh,&$running);
+
+//wait until it's no longer running
+while($running) {
+ sleep(1);
+}
+
+curl_multi_close();
+
+echo 'Done!';
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
Index: en/reference/curl/functions/curl-multi-remove-handle.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-remove-handle.xml,v
retrieving revision 1.3
diff -u -r1.3 curl-multi-remove-handle.xml
--- en/reference/curl/functions/curl-multi-remove-handle.xml 17 Jan 2007 00:14:52 -0000 1.3
+++ en/reference/curl/functions/curl-multi-remove-handle.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<refentry id="function.curl-multi-remove-handle">
<refnamediv>
<refname>curl_multi_remove_handle</refname>
@@ -13,9 +13,12 @@
<methodparam><type>resource</type><parameter>mh</parameter></methodparam>
<methodparam><type>resource</type><parameter>ch</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ Removes a given <parameter>ch</parameter> handle from the given <parameter>mh</parameter>
+ handle. When the <parameter>ch</parameter> handle has been removed, it is again perfectly
+ legal to run <function>curl_exec</function> on this handle. Removing a handle while being
+ used, will effectively halt all transfers in progress.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -27,6 +30,13 @@
</variablelist>
</para>
</refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ On success, returns a cURL handle, &false; on failure.
+ </para>
+ </refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
Index: en/reference/curl/functions/curl-multi-select.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/curl/functions/curl-multi-select.xml,v
retrieving revision 1.3
diff -u -r1.3 curl-multi-select.xml
--- en/reference/curl/functions/curl-multi-select.xml 17 Jan 2007 00:14:52 -0000 1.3
+++ en/reference/curl/functions/curl-multi-select.xml 31 May 2007 06:11:22 -0000
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<refentry id="function.curl-multi-select">
<refnamediv>
<refname>curl_multi_select</refname>
@@ -13,8 +13,9 @@
<methodparam><type>resource</type><parameter>mh</parameter></methodparam>
<methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
+ <para>
+ Get all the sockets associated with the cURL extension, which can then be "selected".
+ </para>
</refsect1>
@@ -27,12 +28,21 @@
<term><parameter>timeout</parameter></term>
<listitem>
<para>
+ Time, in seconds, to wait for a response.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ On success, returns the number of descriptors contained in,
+ the descriptor sets. On failure, this function will return &false;.
+ </para>
+ </refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
