1--- 2c: Copyright (C) Daniel Stenberg, <daniel.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) 10--- 11 12# NAME 13 14curl_easy_escape - URL encodes the given string 15 16# SYNOPSIS 17 18~~~c 19#include <curl/curl.h> 20 21char *curl_easy_escape(CURL *curl, const char *string, int length); 22~~~ 23 24# DESCRIPTION 25 26This function converts the given input *string* to a URL encoded string 27and returns that as a new allocated string. All input characters that are not 28a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" 29version (**%NN** where **NN** is a two-digit hexadecimal number). 30 31If *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on 32the input *string* to find out the size. This function does not accept 33input strings longer than **CURL_MAX_INPUT_LENGTH** (8 MB). 34 35Since 7.82.0, the **curl** parameter is ignored. Prior to that there was 36per-handle character conversion support for some old operating systems such as 37TPF, but it was otherwise ignored. 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# EXAMPLE 53 54~~~c 55int main(void) 56{ 57 CURL *curl = curl_easy_init(); 58 if(curl) { 59 char *output = curl_easy_escape(curl, "data to convert", 15); 60 if(output) { 61 printf("Encoded: %s\n", output); 62 curl_free(output); 63 } 64 curl_easy_cleanup(curl); 65 } 66} 67~~~ 68 69# AVAILABILITY 70 71Added in 7.15.4 and replaces the old curl_escape(3) function. 72 73# RETURN VALUE 74 75A pointer to a null-terminated string or NULL if it failed. 76