GNURLOPT_CONV_TO_NETWORK_FUNCTION(3)

💅 CURLOPT_CONV_TO_NETWORK_FUNCTION 💅

okay bestie, so this one's from the gnurl/curl curl_easy_setopt options manual and it's giving "niche but important" energy, so like… pay attention 💖

---

✨ NAME ✨

CURLOPT_CONV_TO_NETWORK_FUNCTION — converts your data to network encoding from host encoding, no cap 🫶

---

🌸 SYNOPSIS 🌸

#include <gnurl/curl.h>

CURLcode conv_callback(char *ptr, size_t length);

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

---

🦋 DESCRIPTION 🦋

So you're gonna pass a pointer to your callback function, and it literally has to match the prototype up there, okurrr? Like, those are the vibes it needs to have 💅

This bad boy applies to non-ASCII platforms. And hey, curl_version_info(3) will return the CURL_VERSION_CONV feature bit set if this option is provided — so you can check that to confirm it's actually there, iykyk ✨

Here's the tea on how your callback gets called: the data to be converted lives in a buffer pointed to by the ptr parameter, and the amount of data to convert is indicated by the length parameter. The converted data overlays the input data in the buffer pointed to by ptr — so like, it's in-place, bestie, don't be surprised 🙈 CURLE_OK must be returned upon successful conversion. And if an error was encountered, you should return a CURLcode return value defined by curl.h, such as CURLE_CONV_FAILED.

So what does CURLOPT_CONV_TO_NETWORK_FUNCTION actually do? It converts from host encoding to the network encoding — and it's used when commands or ASCII data are sent over the network. iconic behavior honestly 🔥

Now, if you set a callback pointer to NULL, or just don't set it at all, the built-in libcurl iconv functions will be used. But — and this is the important part — if HAVE_ICONV was not defined when libcurl was built, and no callback has been established, conversion will return the CURLE_CONV_REQD error code 😭

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

#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"

The iconv code in libcurl will default the network and UTF8 codeset names as follows:

#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"

#define CURL_ICONV_CODESET_FOR_UTF8   "UTF-8"

You will need to override these definitions if they are different on your system, mmmkay? 💜

---

🎀 DEFAULT 🎀

NULL

---

🌈 PROTOCOLS 🌈

FTP, SMTP, IMAP, POP3 — the whole little squad 🫶

---

💖 EXAMPLE 💖

static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length)
{
  char *tempptrin, *tempptrout;
  size_t bytes = length;
  int rc;
  tempptrin = tempptrout = buffer;
  rc = platform_e2a(&tempptrin, &bytes, &tempptrout, &bytes);
  if(rc == PLATFORM_CONV_OK) {
    return CURLE_OK;
  }
  else {
    return CURLE_CONV_FAILED;
  }
}

curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION,
                 my_conv_from_ebcdic_to_ascii);

---

⭐ AVAILABILITY ⭐

Available only if CURL_DOES_CONVERSIONS was defined when libcurl was built. so like, check that before you come crying to me 😭💀

---

👑 RETURN VALUE 👑

Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. simple as that bestie ✨

---

🧚 SEE ALSO 🧚

• CURLOPT_CONV_FROM_NETWORK_FUNCTION(3)
• CURLOPT_CONV_FROM_UTF8_FUNCTION(3)

---

ok that's the whole page, don't forget the callbacks are in-place and HAVE_ICONV matters, mwah 💋

---

later bestie ~ this one's from libcurl 7.37.0, dated 19 Jun 2014, and it ate, no crumbs 💅✨🦋