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-urlencoded
content type,
such as the ones curl sends with
--data
and
--data-binary
etc.
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-urlencode
option. This option offers several different ways to URL
encode the data you give it.
You use it like
--data-urlencode data
in 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
: URL encode the content and pass that on. Just be careful so that
the content does not contain any
=
or
@
symbols, as that then makes the
syntax match one of the other cases below.
=content
: URL encode the content and pass that on. The initial
=
symbol
is not included in the data.
name=content
: URL encode the content part and pass that on. Note that the
name part is expected to be URL encoded already.
@filename
: load data from the given file (including any newlines), URL
encode that data and pass it on in the POST.
name@filename
: 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:
name=John%20Doe%20%28Junior%29
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:
curl --data-urlencode [email protected] http://example.com
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 does not get sent):
curl --data-urlencode "=user name=John Doe (Junior)" http://example.com
