docs/libcurl/curl_global_init.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, 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 \fBlibcurl(3)\fP of global environment requirements for
  58 details of how to use this function.
  59
  60 .SH FLAGS
  61 .TP 5
  62 .B CURL_GLOBAL_ALL
  63 Initialize everything possible. This sets all known bits except
  64 \fBCURL_GLOBAL_ACK_EINTR\fP.
  65 .TP
  66 .B CURL_GLOBAL_SSL
  67 Initialize SSL
  68 .TP
  69 .B CURL_GLOBAL_WIN32
  70 Initialize the Win32 socket libraries.
  71 .TP
  72 .B CURL_GLOBAL_NOTHING
  73 Initialise nothing extra. This sets no bit.
  74 .TP
  75 .B CURL_GLOBAL_DEFAULT
  76 A sensible default. It will init both SSL and Win32. Right now, this equals
  77 the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
  78 .TP
  79 .B CURL_GLOBAL_ACK_EINTR
  80 When this flag is set, curl will acknowledge EINTR condition when connecting
  81 or when waiting for data.  Otherwise, curl waits until full timeout
  82 elapses. (Added in 7.30.0)
  83 .SH RETURN VALUE
  84 If this function returns non-zero, something went wrong and you cannot use the
  85 other curl functions.
  86 .SH "SEE ALSO"
  87 .BR curl_global_init_mem "(3), "
  88 .BR curl_global_cleanup "(3), "
  89 .BR curl_easy_init "(3) "
  90 .BR libcurl "(3) "