DragonFly On-Line Manual Pages
curl_url_set(3) libcurl Manual curl_url_set(3)
NAME
curl_url_set - set a URL part
SYNOPSIS
#include <curl/curl.h>
CURLUcode curl_url_set(CURLU *url,
CURLUPart part,
const char *content,
unsigned int flags)
DESCRIPTION
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 zero 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.
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 features.
PARTS
CURLUPART_URL
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 URL.
Pass a pointer to a zero terminated string to the url parameter.
The string must point to a correctly formatted "RFC 3986+" URL
or be a NULL pointer.
CURLUPART_SCHEME
Scheme cannot be URL decoded on set.
CURLUPART_USER
CURLUPART_PASSWORD
CURLUPART_OPTIONS
CURLUPART_HOST
The host name can use IDNA. The string must then be encoded as
your locale says or UTF-8 (when winidn is used).
CURLUPART_PORT
Port cannot be URL encoded on set.
CURLUPART_PATH
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.
CURLUPART_QUERY
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 didn't 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 encoded.
The question mark in the URL is not part of the actual query
contents.
CURLUPART_FRAGMENT
The hash sign in the URL is not part of the actual fragment con-
tents.
FLAGS
The flags argument is zero, one or more bits set in a bitmask.
CURLU_NON_SUPPORT_SCHEME
If set, allows curl_url_set(3) to set a non-supported scheme.
CURLU_URLENCODE
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 con-
version.
This URL encoding is charset unaware and will convert the input
on a byte-by-byte manner.
CURLU_DEFAULT_SCHEME
If set, will make libcurl allow the URL to be set without a
scheme and then sets that to the default scheme: HTTPS. Over-
rides the CURLU_GUESS_SCHEME option if both are set.
CURLU_GUESS_SCHEME
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.
RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
went fine.
If this function returns an error, no URL part is returned.
EXAMPLE
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
/* change it to an FTP URL */
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
}
curl_url_cleanup(url);
AVAILABILITY
Added in curl 7.62.0
SEE ALSO
curl_url_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),
libcurl 7.63.0 November 06, 2018 curl_url_set(3)