--- name: "libcurl-env-dbg" section: "3" platform: "linux" package: "curl" version: "8.23.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libcurl-env-dbg" --- # libcurl-env-dbg(3) environment variables libcurl DEBUGBUILD understands ## NAME libcurl-env-dbg - environment variables libcurl DEBUGBUILD understands ## 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. - CURL\_ALTSVC\_HTTP Bypass the AltSvc HTTPS protocol restriction if this variable exists. - CURL\_DBG\_SOCK\_RBLOCK The percentage of recv() calls that should be answered with an EAGAIN at random. For TCP/UNIX sockets. - 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: **CURL\_DBG\_SOCK\_RMAX=400** means recv buffer size is limited to a maximum of 400 bytes. - CURL\_DBG\_SOCK\_WBLOCK The percentage of send() calls that should be answered with an EAGAIN at random. For TCP/UNIX sockets. - 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: **CURL\_DBG\_SOCK\_WPARTIAL=80** means a send with 1000 bytes would only send 800. - CURL\_DBG\_QUIC\_WBLOCK The percentage of send() calls that should be answered with EAGAIN at random. QUIC only. - CURL\_DBG\_SOCK\_FAIL\_IPV6 Fail opening of sockets for the IPv6 address family. - CURL\_DEBUG Trace logging behavior as an alternative to calling *[curl\_global\_trace(3)](/curl_global_trace/3.md)*. Example: **CURL\_DEBUG=http/2** means trace details about HTTP/2 handling. In the curl command line tool, built with *--enable-debug*, this environment variable adds to arguments like *--verbose*, *-vvv*. At least a single *-v* is needed to make the run emit trace output, but when it does, the contents of *CURL\_DEBUG* are added and can override existing options. Example: **CURL\_DEBUG=tcp,-http/2 curl -vv url** means trace protocol details, triggered by *-vv*, add tracing of TCP in addition and remove tracing of HTTP/2. - CURL\_DEBUG\_SIZE Fake the size returned by CURLINFO\_HEADER\_SIZE and CURLINFO\_REQUEST\_SIZE. - CURL\_DNS\_SERVER When built with c-ares for name resolving, setting this environment variable to *\[IP:port\]* makes libcurl use that DNS server instead of the system default. This is used by the curl test suite. - CURL\_FTP\_PWD\_STOP When set, the first transfer - when using ftp: - returns before sending the *PWD* command and stop any further progress. This is used to test an edge case - CURL\_GETHOSTNAME Fake the local machine's unqualified hostname for NTLM and SMTP. - CURL\_HSTS\_HTTP Bypass the HSTS HTTPS protocol restriction if this variable exists. - CURL\_FORCETIME A time of 0 is used for AWS signatures and NTLM if this variable exists. - 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. - CURL\_SIGPIPE\_DEBUG When present, *curl* does not set *SIGPIPE* to ignore. This allows verification that *libcurl* does not cause *SIGPIPE* to be raised. - CURL\_SMALLREQSEND An alternative size of HTTP data to be sent at a time only if smaller than the current. - CURL\_SMALLSENDS An alternative size of socket data to be sent at a time only if smaller than the current. - 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. - 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. - CURL\_OPENLDAP\_TRACE OpenLDAP tracing is enabled if this variable exists and its value is 1 or greater. There is a number of debug levels, refer to *openldap.c* comments. - CURL\_WS\_CHUNK\_SIZE Used to influence the buffer chunk size used for WebSocket encoding and decoding. - CURL\_WS\_CHUNK\_EAGAIN Used to simulate blocking sends after this chunk size for WebSocket connections. - CURL\_WS\_FORCE\_ZERO\_MASK Used to set the bitmask of all sent WebSocket frames to zero. The value of the environment variable does not matter. - CURL\_FORBID\_REUSE Used to set the CURLOPT\_FORBID\_REUSE flag on each transfer initiated by the curl command line tool. The value of the environment variable does not matter. - CURL\_GRACEFUL\_SHUTDOWN Make a blocking, graceful shutdown of all remaining connections when a multi handle is destroyed. This implicitly triggers for easy handles that are run via easy\_perform. The value of the environment variable gives the shutdown timeout in milliseconds. - CURL\_DBG\_HE\_AAAA\_AWAIT\_MS Overrides the time delaying a connect for AAAA resolve results to arrive before continuing with Happy Eyeballing. - CURL\_DBG\_RESOLV\_MAX\_THREADS Overrides the maximum number of threads for resolver. - CURL\_DBG\_RESOLV\_DELAY Makes ever threaded resolve experience an initial delay in milliseconds. - CURL\_DBG\_RESOLV\_FAIL\_DELAY With a threaded resolver, delay each lookup by the given milliseconds and fail it, as if a transient resolver failure happened. - CURL\_DBG\_RESOLV\_FAIL\_NEGATIVE With a threaded resolver, make a lookup failing via *CURL\_DBG\_RESOLV\_FAIL\_DELAY* count as an authoritative negative answer, eligible for negative DNS caching, instead of a transient failure. - CURL\_DBG\_RESOLV\_FAIL\_IPV6 Make libcurl fail a resolve for IPv6 only. - CURL\_DBG\_THRDPOOL\_FAIL\_STARTS Fail this many thread starts in a thread pool, as if the system refused to spawn more threads. Read when the pool is created. - CURL\_QUICK\_EXIT Make *curl* use the quick exit option, even when built in debug mode. - CURL\_DBG\_AWAIT\_HTTPSRR When happy eyeballing for https: wait for the HTTPS-RR resolve answer to arrive before starting any connect attempt. - CURL\_DBG\_NO\_USE\_SSL\_ON\_FIRST When passing *--ssl-reqd*, clear it for the first URL in a curl command. This allows testing of connection reuse in mixed *STARTTLS* needs. - CURL\_DBG\_SUPPRESS\_CONNECT\_HDS Existence of this variable suppresses the collection of CONNECT headers. - CURL\_DBG\_MAX\_TOTAL\_CONNECTIONS Set the *max\_total\_connections* for a *multi* handle. - CURL\_DBG\_FTP\_WILDCARD Simulate CURLOPT\_WILDCARDMATCH being set. ## SEE ALSO [**libcurl-env**(3)](/libcurl-env/3.md)