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

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

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);