Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
libcurl-thread(3)	     libcurl thread safety	     libcurl-thread(3)

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  applica-
	      tions  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#DE-
	      SCRIPTION

	      OpenSSL <= 1.0.2 the user	must set callbacks.

	      https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_lock-
	      ing_callback.html#DESCRIPTION

	      https://curl.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.

       Schannel
	      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	 plat-
	      forms,  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 back-
	      end 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 ver-
	      sions 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 work-
	      ing 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  ex-
	      plicitly	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 explana-
	      tion 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 func-
	      tions.

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

libcurl	7.78.0		       November	04, 2020	     libcurl-thread(3)

NAME | Multi-threading with libcurl | TLS | Other areas of caution

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libcurl-thread&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help