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. +\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()\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. +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). +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()\fP and the destructor call -\fIcurl_global_cleanup()\fP and satisfy libcurl's requirements without -your user having to think about it. +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()\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. +\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()\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. +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()\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. +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