libcurl-thread.3: Revert to stricter handle wording

.. also update formatting and add WinSSL and wolfSSL to the SSL/TLS
handlers list.

1 files changed, 42 insertions, 33 deletions

diff --git a/docs/libcurl/libcurl-thread.3 b/docs/libcurl/libcurl-thread.3
index 155e4e34c..070b47a2b 100644
--- a/docs/libcurl/libcurl-thread.3
+++ b/docs/libcurl/libcurl-thread.3
@@ -24,21 +24,22 @@
 .SH NAME
 libcurl-thread \- libcurl thread safety
 .SH "Multi-threading Issues"
-libcurl is thread safe with the following exceptions:
+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.
 
-Do \fBNOT\fP use library functions to access or modify the same handle
-concurrently from multiple threads. If concurrent access to the same handle
-from multiple threads could be an issue then you must implement your own
-locking to ensure it won't happen.
+\fBHandles.\fP 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.
 
-Shared objects. You can share certain data between multiple handles by using
-the share interface but you must implement your own locking and set
+\fBShared objects.\fP 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.
 
-SSL/TLS handlers. 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:
+\fBSSL/TLS handlers.\fP 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:
 
 .RS
 .IP OpenSSL
@@ -69,30 +70,38 @@ provide one or two functions to allow it to function properly:
 
 .IP Secure-Transport
 
- The engine is fully thread-safe, and no additional steps are required.
+ The engine is used by libcurl in a way that is fully thread-safe.
+
+.IP WinSSL
+
+ The engine is used by libcurl in a way that is fully thread-safe.
+
+.IP wolfSSL
+
+ The engine is used by libcurl in a way that is fully thread-safe.
 .RE
 
-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 \fICURLOPT_NOSIGNAL(3)\fP option to 1
-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 support. c-ares is a library that provides asynchronous
-name resolves. On some platforms, libcurl simply will not function properly
-multi-threaded unless this option is set.
-
-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 \fIcurl_global_init(3)\fP to explicitly initialize the library and its
+\fBSignals.\fP 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
+\fICURLOPT_NOSIGNAL(3)\fP option to 1 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 support. c-ares is a
+library that provides asynchronous name resolves. On some platforms, libcurl
+simply will not function properly multi-threaded unless this option is set.
+
+\fBgethostby* functions and other system calls.\fP 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.
+
+\fBcurl_global_* functions.\fP These functions are not thread safe. If you are
+using libcurl with multiple threads it is especially important that before use
+you call \fIcurl_global_init(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.