CURLOPT_CONV_FROM_UTF8_FUNCTION(3)

💅 CURLOPT_CONV_FROM_UTF8_FUNCTION(3) 💅

okay so bestie, welcome to the libcurl Library Functions Manual, and lemme tell you, this one's a deep cut 🫶 — it's all about converting data from UTF8 to host encoding. Yes, that's a whole vibe. Let's get into it ✨

---

✨ NAME ✨

CURLOPT_CONV_FROM_UTF8_FUNCTION — convert data from UTF8 to host encoding 💖

---

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

CURLcode conv_callback(char *ptr, size_t length);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION,
                          conv_callback);

---

🌸 DESCRIPTION 🌸

So you pass a pointer to your callback function, and that function has to match the prototype up there 👆 — like, exactly, no improvising, bestie.

This one applies to non-ASCII platforms only, iykyk. Also! curl_version_info(3) returns the CURL_VERSION_CONV feature bit set if this option is provided. Cute, right? ⭐

Here's the deal with the data: the stuff you're converting lives in a buffer, and the ptr parameter points at it. How much data you're converting? That's the length parameter. And the converted data overlays the input data in that same buffer pointed to by ptr — in-place glow-up, no new buffer needed 💅. You must return CURLE_OK when the conversion works out. If something goes wrong, return a CURLcode value defined by curl.h, like CURLE_CONV_FAILED.

CURLOPT_CONV_FROM_UTF8_FUNCTION(3) converts to host encoding from UTF8 encoding. And ngl, it's only required for SSL processing. That's it. That's the whole job 🎀

If you set the callback pointer to NULL, or you just... don't set it at all (honestly valid), then the built-in libcurl iconv functions get used. But — and this is the plot twist 😭 — if HAVE_ICONV was not defined when libcurl was built, and no callback has been established, then the conversion returns the CURLE_CONV_REQD error code.

If HAVE_ICONV is defined, then CURL_ICONV_CODESET_OF_HOST must also be defined. Like, for example:

#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"

The iconv code in libcurl defaults the network and UTF8 codeset names like this:

#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"

#define CURL_ICONV_CODESET_FOR_UTF8   "UTF-8"

And if those are different on your system? You need to override these definitions. No cap, just do it 🔥

---

🧚 DEFAULT 🧚

NULL

---

🌈 PROTOCOLS 🌈

This functionality affects all supported protocols 👑

---

🍓 EXAMPLE 🍓

static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length)
{
  int rc = 0;
  /* in-place convert 'buffer' from UTF-8 to EBCDIC */
  if(rc == 0) {
    /* success */
    return CURLE_OK;
  }
  else {
    return CURLE_CONV_FAILED;
  }
}

int main(void)
{
  CURL *curl = curl_easy_init();
  curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION,
                   my_conv_from_utf8_to_ebcdic);
}

---

💀 DEPRECATED 💀

Not available and deprecated since 7.82.0. Yeah. She's retired 💔

Also, it was only ever available if CURL_DOES_CONVERSIONS was defined when libcurl was built.

---

⭐ AVAILABILITY ⭐

Added in curl 7.15.4 — a true vintage icon 👑

---

🫶 RETURN VALUE 🫶

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (that's 0) means everything was OK 💖 and non-zero means an error occurred — check libcurl-errors(3) for the deets.

---

🌸 SEE ALSO 🌸

• CURLOPT_CONV_FROM_NETWORK_FUNCTION(3)
• CURLOPT_CONV_TO_NETWORK_FUNCTION(3)

---

k that's the whole page, bestie!! 💅✨ this lil slice of libcurl manual magic is from the libcurl source, dated 2026-10-12 — mwah, go convert something, ily 🎀🦋💜