curl_easy_perform.md (2616B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: curl_easy_perform 5 Section: 3 6 Source: libcurl 7 See-also: 8 - curl_easy_init (3) 9 - curl_easy_setopt (3) 10 - curl_multi_add_handle (3) 11 - curl_multi_perform (3) 12 - libcurl-errors (3) 13 Protocol: 14 - All 15 Added-in: 7.1 16 --- 17 18 # NAME 19 20 curl_easy_perform - perform a blocking network transfer 21 22 # SYNOPSIS 23 24 ~~~c 25 #include <curl/curl.h> 26 27 CURLcode curl_easy_perform(CURL *easy_handle); 28 ~~~ 29 30 # DESCRIPTION 31 32 curl_easy_perform(3) performs a network transfer in a blocking manner and 33 returns when done, or earlier if it fails. For non-blocking behavior, see 34 curl_multi_perform(3). 35 36 Invoke this function after curl_easy_init(3) and all the curl_easy_setopt(3) 37 calls are made, and it performs the transfer as described in the options. It 38 must be called with the same **easy_handle** as input as the curl_easy_init(3) 39 call returned. 40 41 You can do any amount of calls to curl_easy_perform(3) while using the same 42 **easy_handle**. If you intend to transfer more than one file, you are even 43 encouraged to do so. libcurl attempts to reuse existing connections for the 44 following transfers, thus making the operations faster, less CPU intense and 45 using less network resources. You probably want to use curl_easy_setopt(3) 46 between the invokes to set options for the following curl_easy_perform(3) 47 call. 48 49 You must never call this function simultaneously from two places using the 50 same **easy_handle**. Let the function return first before invoking it another 51 time. If you want parallel transfers, you must use several curl easy_handles. 52 53 A network transfer moves data to a peer or from a peer. An application tells 54 libcurl how to receive data by setting the CURLOPT_WRITEFUNCTION(3) and 55 CURLOPT_WRITEDATA(3) options. To tell libcurl what data to send, there are a 56 few more alternatives but two common ones are CURLOPT_READFUNCTION(3) and 57 CURLOPT_POSTFIELDS(3). 58 59 While the **easy_handle** is added to a multi handle, it cannot be used by 60 curl_easy_perform(3). 61 62 # %PROTOCOLS% 63 64 # EXAMPLE 65 66 ~~~c 67 int main(void) 68 { 69 CURL *curl = curl_easy_init(); 70 if(curl) { 71 CURLcode res; 72 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 73 res = curl_easy_perform(curl); 74 curl_easy_cleanup(curl); 75 } 76 } 77 ~~~ 78 79 # %AVAILABILITY% 80 81 # RETURN VALUE 82 83 This function returns a CURLcode indicating success or error. 84 85 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 86 libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) 87 there can be an error message stored in the error buffer when non-zero is 88 returned.