focal (3) libcurl-thread.3.gz

NAME

       libcurl-thread - libcurl thread safety

Multi-threading with libcurl

       libcurl  is  thread  safe  but  has  no internal thread synchronization. You may have to provide your own
       locking should you meet any of the thread safety exceptions below.

       Handles. You must never share the same handle in multiple threads.  You can pass the handles around among
       threads, but you must never use a single handle from more than one thread at any given time.

       Shared  objects. You can share certain data between multiple handles by using the share interface but you
       must provide your own locking and set curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.

TLS

       If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are  then  of  course  using  the
       underlying  SSL  library  multi-threaded  and those libs might have their own requirements on this issue.
       You may need to provide one or two functions to allow it to function properly:

       OpenSSL
              OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that  support  for  the
              underlying OS threading API is built-in." In that case the engine is used by libcurl in a way that
              is fully thread-safe.

              https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION

              OpenSSL <= 1.0.2 the user must set callbacks.

              https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION

              https://curl.haxx.se/libcurl/c/opensslthreadlock.html

       GnuTLS https://gnutls.org/manual/html_node/Thread-safety.html

       NSS    thread-safe already without anything required.

       Secure-Transport
              The engine is used by libcurl in a way that is fully thread-safe.

       WinSSL The engine is used by libcurl in a way that is fully thread-safe.

       wolfSSL
              The engine is used by libcurl in a way that is fully thread-safe.

       BoringSSL
              The engine is used by libcurl in a way that is fully thread-safe.

Other areas of caution

       Signals
              Signals are used for timing out name resolves (during DNS  lookup)  -  when  built  without  using
              either  the  c-ares  or threaded resolver backends. When using multiple threads you should set the
              CURLOPT_NOSIGNAL(3) option to 1L for all handles. Everything will or might work fine  except  that
              timeouts  are  not  honored  during the DNS lookup - which you can work around by building libcurl
              with c-ares or threaded-resolver support. c-ares is a  library  that  provides  asynchronous  name
              resolves.  On  some platforms, libcurl simply will not function properly multi-threaded unless the
              CURLOPT_NOSIGNAL(3) option is set.

              When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to deal with the risk of  a  SIGPIPE
              (that  at least the OpenSSL backend can trigger). Note that setting CURLOPT_NOSIGNAL(3) to 0L will
              not work in a threaded situation as there will be race where libcurl risks  restoring  the  former
              signal handler while another thread should still ignore it.

       Name resolving
              gethostby*  functions  and other system calls. These functions, provided by your operating system,
              must be thread safe. It is very important that libcurl can find and use thread  safe  versions  of
              these  and  other  system  calls, as otherwise it can't function fully thread safe. Some operating
              systems are known to have faulty thread  implementations.  We  have  previously  received  problem
              reports  on  *BSD  (at  least  in  the past, they may be working fine these days).  Some operating
              systems that are known to have solid and working thread support are Linux, Solaris and Windows.

       curl_global_* functions
              These functions are not thread safe. If  you  are  using  libcurl  with  multiple  threads  it  is
              especially  important  that  before use you call curl_global_init(3) or curl_global_init_mem(3) to
              explicitly initialize the library and its dependents, rather than rely  on  the  "lazy"  fail-safe
              initialization  that  takes  place  the  first  time  curl_easy_init(3) is called. For an in-depth
              explanation refer to libcurl(3) section GLOBAL CONSTANTS.

       Memory functions
              These functions, provided either by your operating system or your own replacements, must be thread
              safe. You can use curl_global_init_mem(3) to set your own replacement memory functions.

       Non-safe functions
              CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe.