1curl_url_get(3) libcurl Manual curl_url_get(3)
2
3
4
6 curl_url_get - extract a part from a URL
7
9 #include <curl/curl.h>
10
11 CURLUcode curl_url_get(CURLU *url,
12 CURLUPart what,
13 char **part,
14 unsigned int flags)
15
17 Given the url handle of an already parsed URL, this function lets the
18 user extract individual pieces from it.
19
20 The what argument should be the particular part to extract (see list
21 below) and part points to a 'char *' to get updated to point to a newly
22 allocated string with the contents.
23
24 The flags argument is a bitmask with individual features.
25
26 The returned part pointer must be freed with curl_free(3) after use.
27
29 The flags argument is zero, one or more bits set in a bitmask.
30
31 CURLU_DEFAULT_PORT
32 If the handle has no port stored, this option will make
33 curl_url_get(3) return the default port for the used scheme.
34
35 CURLU_DEFAULT_SCHEME
36 If the handle has no scheme stored, this option will make
37 curl_url_get(3) return the default scheme instead of error.
38
39 CURLU_NO_DEFAULT_PORT
40 Instructs curl_url_get(3) to not return a port number if it
41 matches the default port for the scheme.
42
43 CURLU_URLDECODE
44 Asks curl_url_get(3) to URL decode the contents before returning
45 it. It will not attempt to decode the scheme, the port number or
46 the full URL. ´ The query component will also get plus-to-space
47 conversion as a bonus when this bit is set.
48
49 Note that this URL decoding is charset unaware and you will get
50 a zero terminated string back with data that could be intended
51 for a particular encoding.
52
53 If there's any byte values lower than 32 in the decoded string,
54 the get operation will return an error instead.
55
56 CURLU_URLENCODE
57 If set, will make curl_url_get(3) URL encode the host name part
58 when a full URL is retrieved. If not set (default), libcurl re‐
59 turns the URL with the host name "raw" to support IDN names to
60 appear as-is. IDN host names are typically using non-ASCII bytes
61 that otherwise will be percent-encoded.
62
63 Note that even when not asking for URL encoding, the '%' (byte
64 37) will be URL encoded to make sure the host name remains
65 valid.
66
68 CURLUPART_URL
69 When asked to return the full URL, curl_url_get(3) will return a
70 normalized and possibly cleaned up version of what was previ‐
71 ously parsed.
72
73 CURLUPART_SCHEME
74 Scheme cannot be URL decoded on get.
75
76 CURLUPART_USER
77
78 CURLUPART_PASSWORD
79
80 CURLUPART_OPTIONS
81
82 CURLUPART_HOST
83 The host name. If it is an IPv6 numeric address, the zoneid will
84 not be part of it but is provided separately in CURLU‐
85 PART_ZONEID. IPv6 numerical addresses are returned within brack‐
86 ets ([]).
87
88 CURLUPART_ZONEID
89 If the host name is a numeric IPv6 address, this field might
90 also be set.
91
92 CURLUPART_PORT
93 Port cannot be URL decoded on get.
94
95 CURLUPART_PATH
96 part will be '/' even if no path is supplied in the URL.
97
98 CURLUPART_QUERY
99 The initial question mark that denotes the beginning of the
100 query part is a delimiter only. It is not part of the query
101 contents.
102
103
104 A not-present query will lead part to be set to NULL. A zero-
105 length query will lead part to be set to a zero-length string.
106
107 The query part will also get pluses converted to space when
108 asked to URL decode on get with the CURLU_URLDECODE bit.
109
110 CURLUPART_FRAGMENT
111
113 CURLUcode rc;
114 CURLU *url = curl_url();
115 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
116 if(!rc) {
117 char *scheme;
118 rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
119 if(!rc) {
120 printf("the scheme is %s\n", scheme);
121 curl_free(scheme);
122 }
123 curl_url_cleanup(url);
124 }
125
127 Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
128
130 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
131 went fine. See the libcurl-errors(3) man page for the full list with
132 descriptions.
133
134 If this function returns an error, no URL part is returned.
135
137 curl_url_cleanup(3), curl_url(3), curl_url_set(3), curl_url_dup(3),
138 curl_url_strerror(3), CURLOPT_CURLU(3)
139
140
141
142libcurl 7.85.0 May 17, 2022 curl_url_get(3)