mirror of
https://github.com/curl/curl.git
synced 2024-12-27 06:59:43 +08:00
122 lines
4.8 KiB
Groff
122 lines
4.8 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" * SPDX-License-Identifier: curl
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.TH curl_global_init 3 "11 May 2004" "libcurl" "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's 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 EXAMPLE
|
|
.nf
|
|
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_global_init_mem "(3), "
|
|
.BR curl_global_cleanup "(3), "
|
|
.BR curl_global_sslset "(3), "
|
|
.BR curl_easy_init "(3), "
|
|
.BR libcurl "(3), "
|
|
.BR curl_global_trace "(3), "
|