[DOC-CVS] [doc-en] master: Document curl_errno/curl_error behavior with multi handles (#5233)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-24T10:49:47+02:00

Commit: https://github.com/php/doc-en/commit/ff7a0054b19ab80290b365d1417550807f82755a
Raw diff: https://github.com/php/doc-en/commit/ff7a0054b19ab80290b365d1417550807f82755a.diff

Document curl_errno/curl_error behavior with multi handles (#5233)

* Document curl_errno/curl_error behavior with multi handles

Add a note to curl_errno() and curl_error() documentation explaining
that these functions always return 0 or empty string when the handle
was executed via curl_multi_exec(). Users should use
curl_multi_info_read() to retrieve errors for individual transfers.

Refs #5047

* Apply suggestions from code review

Changed paths:
  M  reference/curl/functions/curl-errno.xml
  M  reference/curl/functions/curl-error.xml


Diff:

diff --git a/reference/curl/functions/curl-errno.xml b/reference/curl/functions/curl-errno.xml
index b34a1881752d..7b9f97b97c49 100644
--- a/reference/curl/functions/curl-errno.xml
+++ b/reference/curl/functions/curl-errno.xml
@@ -32,6 +32,15 @@
    Returns the error number or <literal>0</literal> (zero) if no error
    occurred.
   </para>
+  <note>
+   <simpara>
+    When a <type>CurlHandle</type> is executed via
+    <function>curl_multi_exec</function>, this function always returns
+    <literal>0</literal>. The error code for each individual handle is
+    available as the <literal>result</literal> key returned by
+    <function>curl_multi_info_read</function>.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -83,6 +92,7 @@ if(curl_errno($ch))
   <para>
    <simplelist>
     <member><function>curl_error</function></member>
+    <member><function>curl_multi_info_read</function></member>
     <member><link xlink:href="&url.curl.error;">Curl error codes</link></member>
    </simplelist>
   </para>
diff --git a/reference/curl/functions/curl-error.xml b/reference/curl/functions/curl-error.xml
index 30b4e6fa68e7..166b9cc499f7 100644
--- a/reference/curl/functions/curl-error.xml
+++ b/reference/curl/functions/curl-error.xml
@@ -32,6 +32,16 @@
    Returns the error message or <literal>''</literal> (the empty string) if no
    error occurred.
   </para>
+  <note>
+   <simpara>
+    When a <type>CurlHandle</type> is executed via
+    <function>curl_multi_exec</function>, this function always returns
+    <literal>''</literal> (the empty string). To retrieve the error string for
+    each individual handle, pass the <literal>result</literal> key returned by
+    <function>curl_multi_info_read</function> to
+    <function>curl_strerror</function>.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -83,6 +93,8 @@ else
   <para>
    <simplelist>
     <member><function>curl_errno</function></member>
+    <member><function>curl_strerror</function></member>
+    <member><function>curl_multi_info_read</function></member>
     <member><link xlink:href="&url.curl.error;">Curl error codes</link></member>
    </simplelist>
   </para>