aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl/libcurl.3
diff options
context:
space:
mode:
Diffstat (limited to 'docs/libcurl/libcurl.3')
-rw-r--r--docs/libcurl/libcurl.3100
1 files changed, 46 insertions, 54 deletions
diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3
index 809375948..39bcccd43 100644
--- a/docs/libcurl/libcurl.3
+++ b/docs/libcurl/libcurl.3
@@ -148,18 +148,16 @@ the library code. For example, when libcurl is built for SSL
capability via the GNU TLS library, there is an elaborate tree inside
that library that describes the SSL protocol.
-\fIcurl_global_init()\fP is the function that you must call. This may
-allocate resources (e.g. the memory for the GNU TLS tree mentioned
-above), so the companion function \fIcurl_global_cleanup()\fP releases
-them.
-
-The basic rule for constructing a program that uses libcurl is this:
-Call \fIcurl_global_init()\fP, with a \fICURL_GLOBAL_ALL\fP argument,
-immediately after the program starts, while it is still only one
-thread and before it uses libcurl at all. Call
-\fIcurl_global_cleanup()\fP immediately before the program exits, when
-the program is again only one thread and after its last use of
-libcurl.
+\fIcurl_global_init(3)\fP is the function that you must call. This may
+allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
+the companion function \fIcurl_global_cleanup(3)\fP releases them.
+
+The basic rule for constructing a program that uses libcurl is this: Call
+\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
+after the program starts, while it is still only one thread and before it uses
+libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the
+program exits, when the program is again only one thread and after its last
+use of libcurl.
You can call both of these multiple times, as long as all calls meet
these requirements and the number of calls to each is the same.
@@ -184,48 +182,42 @@ your code doesn't know about other parts of the program -- it doesn't
know whether they use libcurl or not. And its code doesn't necessarily
run at the start and end of the whole program.
-A module like this must have global constant functions of its own,
-just like \fIcurl_global_init()\fP and \fIcurl_global_cleanup()\fP.
-The module thus has control at the beginning and end of the program
-and has a place to call the libcurl functions. Note that if multiple
-modules in the program use libcurl, they all will separately call the
-libcurl functions, and that's OK because only the first
-\fIcurl_global_init()\fP and the last \fIcurl_global_cleanup()\fP in a
-program change anything. (libcurl uses a reference count in static
-memory).
-
-In a C++ module, it is common to deal with the global constant
-situation by defining a special class that represents the global
-constant environment of the module. A program always has exactly one
-object of the class, in static storage. That way, the program
-automatically calls the constructor of the object as the program
-starts up and the destructor as it terminates. As the author of this
-libcurl-using module, you can make the constructor call
-\fIcurl_global_init()\fP and the destructor call
-\fIcurl_global_cleanup()\fP and satisfy libcurl's requirements without
-your user having to think about it.
-
-\fIcurl_global_init()\fP has an argument that tells what particular
-parts of the global constant environment to set up. In order to
-successfully use any value except \fICURL_GLOBAL_ALL\fP (which says to
-set up the whole thing), you must have specific knowledge of internal
-workings of libcurl and all other parts of the program of which it is
-part.
-
-A special part of the global constant environment is the identity of
-the memory allocator. \fIcurl_global_init()\fP selects the system
-default memory allocator, but you can use \fIcurl_global_init_mem()\fP
-to supply one of your own. However, there is no way to use
-\fIcurl_global_init_mem()\fP in a modular program -- all modules in
-the program that might use libcurl would have to agree on one
-allocator.
-
-There is a failsafe in libcurl that makes it usable in simple
-situations without you having to worry about the global constant
-environment at all: \fIcurl_easy_init()\fP sets up the environment
-itself if it hasn't been done yet. The resources it acquires to do so
-get released by the operating system automatically when the program
-exits.
+A module like this must have global constant functions of its own, just like
+\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
+has control at the beginning and end of the program and has a place to call
+the libcurl functions. Note that if multiple modules in the program use
+libcurl, they all will separately call the libcurl functions, and that's OK
+because only the first \fIcurl_global_init(3)\fP and the last
+\fIcurl_global_cleanup(3)\fP in a program change anything. (libcurl uses a
+reference count in static memory).
+
+In a C++ module, it is common to deal with the global constant situation by
+defining a special class that represents the global constant environment of
+the module. A program always has exactly one object of the class, in static
+storage. That way, the program automatically calls the constructor of the
+object as the program starts up and the destructor as it terminates. As the
+author of this libcurl-using module, you can make the constructor call
+\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
+and satisfy libcurl's requirements without your user having to think about it.
+
+\fIcurl_global_init(3)\fP has an argument that tells what particular parts of
+the global constant environment to set up. In order to successfully use any
+value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
+must have specific knowledge of internal workings of libcurl and all other
+parts of the program of which it is part.
+
+A special part of the global constant environment is the identity of the
+memory allocator. \fIcurl_global_init(3)\fP selects the system default memory
+allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
+own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
+modular program -- all modules in the program that might use libcurl would
+have to agree on one allocator.
+
+There is a failsafe in libcurl that makes it usable in simple situations
+without you having to worry about the global constant environment at all:
+\fIcurl_easy_init(3)\fP sets up the environment itself if it hasn't been done
+yet. The resources it acquires to do so get released by the operating system
+automatically when the program exits.
This failsafe feature exists mainly for backward compatibility because
there was a time when the global functions didn't exist. Because it