curl_easy_escape(3)

💖 NAME 💖

Okay so bestie, welcome to curl_easy_escape(3) from the Library Functions Manual — this is literally the function that URL-encodes a string and returns it as a new allocated string. Let me break it down for you. 💅

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

char *curl_easy_escape(CURL *curl, const char *string, int length);

💅 DESCRIPTION 💅

Okay so here's the tea: this function takes the input string you give it and converts it to a URL-encoded string, then returns that as a brand new allocated string. The way it works is: all input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' get converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number). Obsessed with that attention to detail. ✨

Although not constrained by its type, the returned string may not be altered. So like, don't touch it, okay? 🙈

If length is set to 0 (zero), curl_easy_escape(3) uses strlen() on the input string to find out the size. Iconic shortcut behavior. 💖

You must curl_free(3) the returned string when you are done with it. No cap, this is important. Free your memory, bestie. 🌸

🎀 ENCODING 🎀

Okay so here's the vibe: libcurl is typically not aware of, nor does it care about, character encodings. curl_easy_escape(3) encodes the data byte-by-byte into the URL encoded version without knowledge or care for what particular character encoding the application or the receiving server may assume that the data uses.

The caller of curl_easy_escape(3) must make sure that the data passed in to the function is encoded correctly. That's on you, bestie. 💜

🦋 URLS 🦋

URLs are by definition URL encoded. To create a proper URL from a set of components that may not be URL encoded already, you cannot just URL encode the entire URL string with curl_easy_escape(3), because it then also converts colons, slashes and other symbols that you probably want untouched. So like, don't do that. 🙈

To create a proper URL from strings that are not already URL encoded, we recommend using libcurl's URL API: set the pieces with curl_url_set(3) and get the final correct URL with curl_url_get(3). Slay! 💅

🌈 PROTOCOLS 🌈

This functionality affects all supported protocols. Periodt. 👑

⭐ EXAMPLE ⭐

Okay so here's a little example to make it make sense. No cap, this is exactly how you'd use it:

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    char *output = curl_easy_escape(curl, "data to convert", 15);
    if(output) {
      printf("Encoded: %s\n", output);
      curl_free(output);
    }
    curl_easy_cleanup(curl);
  }
}

👑 HISTORY 👑

Since 7.82.0, the curl parameter is ignored. Prior to that there was per-handle character conversion support for some old operating systems such as TPF, but it was otherwise ignored. The more you know, right? ⭐

🔥 AVAILABILITY 🔥

Added in curl 7.15.4. So it's been around for a minute. 💀

💀 RETURN VALUE 💀

A pointer to a null-terminated string or NULL if it failed. That's the whole vibe check. 💖

🫶 SEE ALSO 🫶

curl_easy_unescape(3), curl_url_get(3), curl_url_set(3). Go check 'em out if you want the full picture. 🌈

---

Peace out, bestie! This has been libcurl on 2026-10-12, signing off. Stay encoded! 💅✨