libcurl-thread.3 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121
  1. .\" **************************************************************************
  2. .\" * _ _ ____ _
  3. .\" * Project ___| | | | _ \| |
  4. .\" * / __| | | | |_) | |
  5. .\" * | (__| |_| | _ <| |___
  6. .\" * \___|\___/|_| \_\_____|
  7. .\" *
  8. .\" * Copyright (C) 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.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. .\" * SPDX-License-Identifier: curl
  22. .\" *
  23. .\" **************************************************************************
  24. .\"
  25. .TH libcurl-thread 3 "13 Jul 2015" "libcurl" "libcurl"
  26. .SH NAME
  27. libcurl-thread \- libcurl thread safety
  28. .SH "Multi-threading with libcurl"
  29. libcurl is thread safe but has no internal thread synchronization. You may have
  30. to provide your own locking should you meet any of the thread safety exceptions
  31. below.
  32. .SH "Handles"
  33. You must \fBnever\fP share the same handle in multiple threads. You can pass
  34. the handles around among threads, but you must never use a single handle from
  35. more than one thread at any given time.
  36. .SH "Shared objects"
  37. You can share certain data between multiple handles by using the share
  38. interface but you must provide your own locking and set
  39. \fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
  40. Note that some items are specifically documented as not thread-safe in the
  41. share API (the connection pool and HSTS cache for example).
  42. .SH TLS
  43. If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
  44. then of course using the underlying SSL library multi-threaded and those libs
  45. might have their own requirements on this issue. You may need to provide one
  46. or two functions to allow it to function properly:
  47. .IP OpenSSL
  48. OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that
  49. support for the underlying OS threading API is built-in." In that case the
  50. engine is used by libcurl in a way that is fully thread-safe.
  51. https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION
  52. OpenSSL <= 1.0.2 the user must set callbacks.
  53. https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION
  54. https://curl.se/libcurl/c/opensslthreadlock.html
  55. .IP GnuTLS
  56. https://gnutls.org/manual/html_node/Thread-safety.html
  57. .IP NSS
  58. thread-safe already without anything required.
  59. .IP Secure-Transport
  60. The engine is used by libcurl in a way that is fully thread-safe.
  61. .IP Schannel
  62. The engine is used by libcurl in a way that is fully thread-safe.
  63. .IP wolfSSL
  64. The engine is used by libcurl in a way that is fully thread-safe.
  65. .IP BoringSSL
  66. The engine is used by libcurl in a way that is fully thread-safe.
  67. .IP AWS-LC
  68. The engine is used by libcurl in a way that is fully thread-safe.
  69. .SH "Signals"
  70. Signals are used for timing out name resolves (during DNS lookup) - when built
  71. without using either the c-ares or threaded resolver backends. When using
  72. multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for
  73. all handles. Everything will or might work fine except that timeouts are not
  74. honored during the DNS lookup - which you can work around by building libcurl
  75. with c-ares or threaded-resolver support. c-ares is a library that provides
  76. asynchronous name resolves. On some platforms, libcurl simply will not
  77. function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
  78. is set.
  79. When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal
  80. with the risk of a SIGPIPE (that at least the OpenSSL backend can
  81. trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a
  82. threaded situation as there will be race where libcurl risks restoring the
  83. former signal handler while another thread should still ignore it.
  84. .SH "Name resolving"
  85. The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system
  86. calls used by libcurl are provided by your operating system and must be thread
  87. safe. It is important that libcurl can find and use thread safe versions of
  88. these and other system calls, as otherwise it cannot function fully thread
  89. safe. Some operating systems are known to have faulty thread
  90. implementations. We have previously received problem reports on *BSD (at least
  91. in the past, they may be working fine these days). Some operating systems that
  92. are known to have solid and working thread support are Linux, Solaris and
  93. Windows.
  94. .SH "curl_global_* functions"
  95. These functions are thread-safe since libcurl 7.84.0 if
  96. \fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit
  97. set (most platforms).
  98. If these functions are not thread-safe and you are using libcurl with multiple
  99. threads it is especially important that before use you call
  100. \fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly
  101. initialize the library and its dependents, rather than rely on the "lazy"
  102. fail-safe initialization that takes place the first time
  103. \fIcurl_easy_init(3)\fP is called. For an in-depth explanation refer to
  104. \fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP.
  105. .SH "Memory functions"
  106. These functions, provided either by your operating system or your own
  107. replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP
  108. to set your own replacement memory functions.
  109. .SH "Non-safe functions"
  110. \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.
  111. \fIcurl_version_info(3)\fP is not thread-safe before libcurl initialization.