docs/libcurl/curl_global_init.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .TH curl_global_init 3 "January 24, 2018" "libcurl 7.59.0" "libcurl Manual"
  23
  24 .SH NAME
  25 curl_global_init - Global libcurl initialisation
  26 .SH SYNOPSIS
  27 .B #include <curl/curl.h>
  28 .sp
  29 .BI "CURLcode curl_global_init(long " flags ");"
  30 .ad
  31 .SH DESCRIPTION
  32 This function sets up the program environment that libcurl needs.  Think of it
  33 as an extension of the library loader.
  34
  35 This function must be called at least once within a program (a program is all
  36 the code that shares a memory space) before the program calls any other
  37 function in libcurl.  The environment it sets up is constant for the life of
  38 the program and is the same for every program, so multiple calls have the same
  39 effect as one call.
  40
  41 The flags option is a bit pattern that tells libcurl exactly what features to
  42 init, as described below. Set the desired bits by ORing the values together.
  43 In normal operation, you must specify CURL_GLOBAL_ALL.  Don't use any other
  44 value unless you are familiar with it and mean to control internal operations of
  45 libcurl.
  46
  47 \fBThis function is not thread safe.\fP You must not call it when any other
  48 thread in the program (i.e. a thread sharing the same memory) is running.
  49 This doesn't just mean no other thread that is using libcurl.  Because
  50 \fIcurl_global_init(3)\fP calls functions of other libraries that are
  51 similarly thread unsafe, it could conflict with any other thread that uses
  52 these other libraries.
  53
  54 If you are initializing libcurl from a Windows DLL you should not initialize it
  55 from DllMain or a static initializer because Windows holds the loader lock
  56 during that time and it could cause a deadlock.
  57
  58 See the description in \fIlibcurl(3)\fP of global environment requirements for
  59 details of how to use this function.
  60 .SH FLAGS
  61 .IP CURL_GLOBAL_ALL
  62 Initialize everything possible. This sets all known bits except
  63 \fBCURL_GLOBAL_ACK_EINTR\fP.
  64
  65 .IP CURL_GLOBAL_SSL
  66 (This flag's presence or absence serves no meaning since 7.57.0. The
  67 description below is for older libcurl versions.)
  68
  69 Initialize SSL.
  70
  71 The implication here is that if this bit is not set, the initialization of the
  72 SSL layer needs to be done by the application or at least outside of
  73 libcurl. The exact procedure how to do SSL initializtion depends on the TLS
  74 backend libcurl uses.
  75
  76 Doing TLS based transfers without having the TLS layer initialized may lead to
  77 unexpected behaviors.
  78 .IP CURL_GLOBAL_WIN32
  79 Initialize the Win32 socket libraries.
  80
  81 The implication here is that if this bit is not set, the initialization of
  82 winsock has to be done by the application or you risk getting undefined
  83 behaviors. This option exists for when the initialization is handled outside
  84 of libcurl so there's no need for libcurl to do it again.
  85 .IP CURL_GLOBAL_NOTHING
  86 Initialise nothing extra. This sets no bit.
  87 .IP CURL_GLOBAL_DEFAULT
  88 A sensible default. It will init both SSL and Win32. Right now, this equals
  89 the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
  90 .IP CURL_GLOBAL_ACK_EINTR
  91 When this flag is set, curl will acknowledge EINTR condition when connecting
  92 or when waiting for data.  Otherwise, curl waits until full timeout
  93 elapses. (Added in 7.30.0)
  94 .SH RETURN VALUE
  95 If this function returns non-zero, something went wrong and you cannot use the
  96 other curl functions.
  97 .SH "SEE ALSO"
  98 .BR curl_global_init_mem "(3), "
  99 .BR curl_global_cleanup "(3), "
 100 .BR curl_global_sslset "(3), "
 101 .BR curl_easy_init "(3) "
 102 .BR libcurl "(3) "