un-nest curl

curl-8.15.0/docs/libcurl/libcurl-thread.3

@@ -0,0 +1,90 @@
+.\" generated by cd2nroff 0.1 from libcurl-thread.md
+.TH libcurl-thread 3 "2025-08-14" libcurl
+.SH NAME
+libcurl\-thread \- libcurl thread safety
+.SH 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.
+.SH Handles
+You must \fBnever\fP 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.
+.SH Shared objects
+You can share certain data between multiple handles by using the share
+interface but you must provide your own locking and set
+\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
+
+Note that some items are specifically documented as not thread\-safe in the
+share API (the connection pool and HSTS cache for example).
+.SH TLS
+All current TLS libraries libcurl supports are thread\-safe.
+.IP 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. For older versions of
+OpenSSL, the user must set mutex callbacks.
+
+libcurl may not be able to fully clean up after multi\-threaded OpenSSL
+depending on how OpenSSL was built and loaded as a library. It is possible in
+some rare circumstances a memory leak could occur unless you implement your own
+OpenSSL thread cleanup.
+
+For example, on Windows if both libcurl and OpenSSL are linked statically to a
+DLL or application then OpenSSL may leak memory unless the DLL or application
+calls OPENSSL_thread_stop() before each thread terminates. If OpenSSL is built
+as a DLL then it does this cleanup automatically and there is no leak. If
+libcurl is built as a DLL and OpenSSL is linked statically to it then libcurl
+does this cleanup automatically and there is no leak (added in libcurl 8.8.0).
+
+Please review the OpenSSL documentation for a full list of circumstances:
+https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/#notes
+.SH Signals
+Signals are used for timing out name resolves (during DNS lookup) \- when built
+without using either the c\-ares or threaded resolver backends. On systems that
+have a signal concept.
+
+When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP
+option to 1L for all handles. Everything works fine except that timeouts
+cannot be honored during DNS lookups \- 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 cannot
+function properly multi\-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
+is set.
+
+When \fICURLOPT_NOSIGNAL(3)\fP 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 \fICURLOPT_NOSIGNAL(3)\fP to 0L does not work in a
+threaded situation as there is a race condition where libcurl risks restoring
+the former signal handler while another thread should still ignore it.
+.SH Name resolving
+The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system
+calls used by libcurl are provided by your operating system and must be thread
+safe. It is important that libcurl can find and use thread safe versions of
+these and other system calls, as otherwise it cannot 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.
+.SH curl_global_* functions
+These functions are thread\-safe since libcurl 7.84.0 if
+\fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit
+set (most platforms).
+
+If these functions are not thread\-safe and you are using libcurl with multiple
+threads it is especially important that before use you call
+\fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly
+initialize the library and its dependents, rather than rely on the "lazy"
+fail\-safe initialization that takes place the first time
+\fIcurl_easy_init(3)\fP is called. For an in\-depth explanation refer to
+\fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP.
+.SH Memory functions
+These functions, provided either by your operating system or your own
+replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP
+to set your own replacement memory functions.
+.SH Non-safe functions
+\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread\-safe.
+
+\fIcurl_version_info(3)\fP is not thread\-safe before libcurl initialization.
+.SH SEE ALSO
+.BR libcurl-security (3)