libcurl-env-dbg.3: move debug variables from libcurl-env.3

- Move documentation of libcurl environment variables used only in debug
  builds from libcurl-env into a separate document libcurl-env-dbg.

- Document more debug environment variables.

Previously undocumented or missing a description:

CURL_ALTSVC_HTTP, CURL_DBG_SOCK_WBLOCK, CURL_DBG_SOCK_WPARTIAL,
CURL_DBG_QUIC_WBLOCK, CURL_DEBUG, CURL_DEBUG_SIZE, CURL_GETHOSTNAME,
CURL_HSTS_HTTP, CURL_FORCETIME, CURL_SMALLREQSEND, CURL_SMALLSENDS,
CURL_TIME.

Closes https://github.com/curl/curl/pull/11811

4 files changed, 108 insertions, 17 deletions

diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words
index ce0102bca..8856afc31 100644
--- a/.github/scripts/spellcheck.words
+++ b/.github/scripts/spellcheck.words
@@ -14,6 +14,7 @@ allocator
 alnum
 ALPN
 Altera
+AltSvc
 ALTSVC
 amiga
 AmigaOS
@@ -139,6 +140,7 @@ cURL
 CURLcode
 CURLE
 CURLH
+CURLINFO
 curlimages
 curlrc
 curltest
@@ -151,7 +153,9 @@ cyassl
 Cygwin
 daniel
 datatracker
+dbg
 Debian
+DEBUGBUILD
 decrypt
 deepcode
 DELE
diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc
index 1f3b1e2ff..336b4192e 100644
--- a/docs/libcurl/Makefile.inc
+++ b/docs/libcurl/Makefile.inc
@@ -111,6 +111,7 @@ man_MANS = \
  curl_ws_send.3 \
  libcurl-easy.3 \
  libcurl-env.3 \
+ libcurl-env-dbg.3 \
  libcurl-errors.3 \
  libcurl-multi.3 \
  libcurl-security.3 \
diff --git a/docs/libcurl/libcurl-env-dbg.3 b/docs/libcurl/libcurl-env-dbg.3
new file mode 100644
index 000000000..6995a8ede
--- /dev/null
+++ b/docs/libcurl/libcurl-env-dbg.3
@@ -0,0 +1,97 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" * SPDX-License-Identifier: curl
+.\" *
+.\" **************************************************************************
+.TH libcurl-env-dbg 3 "18 September 2023" "libcurl" "libcurl"
+.SH NAME
+libcurl-env-dbg \- environment variables libcurl DEBUGBUILD understands
+.SH DESCRIPTION
+This is a set of variables only recognized and used if libcurl was built
+"debug enabled", which should never be true for a library used in production.
+These variables are intended for internal use only, subject to change and have
+many effects on the behavior of libcurl. Refer to the source code to determine
+how exactly they are being used.
+.RS
+.IP "CURL_ALTSVC_HTTP"
+Bypass the AltSvc HTTPS protocol restriction if this variable exists.
+.IP "CURL_DBG_SOCK_RBLOCK"
+The percentage of recv() calls that should be answered with a EAGAIN at random.
+For TCP/UNIX sockets.
+.IP "CURL_DBG_SOCK_RMAX"
+The maximum data that shall be received from the network in one recv() call.
+For TCP/UNIX sockets. This is applied to every recv.
+
+Example: \fBCURL_DBG_SOCK_RMAX=400\fP means recv buffer size is limited to a
+maximum of 400 bytes.
+.IP "CURL_DBG_SOCK_WBLOCK"
+The percentage of send() calls that should be answered with a EAGAIN at random.
+For TCP/UNIX sockets.
+.IP "CURL_DBG_SOCK_WPARTIAL"
+The percentage of data that shall be written to the network. For TCP/UNIX
+sockets. This is applied to every send.
+
+Example: \fBCURL_DBG_SOCK_WPARTIAL=80\fP means a send with 1000 bytes would
+only send 800.
+.IP "CURL_DBG_QUIC_WBLOCK"
+The percentage of send() calls that should be answered with EAGAIN at random.
+QUIC only.
+.IP "CURL_DEBUG"
+Trace logging behavior as an alternative to calling \fIcurl_global_trace(3)\fP.
+
+Example: \fBCURL_DEBUG=http/2\fP means trace details about HTTP/2 handling.
+.IP "CURL_DEBUG_SIZE"
+Fake the size returned by CURLINFO_HEADER_SIZE and CURLINFO_REQUEST_SIZE.
+.IP "CURL_GETHOSTNAME"
+Fake the local machine's unqualified hostname for NTLM and SMTP.
+.IP "CURL_HSTS_HTTP"
+Bypass the HSTS HTTPS protocol restriction if this variable exists.
+.IP "CURL_FORCETIME"
+A time of 0 is used for AWS signatures and NTLM if this variable exists.
+.IP "CURL_ENTROPY"
+A fixed faked value to use instead of a proper random number so that functions
+in libcurl that are otherwise getting random outputs can be tested for what
+they generate.
+.IP "CURL_SMALLREQSEND"
+An alternative size of HTTP data to be sent at a time only if smaller than the
+current.
+.IP "CURL_SMALLSENDS"
+An alternative size of socket data to be sent at a time only if smaller than
+the current.
+.IP "CURL_TIME"
+Fake unix timestamp to use for AltSvc, HSTS and CURLINFO variables that are
+time related.
+
+This variable can also be used to fake the data returned by some CURLINFO
+variables that are not time-related (such as CURLINFO_LOCAL_PORT), and in that
+case the value is not a timestamp.
+.IP "CURL_TRACE"
+LDAP tracing is enabled if this variable exists and its value is 1 or greater.
+
+OpenLDAP tracing is separate. Refer to CURL_OPENLDAP_TRACE.
+.IP "CURL_NTLM_WB_FILE"
+Debug-version of the \fIntlm-wb\fP executable.
+.IP "CURL_OPENLDAP_TRACE"
+OpenLDAP tracing is enabled if this variable exists and its value is 1 or
+greater. There's a number of debug levels, refer to \fIopenldap.c\fP comments.
+.RE
+.SH "SEE ALSO"
+.BR libcurl-env (3)
diff --git a/docs/libcurl/libcurl-env.3 b/docs/libcurl/libcurl-env.3
index bbd697b90..c2ba43215 100644
--- a/docs/libcurl/libcurl-env.3
+++ b/docs/libcurl/libcurl-env.3
@@ -29,6 +29,7 @@ libcurl reads and understands a set of environment variables that if set
 controls and changes behaviors. This is the full list of variables to set and
 description of what they do. Also note that curl, the command line tool,
 supports a set of additional environment variables independently of this.
+.RS
 .IP "[scheme]_proxy"
 When libcurl is given a URL to use in a transfer, it first extracts the scheme
 part from the URL and checks if there is a given proxy set for that in its
@@ -83,21 +84,9 @@ precautions so that they are not stolen or otherwise inadvertently revealed.
 .IP USER
 User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP and
 \fILOGNAME\fP were not set.
+.RE
 .SH "Debug Variables"
-There is a set of variables only recognized and used if libcurl was built
-"debug enabled", which should never be true for a library used in production.
-.IP "CURL_GETHOSTNAME"
-Debug-only variable.
-.IP "CURL_FORCETIME"
-Debug-only variable.
-.IP "CURL_ENTROPY"
-Debug-only variable. Used to set a fixed faked value to use instead of a
-proper random number so that functions in libcurl that are otherwise getting
-random outputs can be tested for what they generate.
-.IP "CURL_TRACE"
-Debug-only variable. Used for debugging the lib/ldap implementation.
-.IP "CURL_NTLM_WB_FILE"
-Debug-only variable. Used to set to a debug-version of the \fIntlm-wb\fP
-executable.
-.IP "CURL_OPENLDAP_TRACE"
-Debug-only variable. Used for debugging the OpenLDAP implementation.
+Debug variables are intended for internal use and are documented in
+\fIlibcurl-env-dbg(3)\fP.
+.SH "SEE ALSO"
+.BR libcurl-env-dbg (3)