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