1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_init 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_cleanup (3) 9 - curl_easy_duphandle (3) 10 - curl_easy_perform (3) 11 - curl_easy_reset (3) 12 - curl_global_init (3) 13 - curl_multi_init (3) 14Protocol: 15 - All 16--- 17 18# NAME 19 20curl_easy_init - Start a libcurl easy session 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27CURL *curl_easy_init(); 28~~~ 29 30# DESCRIPTION 31 32This function allocates and returns a CURL easy handle. Such a handle is used 33as input to other functions in the easy interface. This call must have a 34corresponding call to curl_easy_cleanup(3) when the operation is complete. 35 36The easy handle is used to hold and control a single network transfer. It is 37encouraged to reuse easy handles for repeated transfers. 38 39An alternative way to get a new easy handle is to duplicate an already 40existing one with curl_easy_duphandle(3), which has the upside that it gets 41all the options that were set in the source handle set in the new copy as 42well. 43 44If you did not already call curl_global_init(3) before calling this function, 45curl_easy_init(3) does it automatically. This may be lethal in multi-threaded 46cases, if curl_global_init(3) is not thread-safe in your system, and it may 47then result in resource problems because there is no corresponding cleanup. 48 49You are strongly advised to not allow this automatic behavior, by calling 50curl_global_init(3) yourself properly. See the description in libcurl(3) of 51global environment requirements for details of how to use this function. 52 53# EXAMPLE 54 55~~~c 56int main(void) 57{ 58 CURL *curl = curl_easy_init(); 59 if(curl) { 60 CURLcode res; 61 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 62 res = curl_easy_perform(curl); 63 curl_easy_cleanup(curl); 64 } 65} 66~~~ 67 68# AVAILABILITY 69 70Always 71 72# RETURN VALUE 73 74If this function returns NULL, something went wrong and you cannot use the 75other curl functions. 76
