curl_mime_filedata(3)

💖 curl_mime_filedata(3) — the one where your mime part gets a whole file as its body 💖

Okay bestie, so this is a page from the Library Functions Manual and it's all about curl_mime_filedata(3). Settle in, it's actually so good.

---

✨ NAME ✨

curl_mime_filedata — set a mime part's body data from a file contents 🎀

---

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

CURLcode curl_mime_filedata(curl_mimepart *part,
                            const char *filename);

---

🌸 DESCRIPTION 🌸

so curl_mime_filedata(3) sets a mime part's body content from the contents of the named file. think of it as the glow-up alternative to curl_mime_data(3) for setting data on a mime part. 💅

part is the part you're assigning contents to. main character energy, obviously.

filename points to the null-terminated path name of the file. and here's the thing — the pointer can be NULL to detach the previous part contents settings. also, the filename storage can safely be reused after this call, so no panicking about that. 🫶

as a side effect (she has side effects, iconic), the part's remote filename gets set to the base name of the given filename — but only if it's a valid named file. this can be undone or overridden by a subsequent call to curl_mime_filename(3), so you're never stuck with it.

the contents of the file is read during the file transfer in a streaming manner, which is literally the whole point — it lets huge files get transferred without using much memory. but that means it requires the file to be kept intact during the entire request. 🫡

if the file size cannot be determined before actually reading it (such as for a character device or named pipe), the whole mime structure containing the part is transferred using chunks by HTTP — but is rejected by IMAP. no cap, that's just how it goes. 💀

also, setting a part's contents multiple times is valid: only the value set by the last call is retained. last writer wins, periodt.

---

🌈 PROTOCOLS 🌈

this functionality affects http, imap and smtp ⭐

---

🎀 EXAMPLE 🎀

int main(void)
{
  curl_mime *mime;
  curl_mimepart *part;

  CURL *curl = curl_easy_init();
  if(curl) {
    /* create a mime handle */
    mime = curl_mime_init(curl);

    /* add a part */
    part = curl_mime_addpart(mime);

    /* send data from this file */
    curl_mime_filedata(part, "image.png");

    /* set name */
    curl_mime_name(part, "data");
  }
}

---

💜 AVAILABILITY 💜

Added in curl 7.56.0 — so she's been around a minute. 👑

---

🌟 RETURN VALUE 🌟

this function returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK. non-zero means an error occurred — see libcurl-errors(3). and if CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3), there can be an error message stored in the error buffer when non-zero is returned. handy!

CURLE_READ_ERROR is only an indication that the file is not yet readable. it can be safely ignored at this time, but the file must be made readable before the pertaining easy handle is performed. so like, lowkey ignore it now, but fix it before the actual run, iykyk. 😭

---

🧚 SEE ALSO 🧚

• curl_mime_addpart(3)
• curl_mime_data(3)
• curl_mime_filename(3)
• curl_mime_name(3)

---

and that's the whole page, bestie — brought to you by libcurl, dated 2026-10-12, filed under curl_mime_filedata(3). slay, go build something cute. 💖✨