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 9676f71dbcd9de2f682fcefba05ecffc993c88b7..c3a08f14f72436c4bcce547a5bbc0ce0efc08cbb 100644 (file)
--- 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 76c35ba386a4daa0a7d2a99125fed1acea4672d8..e53b30573f069773313424a2d67867425f4f26c8 100644 (file)
--- 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);