Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
curl_url_get(3) | libcurl | curl_url_get(3) |
NAME
curl_url_get - extract a part from a URLSYNOPSIS
#include <curl/curl.h>
CURLUcode curl_url_get(const CURLU *url,
CURLUPart part,
char **content,
unsigned int flags);
DESCRIPTION
Given a url handle of a URL object, this function extracts an individual piece or the full URL from it.FLAGS
The flags argument is zero, one or more bits set in a bitmask.- CURLU_DEFAULT_PORT
- If the handle has no port stored, this option makes curl_url_get(3) return the default port for the used scheme.
- CURLU_DEFAULT_SCHEME
- If the handle has no scheme stored, this option makes curl_url_get(3) return the default scheme instead of error.
- CURLU_NO_DEFAULT_PORT
- Instructs curl_url_get(3) to not return a port number if it matches the default port for the scheme.
- CURLU_URLDECODE
-
Asks curl_url_get(3) to URL decode the contents before returning it. It does not decode the scheme, the port number or the full URL.
- CURLU_URLENCODE
-
If set, curl_url_get(3) URL encodes the host name part when a full URL is retrieved. If not set (default), libcurl returns the URL with the host name "raw" to support IDN names to appear as-is. IDN host names are typically using non-ASCII bytes that otherwise gets percent-encoded.
- CURLU_PUNYCODE
-
If set and CURLU_URLENCODE is not set, and asked to retrieve the CURLUPART_HOST or CURLUPART_URL parts, libcurl returns the host name in its punycode version if it contains any non-ASCII octets (and is an IDN name).
- CURLU_PUNY2IDN
-
If set and asked to retrieve the CURLUPART_HOST or CURLUPART_URL parts, libcurl returns the host name in its IDN (International Domain Name) UTF-8 version if it otherwise is a punycode version. If the punycode name cannot be converted to IDN correctly, libcurl returns CURLUE_BAD_HOSTNAME.
PARTS
- CURLUPART_URL
-
When asked to return the full URL, curl_url_get(3) returns a normalized and possibly cleaned up version using all available URL parts.
- CURLUPART_SCHEME
- Scheme cannot be URL decoded on get.
- CURLUPART_USER
- CURLUPART_PASSWORD
- CURLUPART_OPTIONS
- The options field is an optional field that might follow the password in the userinfo part. It is only recognized/used when parsing URLs for the following schemes: pop3, smtp and imap. The URL API still allows users to set and get this field independently of scheme when not parsing full URLs.
- CURLUPART_HOST
-
The host name. If it is an IPv6 numeric address, the zone id is not part of it but is provided separately in CURLUPART_ZONEID. IPv6 numerical addresses are returned within brackets ([]).
- CURLUPART_ZONEID
- If the host name is a numeric IPv6 address, this field might also be set.
- CURLUPART_PORT
- A port cannot be URL decoded on get. This number is returned in a string just like all other parts. That string is guaranteed to hold a valid port number in ASCII using base 10.
- CURLUPART_PATH
- The part is always at least a slash ('/') even if no path was supplied in the URL. A URL path always starts with a slash.
- CURLUPART_QUERY
-
The initial question mark that denotes the beginning of the query part is a delimiter only. It is not part of the query contents.
- CURLUPART_FRAGMENT
- The initial hash sign that denotes the beginning of the fragment is a delimiter only. It is not part of the fragment contents.
EXAMPLE
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
}
AVAILABILITY
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.RETURN VALUE
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.SEE ALSO
curl_url(3), curl_url_cleanup(3), curl_url_dup(3), curl_url_set(3), curl_url_strerror(3), CURLOPT_CURLU(3)December 4, 2023 | libcurl 8.5.0 |