xref: /curl/docs/libcurl/curl_easy_perform.md (revision 5a488251) 
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
15Added-in: 7.1
16---
17
18# NAME
19
20curl_easy_perform - perform a blocking network transfer
21
22# SYNOPSIS
23
24~~~c
25#include <curl/curl.h>
26
27CURLcode curl_easy_perform(CURL *easy_handle);
28~~~
29
30# DESCRIPTION
31
32curl_easy_perform(3) performs a network transfer in a blocking manner and
33returns when done, or earlier if it fails. For non-blocking behavior, see
34curl_multi_perform(3).
35
36Invoke this function after curl_easy_init(3) and all the curl_easy_setopt(3)
37calls are made, and it performs the transfer as described in the options. It
38must be called with the same **easy_handle** as input as the curl_easy_init(3)
39call returned.
40
41You 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
43encouraged to do so. libcurl attempts to reuse existing connections for the
44following transfers, thus making the operations faster, less CPU intense and
45using less network resources. You probably want to use curl_easy_setopt(3)
46between the invokes to set options for the following curl_easy_perform(3)
47call.
48
49You must never call this function simultaneously from two places using the
50same **easy_handle**. Let the function return first before invoking it another
51time. If you want parallel transfers, you must use several curl easy_handles.
52
53A network transfer moves data to a peer or from a peer. An application tells
54libcurl how to receive data by setting the CURLOPT_WRITEFUNCTION(3) and
55CURLOPT_WRITEDATA(3) options. To tell libcurl what data to send, there are a
56few more alternatives but two common ones are CURLOPT_READFUNCTION(3) and
57CURLOPT_POSTFIELDS(3).
58
59While the **easy_handle** is added to a multi handle, it cannot be used by
60curl_easy_perform(3).
61
62# %PROTOCOLS%
63
64# EXAMPLE
65
66~~~c
67int 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
83CURLE_OK (0) means everything was OK, non-zero means an error occurred as
84*\<curl/curl.h\>* defines - see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3)
85was set with curl_easy_setopt(3) there is an error message stored in the error
86buffer when non-zero is returned.
87