GNURLOPT_XFERINFOFUNCTION(3)

💅 GNURLOPT_XFERINFOFUNCTION 💅

okay so this page lives in the curl_easy_setopt options manual section (yes, gnurl's — icon behavior), and it's all about one very specific callback. grab a strawberry 🍓 and let's go.

✨ NAME ✨

CURLOPT_XFERINFOFUNCTION — the callback to the progress meter function. that's it, that's the vibe. 🎀

🦋 SYNOPSIS 🦋

#include <gnurl/curl.h>

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

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

like, copy that prototype exactly, bestie. it is not a suggestion. 🙈

💖 DESCRIPTION 💖

so you pass in a pointer to your callback function — and it has to match the prototype shown above, no freelancing. ✨

libcurl calls your function instead of its internal equivalent one, and it does it on a frequent interval. when data is actually moving it gets called very frequently (like, main-character energy frequent), and during slow periods — say, when nothing is being transferred at all — it can chill out to about one call per second. lowkey polite of it.

clientp is the pointer you set with CURLOPT_XFERINFODATA(3). libcurl itself does not use it — it just carries it along from your app to the callback, like a note passed in class. 🫶

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

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

unknown / unused argument values passed to the callback get set to zero (so if you're only downloading, the upload size stays 0). and ngl, lots of times the callback gets called once or more first, before it even knows the data sizes — so your program must be built to handle that. fr fr, don't skip that part. 😭

if your callback returns CURL_PROGRESSFUNC_CONTINUE, libcurl goes ahead and keeps executing the default progress function. slay.

returning any other non-zero value from this callback makes libcurl abort the transfer and return CURLE_ABORTED_BY_CALLBACK. 💀 so like, be careful what you return, okay?

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. iykyk.

heads up bestie: CURLOPT_NOPROGRESS(3) must be set to 0 to make this function actually get called. that's the whole vibe check. if you forget, nothing happens and you'll be confused for an hour. 🙈

🌸 DEFAULT 🌸

by default, libcurl has an internal progress meter. that's rarely wanted by users. iconic of libcurl to ship it anyway.

🌈 PROTOCOLS 🌈

All — every single one. 👑

⭐ EXAMPLE ⭐

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

🧚 AVAILABILITY 🧚

added in 7.32.0. this callback replaces CURLOPT_PROGRESSFUNCTION(3). out with the old, in with the new ✨

🔥 RETURN VALUE 🔥

returns CURLE_OK. simple. clean. no notes.

👑 SEE ALSO 👑

• CURLOPT_XFERINFODATA(3)
• CURLOPT_NOPROGRESS(3)

---

and that's the page, bestie! 🫶 this little masterpiece came from libcurl 7.37.0, dated 17 Jun 2014 — ancient, but the vibes are timeless. mwah 💋