1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_escape 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_unescape (3) 9 - curl_url_set (3) 10 - curl_url_get (3) 11Protocol: 12 - All 13Added-in: 7.15.4 14--- 15 16# NAME 17 18curl_easy_escape - URL encode a string 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25char *curl_easy_escape(CURL *curl, const char *string, int length); 26~~~ 27 28# DESCRIPTION 29 30This function converts the given input *string* to a URL encoded string and 31returns that as a new allocated string. All input characters that are not a-z, 32A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version 33(**%NN** where **NN** is a two-digit hexadecimal number). 34 35If *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on the input 36*string* to find out the size. This function does not accept input strings 37longer than **CURL_MAX_INPUT_LENGTH** (8 MB). 38 39You must curl_free(3) the returned string when you are done with it. 40 41# ENCODING 42 43libcurl is typically not aware of, nor does it care about, character 44encodings. curl_easy_escape(3) encodes the data byte-by-byte into the 45URL encoded version without knowledge or care for what particular character 46encoding the application or the receiving server may assume that the data 47uses. 48 49The caller of curl_easy_escape(3) must make sure that the data passed in 50to the function is encoded correctly. 51 52# URLs 53 54URLs are by definition *URL encoded*. To create a proper URL from a set of 55components that may not be URL encoded already, you cannot just URL encode the 56entire URL string with curl_easy_escape(3), because it then also converts 57colons, slashes and other symbols that you probably want untouched. 58 59To create a proper URL from strings that are not already URL encoded, we 60recommend using libcurl's URL API: set the pieces with curl_url_set(3) and get 61the final correct URL with curl_url_get(3). 62 63# %PROTOCOLS% 64 65# EXAMPLE 66 67~~~c 68int main(void) 69{ 70 CURL *curl = curl_easy_init(); 71 if(curl) { 72 char *output = curl_easy_escape(curl, "data to convert", 15); 73 if(output) { 74 printf("Encoded: %s\n", output); 75 curl_free(output); 76 } 77 curl_easy_cleanup(curl); 78 } 79} 80~~~ 81 82# HISTORY 83 84Since 7.82.0, the **curl** parameter is ignored. Prior to that there was 85per-handle character conversion support for some old operating systems such as 86TPF, but it was otherwise ignored. 87 88# %AVAILABILITY% 89 90# RETURN VALUE 91 92A pointer to a null-terminated string or NULL if it failed. 93
