mirror of
https://codeberg.org/kiss-community/repo
synced 2024-12-23 07:40:11 -07:00
69 lines
2.5 KiB
Groff
69 lines
2.5 KiB
Groff
.\" generated by cd2nroff 0.1 from curl_easy_escape.md
|
|
.TH curl_easy_escape 3 "2024-08-02" libcurl
|
|
.SH NAME
|
|
curl_easy_escape \- URL encode a string
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
char *curl_easy_escape(CURL *curl, const char *string, int length);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
This function converts the given input \fIstring\fP 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, \(aq\-\(aq, \(aq.\(aq, \(aq_\(aq or \(aq~\(aq are converted to their "URL escaped" version
|
|
(\fB%NN\fP where \fBNN\fP is a two\-digit hexadecimal number).
|
|
|
|
If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input
|
|
\fIstring\fP to find out the size. This function does not accept input strings
|
|
longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
|
|
|
|
You must \fIcurl_free(3)\fP the returned string when you are done with it.
|
|
.SH ENCODING
|
|
libcurl is typically not aware of, nor does it care about, character
|
|
encodings. \fIcurl_easy_escape(3)\fP 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 \fIcurl_easy_escape(3)\fP must make sure that the data passed in
|
|
to the function is encoded correctly.
|
|
.SH URLs
|
|
URLs are by definition \fIURL encoded\fP. 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 \fIcurl_easy_escape(3)\fP, 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\(aqs URL API: set the pieces with \fIcurl_url_set(3)\fP and get
|
|
the final correct URL with \fIcurl_url_get(3)\fP.
|
|
.SH PROTOCOLS
|
|
This functionality affects all supported protocols
|
|
.SH EXAMPLE
|
|
.nf
|
|
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);
|
|
}
|
|
}
|
|
.fi
|
|
.SH HISTORY
|
|
Since 7.82.0, the \fBcurl\fP 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.
|
|
.SH AVAILABILITY
|
|
Added in curl 7.15.4
|
|
.SH RETURN VALUE
|
|
A pointer to a null\-terminated string or NULL if it failed.
|
|
.SH SEE ALSO
|
|
.BR curl_easy_unescape (3),
|
|
.BR curl_url_get (3),
|
|
.BR curl_url_set (3)
|