Bryan Henderson turned the 'initialized' variable for curl_global_init()

into a counter, and thus you can now do multiple curl_global_init() and you
are then supposed to do the same amount of calls to curl_global_cleanup().
Bryan also updated the docs accordingly.

1 files changed, 22 insertions, 12 deletions

diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3
index 8e8ec09f4..0729ef787 100644
--- a/docs/libcurl/curl_global_init.3
+++ b/docs/libcurl/curl_global_init.3
@@ -11,22 +11,31 @@ curl_global_init - Global libcurl initialisation
 .BI "CURLcode curl_global_init(long " flags ");"
 .ad
 .SH DESCRIPTION
-This function should only be called once (no matter how many threads or
-libcurl sessions that'll be used) by every application that uses libcurl.
+This function sets up the program environment that libcurl needs.  Think
+of it as an extension of the library loader.
 
-If this function hasn't been invoked when \fIcurl_easy_init(3)\fP is called,
-it will be done automatically by libcurl. It is adviced that you do not rely
-on this automatic call, but instead call \fIcurl_global_init(3)\fP properly.
+This function must be called at least once within a program (a program is
+all the code that shares a memory space) before the program calls any other
+function in libcurl.  The environment it sets up is constant for the life
+of the program and is the same for every program, so multiple calls have
+the same effect as one call.
 
-The flags option is a bit pattern that tells libcurl exact what features to
+The flags option is a bit pattern that tells libcurl exactly what features to
 init, as described below. Set the desired bits by ORing the values together.
+In normal operation, you must specify CURL_GLOBAL_ALL.  Don't use any other
+value unless you are familiar with and mean to control internal operations
+of libcurl.
 
-You must however \fBalways\fP use the \fIcurl_global_cleanup(3)\fP function,
-as that cannot be called automatically for you by libcurl.
+\fBThis function is not thread safe.\fP  You must not call it when any
+other thread in the program (i.e. a thread sharing the same memory) is
+running.  This doesn't just mean no other thread that is using
+libcurl.  Because \fIcurl_global_init()\fP calls functions of other
+libraries that are similarly thread unsafe, it could conflict with any
+other thread that uses these other libraries.
+
+See the description in \fBlibcurl\fP(3) of global environment
+requirements for details of how to use this function.
 
-Calling this function more than once will cause unpredictable results. If that
-is not enough, calling this function from more than one thread may also cause
-unpredictable results.
 .SH FLAGS
 .TP 5
 .B CURL_GLOBAL_ALL
@@ -46,4 +55,5 @@ other curl functions.
 .SH "SEE ALSO"
 .BR curl_global_init_mem "(3), "
 .BR curl_global_cleanup "(3), "
-.BR curl_easy_init "(3) "
\ No newline at end of file
+.BR curl_easy_init "(3) "
+.BR libcurl "(3) "