libcurl-thread.3: Revert to stricter handle wording

.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

.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.