aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl/curl_global_init.3
diff options
context:
space:
mode:
Diffstat (limited to 'docs/libcurl/curl_global_init.3')
-rw-r--r--docs/libcurl/curl_global_init.334
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) "