Percent-encoding, also known as URL encoding, is technically a mechanism for encoding data so that it can appear in URLs. This encoding is typically used when sending POSTs with the
application/x-www-form-urlencodedcontent type, such as the ones curl sends with
The command-line options mentioned above all require that you provide properly encoded data, data you need to make sure already exists in the right format. While that gives you a lot of freedom, it is also a bit inconvenient at times.
To help you send data you have not already encoded, curl offers the
--data-urlencodeoption. This option offers several different ways to URL encode the data you give it.
You use it like
--data-urlencode datain the same style as the other --data options. To be CGI-compliant, the data part should begin with a name followed by a separator and a content specification. The data part can be passed to curl using one of the following syntaxes:
content: This will make curl URL encode the content and pass that on. Just be careful so that the content does not contain any = or @ symbols, as that will then make the syntax match one of the other cases below!
=content: This will make curl URL encode the content and pass that on. The initial '=' symbol is not included in the data.
name=content: This will make curl URL encode the content part and pass that on. Note that the name part is expected to be URL encoded already.
@filename: This will make curl load data from the given file (including any newlines), URL encode that data and pass it on in the POST.
[email protected]: This will make curl load data from the given file (including any newlines), URL encode that data and pass it on in the POST. The name part gets an equal sign appended, resulting in name=urlencoded-file-content. Note that the name is expected to be URL encoded already.
As an example, you could POST a name to have it encoded by curl:
curl --data-urlencode "name=John Doe (Junior)" http://example.com
…which would send the following data in the actual request body:
If you store the string
John Doe (Junior)in a file named
contents.txt, you can tell curl to send that contents URL encoded using the field name 'user' like this:
In both these examples above, the field name is not URL encoded but is passed on as-is. If you want to URL encode the field name as well, like if you want to pass on a field name called
user name, you can ask curl to encode the entire string by prefixing it with an equals sign (that will not get sent):
curl --data-urlencode "=user name=John Doe (Junior)" http://example.com