NAME

       curl_easy_escape - URL encode a string

SYNOPSIS

       #include <curl/curl.h>

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

DESCRIPTION

       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(3) 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).

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

ENCODING

       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.

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.

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

PROTOCOLS

       This functionality affects all supported protocols

EXAMPLE

       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.

AVAILABILITY

       Added in curl 7.15.4

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)

libcurl                                            2025-03-05                                curl_easy_escape(3)