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_free (3) 10Protocol: 11 - All 12--- 13 14# NAME 15 16curl_easy_escape - URL encodes the given string 17 18# SYNOPSIS 19 20~~~c 21#include <curl/curl.h> 22 23char *curl_easy_escape(CURL *curl, const char *string, int length); 24~~~ 25 26# DESCRIPTION 27 28This function converts the given input *string* to a URL encoded string 29and returns that as a new allocated string. All input characters that are not 30a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" 31version (**%NN** where **NN** is a two-digit hexadecimal number). 32 33If *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on 34the input *string* to find out the size. This function does not accept 35input strings longer than **CURL_MAX_INPUT_LENGTH** (8 MB). 36 37Since 7.82.0, the **curl** parameter is ignored. Prior to that there was 38per-handle character conversion support for some old operating systems such as 39TPF, but it was otherwise ignored. 40 41You must curl_free(3) the returned string when you are done with it. 42 43# ENCODING 44 45libcurl is typically not aware of, nor does it care about, character 46encodings. curl_easy_escape(3) encodes the data byte-by-byte into the 47URL encoded version without knowledge or care for what particular character 48encoding the application or the receiving server may assume that the data 49uses. 50 51The caller of curl_easy_escape(3) must make sure that the data passed in 52to the function is encoded correctly. 53 54# EXAMPLE 55 56~~~c 57int main(void) 58{ 59 CURL *curl = curl_easy_init(); 60 if(curl) { 61 char *output = curl_easy_escape(curl, "data to convert", 15); 62 if(output) { 63 printf("Encoded: %s\n", output); 64 curl_free(output); 65 } 66 curl_easy_cleanup(curl); 67 } 68} 69~~~ 70 71# AVAILABILITY 72 73Added in 7.15.4 and replaces the old curl_escape(3) function. 74 75# RETURN VALUE 76 77A pointer to a null-terminated string or NULL if it failed. 78
