1curl_url_set(3) libcurl Manual curl_url_set(3)
2
6 curl_url_set - set a URL part
7
9 #include <curl/curl.h>
10 CURLUcode curl_url_set(CURLU *url,
12 CURLUPart part,
13 const char *content,
14 unsigned int flags)
15
17 Given the url handle of an already parsed URL, this function lets the
18 user set/update individual pieces of it.
19 The part argument should identify the particular URL part (see list be‐
21 low) to set or change, with content pointing to a null-terminated
22 string with the new contents for that URL part. The contents should be
23 in the form and encoding they'd use in a URL: URL encoded.
24 The application does not have to keep content around after a successful
26 call.
27 Setting a part to a NULL pointer will effectively remove that part's
29 contents from the CURLU handle.
30 By default, this API only accepts URLs using schemes for protocols that
32 are supported built-in. To make libcurl parse URLs generically even for
33 schemes it does not know about, the CURLU_NON_SUPPORT_SCHEME flags bit
34 must be set. Otherwise, this function returns CURLUE_UNSUPPORTED_SCHEME
35 on URL schemes it does not recognize.
36 The flags argument is a bitmask with independent features.
38
40 CURLUPART_URL
41 Allows the full URL of the handle to be replaced. If the handle
42 already is populated with a URL, the new URL can be relative to
43 the previous.
44 When successfully setting a new URL, relative or absolute, the
46 handle contents will be replaced with the information of the
47 newly set URL.
48 Pass a pointer to a null-terminated string to the url parameter.
50 The string must point to a correctly formatted "RFC 3986+" URL
51 or be a NULL pointer.
52 CURLUPART_SCHEME
54 Scheme cannot be URL decoded on set. libcurl only accepts set‐
55 ting schemes up to 40 bytes long.
56 CURLUPART_USER
58 CURLUPART_PASSWORD
60 CURLUPART_OPTIONS
62 CURLUPART_HOST
64 The host name. If it is IDNA the string must then be encoded as
65 your locale says or UTF-8 (when WinIDN is used). If it is a
66 bracketed IPv6 numeric address it may contain a zone id (or you
67 can use CURLUPART_ZONEID).
68 CURLUPART_ZONEID
70 If the host name is a numeric IPv6 address, this field can also
71 be set.
72 CURLUPART_PORT
74 Port cannot be URL encoded on set. The given port number is pro‐
75 vided as a string and the decimal number must be between 1 and
76 65535. Anything else will return an error.
77 CURLUPART_PATH
79 If a path is set in the URL without a leading slash, a slash
80 will be inserted automatically when this URL is read from the
81 handle.
82 CURLUPART_QUERY
84 The query part will also get spaces converted to pluses when
85 asked to URL encode on set with the CURLU_URLENCODE bit.
86 If used together with the CURLU_APPENDQUERY bit, the provided
88 part will be appended on the end of the existing query - and if
89 the previous part did not end with an ampersand (&), an amper‐
90 sand will be inserted before the new appended part.
91 When CURLU_APPENDQUERY is used together with CURLU_URLENCODE,
93 the first '=' symbol will not be URL encoded.
94 The question mark in the URL is not part of the actual query
96 contents.
97 CURLUPART_FRAGMENT
99 The hash sign in the URL is not part of the actual fragment con‐
100 tents.
101
103 The flags argument is zero, one or more bits set in a bitmask.
104 CURLU_NON_SUPPORT_SCHEME
106 If set, allows curl_url_set(3) to set a non-supported scheme.
107 CURLU_URLENCODE
109 When set, curl_url_set(3) URL encodes the part on entry, except
110 for scheme, port and URL.
111 When setting the path component with URL encoding enabled, the
113 slash character will be skipped.
114 The query part gets space-to-plus conversion before the URL con‐
116 version.
117 This URL encoding is charset unaware and will convert the input
119 on a byte-by-byte manner.
120 CURLU_DEFAULT_SCHEME
122 If set, will make libcurl allow the URL to be set without a
123 scheme and then sets that to the default scheme: HTTPS. Over‐
124 rides the CURLU_GUESS_SCHEME option if both are set.
125 CURLU_GUESS_SCHEME
127 If set, will make libcurl allow the URL to be set without a
128 scheme and it instead "guesses" which scheme that was intended
129 based on the host name. If the outermost sub-domain name matches
130 DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme will be
131 used, otherwise it picks HTTP. Conflicts with the CURLU_DE‐
132 FAULT_SCHEME option which takes precedence if both are set.
133 CURLU_NO_AUTHORITY
135 If set, skips authority checks. The RFC allows individual
136 schemes to omit the host part (normally the only mandatory part
137 of the authority), but libcurl cannot know whether this is per‐
138 mitted for custom schemes. Specifying the flag permits empty au‐
139 thority sections, similar to how file scheme is handled.
140 CURLU_PATH_AS_IS
142 When set for CURLUPART_URL, this makes libcurl skip the normal‐
143 ization of the path. That is the procedure where curl otherwise
144 removes sequences of dot-slash and dot-dot etc. The same option
145 used for transfers is called CURLOPT_PATH_AS_IS(3).
146 CURLU_ALLOW_SPACE
148 If set, a the URL parser allows space (ASCII 32) where possible.
149 The URL syntax does normally not allow spaces anywhere, but they
150 should be encoded as %20 or '+'. When spaces are allowed, they
151 are still not allowed in the scheme. When space is used and al‐
152 lowed in a URL, it will be stored as-is unless CURLU_URLENCODE
153 is also set, which then makes libcurl URL-encode the space be‐
154 fore stored. This affects how the URL will be constructed when
155 curl_url_get(3) is subsequently used to extract the full URL or
156 individual parts. (Added in 7.78.0)
157
159 CURLUcode rc;
160 CURLU *url = curl_url();
161 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
162 if(!rc) {
163 char *scheme;
164 /* change it to an FTP URL */
165 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
166 }
167 curl_url_cleanup(url);
168
170 Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
171
173 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
174 went fine. See the libcurl-errors(3) man page for the full list with
175 descriptions.
176 A URL string passed on to curl_url_set(3) for the CURLUPART_URL part,
178 must be shorter than 8000000 bytes otherwise it returns CURLUE_MAL‐
179 FORMED_INPUT (added in 7.65.0).
180 If this function returns an error, no URL part is set.
182
184 curl_url_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),
185 curl_url_strerror(3), CURLOPT_CURLU(3)
186libcurl 7.85.0 June 12, 2022 curl_url_set(3)