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       Secure-Transport
53              The engine is used by libcurl in a way  that  is  fully  thread-
54              safe.
55
56       WinSSL The  engine  is  used  by libcurl in a way that is fully thread-
57              safe.
58
59       wolfSSL
60              The engine is used by libcurl in a way  that  is  fully  thread-
61              safe.
62
63       BoringSSL
64              The  engine  is  used  by libcurl in a way that is fully thread-
65              safe.
66

Other areas of caution

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