1libcurl-thread(3)            libcurl thread safety           libcurl-thread(3)
2
3
4

NAME

6       libcurl-thread - libcurl thread safety
7

Multi-threading with libcurl

9       libcurl  is thread safe but has no internal thread synchronization. You
10       may have to provide your own locking should you meet any of the  thread
11       safety exceptions below.
12
13       Handles. You must never share the same handle in multiple threads.  You
14       can pass the handles around among threads, but you  must  never  use  a
15       single handle from more than one thread at any given time.
16
17       Shared  objects. You can share certain data between multiple handles by
18       using the share interface but you must provide your own locking and set
19       curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
20

TLS

22       If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you
23       are then of course using the underlying SSL library multi-threaded  and
24       those  libs  might  have  their own requirements on this issue. You may
25       need to provide one or two functions to allow it to function properly:
26
27       OpenSSL
28              OpenSSL 1.1.0+ "can be safely used  in  multi-threaded  applica‐
29              tions  provided that support for the underlying OS threading API
30              is built-in." In that case the engine is used by  libcurl  in  a
31              way that is fully thread-safe.
32
33              https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DE‐
34              SCRIPTION
35
36              OpenSSL <= 1.0.2 the user must set callbacks.
37
38              https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_lock‐
39              ing_callback.html#DESCRIPTION
40
41              https://curl.se/libcurl/c/opensslthreadlock.html
42
43
44       GnuTLS https://gnutls.org/manual/html_node/Thread-safety.html
45
46       NSS    thread-safe already without anything required.
47
48       Secure-Transport
49              The  engine  is  used  by libcurl in a way that is fully thread-
50              safe.
51
52       Schannel
53              The engine is used by libcurl in a way  that  is  fully  thread-
54              safe.
55
56       wolfSSL
57              The  engine  is  used  by libcurl in a way that is fully thread-
58              safe.
59
60       BoringSSL
61              The engine is used by libcurl in a way  that  is  fully  thread-
62              safe.
63

Other areas of caution

65       Signals
66              Signals  are  used  for  timing  out  name  resolves (during DNS
67              lookup) - when built without using either the c-ares or threaded
68              resolver  backends.  When  using multiple threads you should set
69              the CURLOPT_NOSIGNAL(3) option to 1L for all handles. Everything
70              will  or  might  work  fine except that timeouts are not honored
71              during the DNS lookup - which you can work  around  by  building
72              libcurl  with  c-ares  or threaded-resolver support. c-ares is a
73              library that provides asynchronous name resolves. On some  plat‐
74              forms,  libcurl simply will not function properly multi-threaded
75              unless the CURLOPT_NOSIGNAL(3) option is set.
76
77              When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to
78              deal with the risk of a SIGPIPE (that at least the OpenSSL back‐
79              end can trigger). Note that setting  CURLOPT_NOSIGNAL(3)  to  0L
80              will  not  work  in  a  threaded situation as there will be race
81              where libcurl risks restoring the former  signal  handler  while
82              another thread should still ignore it.
83
84       Name resolving
85              gethostby*  functions  and  other system calls. These functions,
86              provided by your operating system, must be thread  safe.  It  is
87              important  that libcurl can find and use thread safe versions of
88              these and other system calls, as otherwise  it  cannot  function
89              fully  thread  safe.  Some  operating  systems are known to have
90              faulty thread implementations. We have previously received prob‐
91              lem  reports  on *BSD (at least in the past, they may be working
92              fine these days). Some operating systems that are known to  have
93              solid and working thread support are Linux, Solaris and Windows.
94
95       curl_global_* functions
96              These   functions   are  thread-safe  since  libcurl  7.84.0  if
97              curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit
98              set (most platforms).
99
100              If these functions are not thread-safe and you are using libcurl
101              with multiple threads it is especially important that before use
102              you  call  curl_global_init(3) or curl_global_init_mem(3) to ex‐
103              plicitly initialize the library and its dependents, rather  than
104              rely on the "lazy" fail-safe initialization that takes place the
105              first time curl_easy_init(3) is called. For an in-depth explana‐
106              tion refer to libcurl(3) section GLOBAL CONSTANTS.
107
108       Memory functions
109              These  functions,  provided  either  by your operating system or
110              your  own  replacements,  must  be  thread  safe.  You  can  use
111              curl_global_init_mem(3) to set your own replacement memory func‐
112              tions.
113
114       Non-safe functions
115              CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe.
116
117
118
119libcurl 7.85.0                   June 15, 2022               libcurl-thread(3)