GNURLOPT_READFUNCTION(3)

💅 GNURLOPT_READFUNCTION(3) — read callback for data uploads

okay bestie, so this one's from the Library Functions Manual and it's all about gnurl/curl's CURLOPT_READFUNCTION — the read callback for data uploads. Let's get into it ✨

---

🌸 SYNOPSIS 🌸

#include <gnurl/curl.h>

size_t
read_callback(char *buffer, size_t size, size_t nitems, void *userdata);

CURLcode
curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);

---

💖 DESCRIPTION 💖

So you pass a pointer to your callback function, like the prototype up there shows. Easy.

This callback gets called by libcurl the second it needs to read data so it can send it to the peer — like when you ask it to upload or post data to the server. The data area that buffer points at? Your function should fill it up with at most size multiplied with nitems number of bytes. That's the ceiling, bestie, don't go over 💀

You set the userdata argument with the CURLOPT_READDATA(3) option. yw.

Your function must return the actual number of bytes it stored in the data area that buffer points at. And if you return 0? That signals end-of-file to the library and causes it to stop the current transfer. periodt.

⚠️ ngl, if you stop the current transfer by returning 0 "pre-maturely" (i.e. before the server expected it, like when you've said you'll upload N bytes and you upload less than N bytes), you may experience the server just "hangs" waiting for the rest of the data that won't come. awkward 😭

The read callback may return CURL_READFUNC_ABORT to stop the current operation immediately, resulting in a CURLE_ABORTED_BY_CALLBACK error code from the transfer. slay, but also, abort.

The callback can return CURL_READFUNC_PAUSE to cause reading from this connection to pause. See curl_easy_pause(3) for further details 🫶

---

🦋 BUGS 🦋

when doing TFTP uploads, you must return the exact amount of data that the callback wants, or it will be considered the final packet by the server end and the transfer will end there. no pressure or anything 🙈

If you set this callback pointer to NULL, or don't set it at all, the default internal read function will be used. It is doing an fread() on the FILE * userdata set with CURLOPT_READDATA(3).

You can set the total size of the data you are sending by using CURLOPT_INFILESIZE_LARGE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3), depending on the type of transfer. For some transfer types it may be required and it allows for better error checking. lowkey important 👑

---

🎀 DEFAULT 🎀

The default internal read callback is fread().

---

🌈 PROTOCOLS 🌈

This is used for all protocols when doing uploads. all of them. every single one 💅

---

⭐ EXAMPLE ⭐

size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userdata)
{
  FILE *readhere = (FILE *)userdata;
  curl_off_t nread;

  /* copy as much data as possible into the 'ptr' buffer, but no more than
     'size' * 'nmemb' bytes! */
  size_t retcode = fread(ptr, size, nmemb, readhere);

  nread = (curl_off_t)retcode;

  fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
          " bytes from file\n", nread);
  return retcode;
}

void setup(char *uploadthis)
{
  FILE *file = fopen(uploadthis, "rb");
  CURLcode result;

  /* set callback to use */
  curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);

  /* pass in suitable argument to callback */
  curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);

  result = curl_easy_perform(curl);
}

---

🧚 AVAILABILITY 🧚

The CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT was added in 7.12.1. vintage ✨

---

👑 RETURN VALUE 👑

This will return CURLE_OK. that's it, that's the return 💖

---

🍓 SEE ALSO 🍓

• CURLOPT_READDATA(3)
• CURLOPT_WRITEFUNCTION(3)
• CURLOPT_SEEKFUNCTION(3)
• CURLOPT_UPLOAD(3)
• CURLOPT_POST(3)
• CURLOPT_UPLOAD_BUFFERSIZE(3)

---

okay that's the whole page bestie, go read your data and return your byte counts responsibly 🫶

De bian, June 25, 2020 — mwah, catch you on the next manpage 💋