From: Jay Satiro <raysatiro@yahoo.com>
Date: Thu, 5 Oct 2023 07:19:47 +0000 (-0400)
Subject: CURLOPT_DEBUGFUNCTION.3: warn about internal handles
X-Git-Tag: curl-8_4_0~17
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0dc40b2a0fef0287f8cc161290f9f113da84861a;p=thirdparty%2Fcurl.git

CURLOPT_DEBUGFUNCTION.3: warn about internal handles

- Warn that the user's debug callback may be called with the handle
  parameter set to an internal handle.

Without this warning the user may assume that the only handles their
debug callback receives are the easy handles on which they set
CURLOPT_DEBUGFUNCTION.

This is a follow-up to f8cee8cc which changed DoH handles to inherit
the debug callback function set in the user's easy handle. As a result
those handles are now passed to the user's debug callback function.

Closes https://github.com/curl/curl/pull/12034
---

diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3
index 9676f71dbc..c3a08f14f7 100644
--- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3
@@ -62,6 +62,7 @@ not null-terminated, but is exactly of the \fIsize\fP as told by the
 The \fIclientp\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP.
 
 Available \fBcurl_infotype\fP values:
+.RS
 .IP CURLINFO_TEXT
 The data is informational text.
 .IP CURLINFO_HEADER_IN
@@ -79,6 +80,13 @@ The data is protocol data sent to the peer.
 The data is SSL/TLS (binary) data sent to the peer.
 .IP CURLINFO_SSL_DATA_IN
 The data is SSL/TLS (binary) data received from the peer.
+.RE
+
+WARNING: This callback may be called with the curl \fIhandle\fP set to an
+internal handle. (Added in 8.4.0)
+
+If you need to distinguish your curl \fIhandle\fP from internal handles then
+set \fICURLOPT_PRIVATE(3)\fP on your handle.
 .SH DEFAULT
 NULL
 .SH PROTOCOLS
diff --git a/lib/curl_trc.c b/lib/curl_trc.c
index 76c35ba386..e53b30573f 100644
--- a/lib/curl_trc.c
+++ b/lib/curl_trc.c
@@ -61,6 +61,10 @@ void Curl_debug(struct Curl_easy *data, curl_infotype type,
       "* ", "< ", "> ", "{ ", "} ", "{ ", "} " };
     if(data->set.fdebug) {
       bool inCallback = Curl_is_in_callback(data);
+      /* CURLOPT_DEBUGFUNCTION doc says the user may set CURLOPT_PRIVATE to
+         distinguish their handle from internal handles. */
+      if(data->internal)
+        DEBUGASSERT(!data->set.private_data);
       Curl_set_in_callback(data, true);
       (void)(*data->set.fdebug)(data, type, ptr, size, data->set.debugdata);
       Curl_set_in_callback(data, inCallback);