mirror of
https://codeberg.org/kiss-community/repo
synced 2024-11-20 05:30:11 -07:00
104 lines
3.8 KiB
Groff
104 lines
3.8 KiB
Groff
.\" generated by cd2nroff 0.1 from curl_global_init.md
|
|
.TH curl_global_init 3 libcurl
|
|
.SH NAME
|
|
curl_global_init \- Global libcurl initialization
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
CURLcode curl_global_init(long flags);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
This function sets up the program environment that libcurl needs. Think of it
|
|
as an extension of the library loader.
|
|
|
|
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 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. Do not use any other
|
|
value unless you are familiar with it and mean to control internal operations
|
|
of libcurl.
|
|
|
|
This function is thread\-safe since libcurl 7.84.0 if
|
|
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
|
|
(most platforms).
|
|
|
|
If this is not thread\-safe, you must not call this function when any other
|
|
thread in the program (i.e. a thread sharing the same memory) is running.
|
|
This does not just mean no other thread that is using libcurl. Because
|
|
\fIcurl_global_init(3)\fP calls functions of other libraries that are
|
|
similarly thread unsafe, it could conflict with any other thread that uses
|
|
these other libraries.
|
|
|
|
If you are initializing libcurl from a Windows DLL you should not initialize
|
|
it from \fIDllMain\fP or a static initializer because Windows holds the loader
|
|
lock during that time and it could cause a deadlock.
|
|
|
|
See the description in \fIlibcurl(3)\fP of global environment requirements for
|
|
details of how to use this function.
|
|
.SH FLAGS
|
|
.IP CURL_GLOBAL_ALL
|
|
Initialize everything possible. This sets all known bits except
|
|
\fBCURL_GLOBAL_ACK_EINTR\fP.
|
|
.IP CURL_GLOBAL_SSL
|
|
(This flag\(aqs presence or absence serves no meaning since 7.57.0. The
|
|
description below is for older libcurl versions.)
|
|
|
|
Initialize SSL.
|
|
|
|
The implication here is that if this bit is not set, the initialization of the
|
|
SSL layer needs to be done by the application or at least outside of
|
|
libcurl. The exact procedure how to do SSL initialization depends on the TLS
|
|
backend libcurl uses.
|
|
|
|
Doing TLS based transfers without having the TLS layer initialized may lead to
|
|
unexpected behaviors.
|
|
.IP CURL_GLOBAL_WIN32
|
|
Initialize the Win32 socket libraries.
|
|
|
|
The implication here is that if this bit is not set, the initialization of
|
|
winsock has to be done by the application or you risk getting undefined
|
|
behaviors. This option exists for when the initialization is handled outside
|
|
of libcurl so there is no need for libcurl to do it again.
|
|
.IP CURL_GLOBAL_NOTHING
|
|
Initialize nothing extra. This sets no bit.
|
|
.IP CURL_GLOBAL_DEFAULT
|
|
A sensible default. It initializes both SSL and Win32. Right now, this equals
|
|
the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
|
|
.IP CURL_GLOBAL_ACK_EINTR
|
|
This bit has no point since 7.69.0 but its behavior is instead the default.
|
|
|
|
Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when
|
|
connecting or when waiting for data. Otherwise, curl waits until full timeout
|
|
elapses. (Added in 7.30.0)
|
|
.SH PROTOCOLS
|
|
All
|
|
.SH EXAMPLE
|
|
.nf
|
|
int main(void)
|
|
{
|
|
curl_global_init(CURL_GLOBAL_DEFAULT);
|
|
|
|
/* use libcurl, then before exiting... */
|
|
|
|
curl_global_cleanup();
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Added in 7.8
|
|
.SH RETURN VALUE
|
|
If this function returns non\-zero, something went wrong and you cannot use the
|
|
other curl functions.
|
|
.SH SEE ALSO
|
|
.BR curl_easy_init (3),
|
|
.BR curl_global_cleanup (3),
|
|
.BR curl_global_init_mem (3),
|
|
.BR curl_global_sslset (3),
|
|
.BR curl_global_trace (3),
|
|
.BR libcurl (3)
|