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