docs/libcurl/curl_global_init.3

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