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 applications
29              provided  that  support  for  the underlying OS threading API is
30              built-in."
31
32              https://www.openssl.org/docs/manmas‐
33              ter/crypto/threads.html#DESCRIPTION
34
35              OpenSSL <= 1.0.2 the user must set callbacks.
36
37              https://www.openssl.org/docs/man1.0.2/crypto/threads.html#DESCRIP‐
38              TION
39
40              https://curl.haxx.se/libcurl/c/opensslthreadlock.html
41
42
43       GnuTLS https://gnutls.org/manual/html_node/Thread-safety.html
44
45       NSS    thread-safe already without anything required.
46
47       PolarSSL
48              Required actions unknown.
49
50       yassl  Required actions unknown.
51
52       axTLS  Required actions unknown.
53
54       Secure-Transport
55              The engine is used by libcurl in a way  that  is  fully  thread-
56              safe.
57
58       WinSSL The  engine  is  used  by libcurl in a way that is fully thread-
59              safe.
60
61       wolfSSL
62              The engine is used by libcurl in a way  that  is  fully  thread-
63              safe.
64
65       BoringSSL
66              The  engine  is  used  by libcurl in a way that is fully thread-
67              safe.
68

Other areas of caution

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