curl_url_set - set a URL part
CURLUcode curl_url_set(CURLU *url,
const char *content,
unsigned int flags)
Given the url handle of an already parsed URL, this function lets the
user set/update individual pieces of it.
The part argument should identify the particular URL part
(see list below) to set or change, with content pointing to a
null-terminated string with the new contents for that URL part. The contents
should be in the form and encoding they'd use in a URL: URL encoded.
The application does not have to keep content around after
a successful call.
Setting a part to a NULL pointer will effectively remove that
part's contents from the CURLU handle.
The flags argument is a bitmask with independent
The flags argument is zero, one or more bits set in a bitmask.
- Allows the full URL of the handle to be replaced. If the handle already is
populated with a URL, the new URL can be relative to the previous.
When successfully setting a new URL, relative or absolute, the
handle contents will be replaced with the information of the newly set
Pass a pointer to a null-terminated string to the url
parameter. The string must point to a correctly formatted "RFC
3986+" URL or be a NULL pointer.
- Scheme cannot be URL decoded on set. libcurl only accepts setting schemes
up to 40 bytes long.
- The host name. If it is IDNA the string must then be encoded as your
locale says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6
numeric address it may contain a zone id (or you can use
- If the host name is a numeric IPv6 address, this field can also be
- Port cannot be URL encoded on set. The given port number is provided as a
string and the decimal number must be between 1 and 65535. Anything else
will return an error.
- If a path is set in the URL without a leading slash, a slash will be
inserted automatically when this URL is read from the handle.
- The query part will also get spaces converted to pluses when asked to URL
encode on set with the CURLU_URLENCODE bit.
If used together with the CURLU_APPENDQUERY bit, the
provided part will be appended on the end of the existing query - and if
the previous part did not end with an ampersand (&), an ampersand
will be inserted before the new appended part.
When CURLU_APPENDQUERY is used together with
CURLU_URLENCODE, the first '=' symbol will not be URL
The question mark in the URL is not part of the actual query
- The hash sign in the URL is not part of the actual fragment contents.
- If set, allows curl_url_set(3) to set a non-supported scheme.
- When set, curl_url_set(3) URL encodes the part on entry, except for
scheme, port and URL.
When setting the path component with URL encoding enabled, the
slash character will be skipped.
The query part gets space-to-plus conversion before the URL
This URL encoding is charset unaware and will convert the
input on a byte-by-byte manner.
- If set, will make libcurl allow the URL to be set without a scheme and
then sets that to the default scheme: HTTPS. Overrides the
CURLU_GUESS_SCHEME option if both are set.
- If set, will make libcurl allow the URL to be set without a scheme and it
instead "guesses" which scheme that was intended based on the
host name. If the outermost sub-domain name matches DICT, FTP, IMAP, LDAP,
POP3 or SMTP then that scheme will be used, otherwise it picks HTTP.
Conflicts with the CURLU_DEFAULT_SCHEME option which takes
precedence if both are set.
- If set, skips authority checks. The RFC allows individual schemes to omit
the host part (normally the only mandatory part of the authority), but
libcurl cannot know whether this is permitted for custom schemes.
Specifying the flag permits empty authority sections, similar to how file
scheme is handled.
- When set for CURLUPART_URL, this makes libcurl skip the
normalization of the path. That is the procedure where curl otherwise
removes sequences of dot-slash and dot-dot etc. The same option used for
transfers is called CURLOPT_PATH_AS_IS(3).
- If set, a the URL parser allows space (ASCII 32) where possible. The URL
syntax does normally not allow spaces anywhere, but they should be encoded
as %20 or '+'. When spaces are allowed, they are still not allowed in the
scheme. When space is used and allowed in a URL, it will be stored as-is
unless CURLU_URLENCODE is also set, which then makes libcurl
URL-encode the space before stored. This affects how the URL will be
constructed when curl_url_get(3) is subsequently used to extract
the full URL or individual parts. (Added in 7.78.0)
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
/* change it to an FTP URL */
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went fine.
See the libcurl-errors(3) man page for the full list with descriptions.
A URL string passed on to curl_url_set(3) for the
CURLUPART_URL part, must be shorter than 8000000 bytes otherwise it
returns CURLUE_MALFORMED_INPUT (added in 7.65.0).
If this function returns an error, no URL part is set.
curl_url_cleanup(3), curl_url(3), curl_url_get(3),
curl_url_dup(3), curl_url_strerror(3), CURLOPT_CURLU(3)
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.