1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_global_trace 5Section: 3 6Source: libcurl 7See-also: 8 - curl_global_init (3) 9 - libcurl (3) 10--- 11 12# NAME 13 14curl_global_trace - Global libcurl logging configuration 15 16# SYNOPSIS 17 18~~~c 19#include <curl/curl.h> 20 21CURLcode curl_global_trace(const char *config); 22~~~ 23 24# DESCRIPTION 25 26This function configures the logging behavior, allowing to make some 27parts of curl more verbose or silent than others. 28 29This function may be called during the initialization phase of a program. It 30does not have to be. It can be called several times even, possibly overwriting 31settings of previous calls. 32 33Calling this function after transfers have been started is undefined. On 34some platforms/architectures it might take effect, on others not. 35 36This function is thread-safe since libcurl 8.3.0 if 37curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set 38(most platforms). 39 40If this is not thread-safe, you must not call this function when any other 41thread in the program (i.e. a thread sharing the same memory) is running. 42This does not just mean no other thread that is using libcurl. Because 43curl_global_init(3) may call functions of other libraries that are 44similarly thread unsafe, it could conflict with any other thread that uses 45these other libraries. 46 47If you are initializing libcurl from a Windows DLL you should not initialize 48it from *DllMain* or a static initializer because Windows holds the loader 49lock during that time and it could cause a deadlock. 50 51The *config* string is a list of comma-separated component names. Names 52are case-insensitive and unknown names are ignored. The special name "all" 53applies to all components. Names may be prefixed with '+' or '-' to enable 54or disable detailed logging for a component. 55 56The list of component names is not part of curl's public API. Names may be 57added or disappear in future versions of libcurl. Since unknown names are 58silently ignored, outdated log configurations does not cause errors when 59upgrading libcurl. Given that, some names can be expected to be fairly stable 60and are listed below for easy reference. 61 62Note that log configuration applies only to transfers where debug logging 63is enabled. See CURLOPT_VERBOSE(3) or CURLOPT_DEBUGFUNCTION(3) 64on how to control that. 65 66# TRACE COMPONENTS 67 68## tcp 69 70Tracing of TCP socket handling: connect, reads, writes. 71 72## ssl 73 74Tracing of SSL/TLS operations, whichever SSL backend is used in your build. 75 76## http/2 77 78Details about HTTP/2 handling: frames, events, I/O, etc. 79 80## http/3 81 82Details about HTTP/3 handling: connect, frames, events, I/O etc. 83 84## http-proxy 85 86Involved when transfers are tunneled through an HTTP proxy. "h1-proxy" or 87"h2-proxy" are also involved, depending on the HTTP version negotiated with 88the proxy. 89 90In order to find out all components involved in a transfer, run it with "all" 91configured. You can then see all names involved in your libcurl version in the 92trace. 93 94# EXAMPLE 95 96~~~c 97int main(void) 98{ 99 /* log details of HTTP/2 and SSL handling */ 100 curl_global_trace("http/2,ssl"); 101 102 /* log all details, except SSL handling */ 103 curl_global_trace("all,-ssl"); 104} 105~~~ 106 107Below is a trace sample where "http/2" was configured. The trace output 108of an enabled component appears at the beginning in brackets. 109~~~ 110* [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/ 111... 112* [HTTP/2] [h2sid=1] FRAME[HEADERS] 113* [HTTP/2] [h2sid=1] 249 header bytes 114... 115~~~ 116 117# AVAILABILITY 118 119Added in 8.3 120 121# RETURN VALUE 122 123If this function returns non-zero, something went wrong and the configuration 124may not have any effects or may only been applied partially. 125