| curl_url_set(3) | Library Functions Manual | curl_url_set(3) |
curl_url_set - set a URL part
#include <curl/curl.h>
CURLUcode curl_url_set(CURLU *url,
CURLUPart part,
const char *content,
unsigned int flags);
The url handle to work on, passed in as the first argument, must be a handle previously created by curl_url(3) or curl_url_dup(3).
This function sets or updates individual URL components, or parts, held by the URL object the handle identifies.
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 would use in a URL: URL encoded.
When setting part in the URL object that was previously already set, it replaces the data that was previously stored for that part with the new content.
The caller does not have to keep content around after a successful call as this function copies the content.
Setting a part to a NULL pointer removes that part's contents from the CURLU handle.
By default, this API only accepts URLs using schemes for protocols that are supported built-in. To make libcurl parse URLs generically even for schemes it does not know about, the CURLU_NON_SUPPORT_SCHEME flags bit must be set. Otherwise, this function returns CURLUE_UNSUPPORTED_SCHEME for URL schemes it does not recognize.
This function has an 8 MB maximum length limit for all provided input strings. In the real world, excessively long fields in URLs cause problems even if this API accepts them.
When setting or updating contents of individual URL parts, this API might accept data that would not be otherwise possible to set in the string when it gets populated as a result of a full URL parse. Beware. If done so, extracting a full URL later on from such components might render an invalid URL.
The flags argument is a bitmask with independent features.
When successfully setting a new URL, relative or absolute, the handle contents is replaced with the components of the newly set URL.
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.
Unless CURLU_NO_AUTHORITY is set, a blank hostname is not allowed in the URL.
Unless CURLU_NO_AUTHORITY is set, a blank hostname is not allowed to set.
If used together with the CURLU_APPENDQUERY bit, the provided part is appended on the end of the existing query.
The question mark in the URL is not part of the actual query contents.
The flags argument is zero, one or more bits set in a bitmask.
When CURLU_APPENDQUERY is used together with CURLU_URLENCODE, the first '=' symbol is not URL encoded.
When setting the path component with URL encoding enabled, the slash character is be skipped.
The query part gets space-to-plus conversion before the URL conversion.
This URL encoding is charset unaware and converts the input in a byte-by-byte manner.
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
/* change it to an FTP URL */
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
}
curl_url_cleanup(url);
}
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.
The input string passed to curl_url_set(3) must be shorter than eight million bytes. Otherwise this function returns CURLUE_MALFORMED_INPUT.
If this function returns an error, no URL part is set.
CURLOPT_CURLU(3), curl_url(3), curl_url_cleanup(3), curl_url_dup(3), curl_url_get(3), curl_url_strerror(3)
| March 12 2024 | libcurl |