1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_PROGRESSFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_NOPROGRESS (3)
9  - CURLOPT_VERBOSE (3)
10  - CURLOPT_XFERINFOFUNCTION (3)
11Protocol:
12  - All
13---
14
15# NAME
16
17CURLOPT_PROGRESSFUNCTION - progress meter callback
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24int progress_callback(void *clientp,
25                      double dltotal,
26                      double dlnow,
27                      double ultotal,
28                      double ulnow);
29
30CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION,
31                          progress_callback);
32~~~
33
34# DESCRIPTION
35
36Pass a pointer to your callback function, which should match the prototype
37shown above.
38
39This option is deprecated and we encourage users to use the
40newer CURLOPT_XFERINFOFUNCTION(3) instead, if you can.
41
42This function gets called by libcurl instead of its internal equivalent with a
43frequent interval. While data is being transferred it is invoked frequently,
44and during slow periods like when nothing is being transferred it can slow
45down to about one call per second.
46
47*clientp* is the pointer set with CURLOPT_PROGRESSDATA(3), it is not
48used by libcurl but is only passed along from the application to the callback.
49
50The callback gets told how much data libcurl is about to transfer and has
51transferred, in number of bytes. *dltotal* is the total number of bytes
52libcurl expects to download in this transfer. *dlnow* is the number of
53bytes downloaded so far. *ultotal* is the total number of bytes libcurl
54expects to upload in this transfer. *ulnow* is the number of bytes
55uploaded so far.
56
57Unknown/unused argument values passed to the callback are be set to zero (like
58if you only download data, the upload size remains 0). Many times the callback
59is called one or more times first, before it knows the data sizes so a program
60must be made to handle that.
61
62If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl
63to continue executing the default progress function.
64
65Returning any other non-zero value from this callback makes libcurl abort the
66transfer and return *CURLE_ABORTED_BY_CALLBACK*.
67
68If you transfer data with the multi interface, this function is not called
69during periods of idleness unless you call the appropriate libcurl function
70that performs transfers.
71
72CURLOPT_NOPROGRESS(3) must be set to 0 to make this function actually
73get called.
74
75# DEFAULT
76
77By default, libcurl has an internal progress meter. That is rarely wanted by
78users.
79
80# EXAMPLE
81
82~~~c
83struct progress {
84  char *private;
85  size_t size;
86};
87
88static size_t progress_callback(void *clientp,
89                                double dltotal,
90                                double dlnow,
91                                double ultotal,
92                                double ulnow)
93{
94  struct progress *memory = clientp;
95  printf("private: %p\n", memory->private);
96
97  /* use the values */
98
99  return 0; /* all is good */
100}
101
102int main(void)
103{
104  struct progress data;
105
106  CURL *curl = curl_easy_init();
107  if(curl) {
108    /* pass struct to callback  */
109    curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data);
110    curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback);
111
112    curl_easy_perform(curl);
113  }
114}
115~~~
116
117# AVAILABILITY
118
119Deprecated since 7.32.0.
120
121# RETURN VALUE
122
123Returns CURLE_OK.
124