curl / libcurl / API / curl_easy_escape

curl_easy_escape - URL encode the given string


curl_easy_escape - URL encode a string


#include <curl/curl.h>
char *curl_easy_escape(CURL *curl, const char *string, int length);


This function converts the given input string to a URL encoded string and returns that as a new allocated string. All input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number).

If length is set to 0 (zero), curl_easy_escape uses strlen() on the input string to find out the size. This function does not accept input strings longer than CURL_MAX_INPUT_LENGTH (8 MB).

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.

You must curl_free the returned string when you are done with it.


libcurl is typically not aware of, nor does it care about, character encodings. curl_easy_escape 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 must make sure that the data passed in to the function is encoded correctly.


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, because it then also converts colons, slashes and other symbols that you probably want untouched.

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 and get the final correct URL with curl_url_get.




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);


Added in 7.15.4 and replaces the old curl_escape function.

Return value

A pointer to a null-terminated string or NULL if it failed.

See also

curl_easy_unescape(3), curl_url_get(3), curl_url_set(3)

This HTML page was made with roffit.