Return to libcurl-thread.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

curl

    1: .\" **************************************************************************
    2: .\" *                                  _   _ ____  _
    3: .\" *  Project                     ___| | | |  _ \| |
    4: .\" *                             / __| | | | |_) | |
    5: .\" *                            | (__| |_| |  _ <| |___
    6: .\" *                             \___|\___/|_| \_\_____|
    7: .\" *
    8: .\" * Copyright (C) 2015 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
    9: .\" *
   10: .\" * This software is licensed as described in the file COPYING, which
   11: .\" * you should have received as part of this distribution. The terms
   12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
   13: .\" *
   14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
   15: .\" * copies of the Software, and permit persons to whom the Software is
   16: .\" * furnished to do so, under the terms of the COPYING file.
   17: .\" *
   18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
   19: .\" * KIND, either express or implied.
   20: .\" *
   21: .\" **************************************************************************
   22: .\"
   23: .TH libcurl-thread 3 "June 30, 2019" "libcurl 7.70.0" "libcurl thread safety"
   24: 
   25: .SH NAME
   26: libcurl-thread \- libcurl thread safety
   27: .SH "Multi-threading with libcurl"
   28: libcurl is thread safe but has no internal thread synchronization. You may have
   29: to provide your own locking should you meet any of the thread safety exceptions
   30: below.
   31: 
   32: \fBHandles.\fP You must \fBnever\fP share the same handle in multiple threads.
   33: You can pass the handles around among threads, but you must never use a single
   34: handle from more than one thread at any given time.
   35: 
   36: \fBShared objects.\fP You can share certain data between multiple handles by
   37: using the share interface but you must provide your own locking and set
   38: \fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
   39: .SH TLS
   40: If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
   41: then of course using the underlying SSL library multi-threaded and those libs
   42: might have their own requirements on this issue.  You may need to provide one
   43: or two functions to allow it to function properly:
   44: .IP OpenSSL
   45: OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that
   46: support for the underlying OS threading API is built-in." In that case the
   47: engine is used by libcurl in a way that is fully thread-safe.
   48: 
   49: https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION
   50: 
   51: OpenSSL <= 1.0.2 the user must set callbacks.
   52: 
   53: https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION
   54: 
   55: https://curl.haxx.se/libcurl/c/opensslthreadlock.html
   56: 
   57: .IP GnuTLS
   58: https://gnutls.org/manual/html_node/Thread-safety.html
   59: .IP NSS
   60: thread-safe already without anything required.
   61: .IP Secure-Transport
   62: The engine is used by libcurl in a way that is fully thread-safe.
   63: .IP WinSSL
   64: The engine is used by libcurl in a way that is fully thread-safe.
   65: .IP wolfSSL
   66: The engine is used by libcurl in a way that is fully thread-safe.
   67: .IP BoringSSL
   68: The engine is used by libcurl in a way that is fully thread-safe.
   69: .SH "Other areas of caution"
   70: .IP Signals
   71: Signals are used for timing out name resolves (during DNS lookup) - when built
   72: without using either the c-ares or threaded resolver backends. When using
   73: multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for
   74: all handles. Everything will or might work fine except that timeouts are not
   75: honored during the DNS lookup - which you can work around by building libcurl
   76: with c-ares or threaded-resolver support. c-ares is a library that provides
   77: asynchronous name resolves. On some platforms, libcurl simply will not
   78: function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
   79: is set.
   80: 
   81: When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal
   82: with the risk of a SIGPIPE (that at least the OpenSSL backend can
   83: trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a
   84: threaded situation as there will be race where libcurl risks restoring the
   85: former signal handler while another thread should still ignore it.
   86: .IP "Name resolving"
   87: \fBgethostby* functions and other system calls.\fP These functions, provided
   88: by your operating system, must be thread safe. It is very important that
   89: libcurl can find and use thread safe versions of these and other system calls,
   90: as otherwise it can't function fully thread safe. Some operating systems are
   91: known to have faulty thread implementations. We have previously received
   92: problem reports on *BSD (at least in the past, they may be working fine these
   93: days).  Some operating systems that are known to have solid and working thread
   94: support are Linux, Solaris and Windows.
   95: .IP "curl_global_* functions"
   96: These functions are not thread safe. If you are using libcurl with multiple
   97: threads it is especially important that before use you call
   98: \fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly
   99: initialize the library and its dependents, rather than rely on the "lazy"
  100: fail-safe initialization that takes place the first time
  101: \fIcurl_easy_init(3)\fP is called. For an in-depth explanation refer to
  102: \fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP.
  103: .IP "Memory functions"
  104: These functions, provided either by your operating system or your own
  105: replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP
  106: to set your own replacement memory functions.
  107: .IP "Non-safe functions"
  108: \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.