GNURLOPT_PROGRESSFUNCTION(3)

💅 GNURLOPT_PROGRESSFUNCTION(3) — curl_easy_setopt options, bestie edition

okay so real talk, this one lives in the curl_easy_setopt options family (gnurl girlies, you know the drill) and it's literally all about getting a callback when your transfer makes progress. let's get into it 🎀

---

✨ NAME ✨

CURLOPT_PROGRESSFUNCTION — the callback-to-progress-meter-function situation. that's it, that's the vibe 🦋

---

🌸 SYNOPSIS 🌸

#include <gnurl/curl.h>

int progress_callback(void *clientp,
                      double dltotal,
                      double dlnow,
                      double ultotal,
                      double ulnow);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION,
                          progress_callback);

like, you pass a pointer to your callback function and it has to match that prototype up there exactly. no improvising, bestie 💅

---

💖 DESCRIPTION 💖

So you hand over a pointer to your callback function (matching the prototype above, fr fr) and libcurl calls yours instead of its own internal equivalent, on a pretty frequent interval. While data is actually being transferred it gets called very frequently — like, constantly, main character energy — and during slow periods, i.e. when nothing's going anywhere, it can chill down to about one call per second. 😴

ngl, the docs themselves say: we encourage users to use the newer CURLOPT_XFERINFOFUNCTION(3) instead, if you can. so like… if you can, slay, do that one. ✨

clientp is the pointer you set with CURLOPT_PROGRESSDATA(3). libcurl does not use it — it literally just carries it from your application over to the callback. a little messenger. a vibe courier. 🫶

The callback gets told how much data libcurl will transfer and how much it has transferred, in number of bytes:

• dltotal — the total number of bytes libcurl expects to download in this transfer
• dlnow — the number of bytes downloaded so far
• ultotal — the total number of bytes libcurl expects to upload in this transfer
• ulnow — the number of bytes uploaded so far

Unknown / unused argument values passed to the callback get set to zero (so if you're only downloading data, the upload size stays at 0). and heads up — many times the callback gets called one or more times first, before it even knows the data sizes, so your program absolutely has to be built to handle that. no cap, plan for it 🙈

Now the return value behaviour, and this part is important:

• If your callback returns CURL_PROGRESSFUNC_CONTINUE, libcurl will continue executing the default progress function. cute, non-disruptive 🧚
• Returning any other non-zero value will cause libcurl to abort the transfer and return CURLE_ABORTED_BY_CALLBACK. so like, don't return random non-zero values unless you mean it 💀

If you transfer data with the multi interface, this function will not be called during periods of idleness — unless you call the appropriate libcurl function that performs transfers. you gotta poke it 🫵

And the big one: CURLOPT_NOPROGRESS(3) must be set to 0 to make this function actually get called. set that or your callback is just sitting there, iconic but unemployed 😭

---

💅 DEFAULT 💅

By default, libcurl has an internal progress meter. That's rarely wanted by users. like, respectfully, nobody's asking for it 🌈

---

🔥 PROTOCOLS 🔥

All — every single one, we love an inclusive queen 👑

---

⭐ EXAMPLE ⭐

https://curl.haxx.se/libcurl/c/progressfunc.html

go look at the example, it's giving tutorial 💖

---

🎀 AVAILABILITY 🎀

Always — she's been here the whole time 🦋

---

🍓 RETURN VALUE 🍓

Returns CURLE_OK. simple, clean, no drama ✨

---

🌈 SEE ALSO 🌈

• CURLOPT_VERBOSE(3)
• CURLOPT_NOPROGRESS(3),

(yeah the trailing comma is literally in the source, leaving it exactly as found, iykyk 🫶)

---

💀 one last vibe check reminder: non-zero return = transfer aborted with CURLE_ABORTED_BY_CALLBACK. and CURLOPT_NOPROGRESS(3) to 0 or nothing happens at all. periodt.

---

okay that's the whole page!! brought to you by libcurl 7.37.0, dated 17 Jun 2014 — yes she's vintage, yes she still ate 👑💜 byeee 🧚‍♀️