1curl_url_set(3) libcurl 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 This function call has no particular maximum length for any provided
38 input string. In the real world, excessively long field in URLs will
39 cause problems even if this API accepts them.
40 When setting or updating contents of individual URL parts, this API
42 might accept data that would not be otherwise possible to set in the
43 string when it gets populated as a result of a full URL parse. Beware.
44 If done so, extracting a full URL later on from such components might
45 render an invalid URL.
46 The flags argument is a bitmask with independent features.
48
50 CURLUPART_URL
51 Allows the full URL of the handle to be replaced. If the handle
52 already is populated with a URL, the new URL can be relative to
53 the previous.
54 When successfully setting a new URL, relative or absolute, the
56 handle contents will be replaced with the information of the
57 newly set URL.
58 Pass a pointer to a null-terminated string to the url parameter.
60 The string must point to a correctly formatted "RFC 3986+" URL
61 or be a NULL pointer.
62 Unless CURLU_NO_AUTHORITY is set, a blank host name is not al‐
64 lowed in the URL.
65 CURLUPART_SCHEME
67 Scheme cannot be URL decoded on set. libcurl only accepts set‐
68 ting schemes up to 40 bytes long.
69 CURLUPART_USER
71 CURLUPART_PASSWORD
73 CURLUPART_OPTIONS
75 The options field is an optional field that might follow the
76 password in the userinfo part. It is only recognized/used when
77 parsing URLs for the following schemes: pop3, smtp and imap.
78 This function however allows users to independently set this
79 field at will.
80 CURLUPART_HOST
82 The host name. If it is IDNA the string must then be encoded as
83 your locale says or UTF-8 (when WinIDN is used). If it is a
84 bracketed IPv6 numeric address it may contain a zone id (or you
85 can use CURLUPART_ZONEID).
86 Unless CURLU_NO_AUTHORITY is set, a blank host name is not al‐
88 lowed to set.
89 CURLUPART_ZONEID
91 If the host name is a numeric IPv6 address, this field can also
92 be set.
93 CURLUPART_PORT
95 Port cannot be URL encoded on set. The given port number is pro‐
96 vided as a string and the decimal number must be between 1 and
97 65535. Anything else will return an error.
98 CURLUPART_PATH
100 If a path is set in the URL without a leading slash, a slash
101 will be prepended automatically.
102 CURLUPART_QUERY
104 The query part will also get spaces converted to pluses when
105 asked to URL encode on set with the CURLU_URLENCODE bit.
106 If used together with the CURLU_APPENDQUERY bit, the provided
108 part is appended on the end of the existing query.
109 The question mark in the URL is not part of the actual query
111 contents.
112 CURLUPART_FRAGMENT
114 The hash sign in the URL is not part of the actual fragment con‐
115 tents.
116
118 The flags argument is zero, one or more bits set in a bitmask.
119 CURLU_APPENDQUERY
121 Can be used when setting the CURLUPART_QUERY component. The pro‐
122 vided new part will then instead be appended at the end of the
123 existing query - and if the previous part did not end with an
124 ampersand (&), an ampersand gets inserted before the new ap‐
125 pended part.
126 When CURLU_APPENDQUERY is used together with CURLU_URLENCODE,
128 the first '=' symbol will not be URL encoded.
129 CURLU_NON_SUPPORT_SCHEME
131 If set, allows curl_url_set(3) to set a non-supported scheme.
132 CURLU_URLENCODE
134 When set, curl_url_set(3) URL encodes the part on entry, except
135 for scheme, port and URL.
136 When setting the path component with URL encoding enabled, the
138 slash character will be skipped.
139 The query part gets space-to-plus conversion before the URL con‐
141 version.
142 This URL encoding is charset unaware and will convert the input
144 on a byte-by-byte manner.
145 CURLU_DEFAULT_SCHEME
147 If set, will make libcurl allow the URL to be set without a
148 scheme and then sets that to the default scheme: HTTPS. Over‐
149 rides the CURLU_GUESS_SCHEME option if both are set.
150 CURLU_GUESS_SCHEME
152 If set, will make libcurl allow the URL to be set without a
153 scheme and it instead "guesses" which scheme that was intended
154 based on the host name. If the outermost sub-domain name matches
155 DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme will be
156 used, otherwise it picks HTTP. Conflicts with the CURLU_DE‐
157 FAULT_SCHEME option which takes precedence if both are set.
158 CURLU_NO_AUTHORITY
160 If set, skips authority checks. The RFC allows individual
161 schemes to omit the host part (normally the only mandatory part
162 of the authority), but libcurl cannot know whether this is per‐
163 mitted for custom schemes. Specifying the flag permits empty au‐
164 thority sections, similar to how file scheme is handled.
165 CURLU_PATH_AS_IS
167 When set for CURLUPART_URL, this makes libcurl skip the normal‐
168 ization of the path. That is the procedure where curl otherwise
169 removes sequences of dot-slash and dot-dot etc. The same option
170 used for transfers is called CURLOPT_PATH_AS_IS(3).
171 CURLU_ALLOW_SPACE
173 If set, the URL parser allows space (ASCII 32) where possible.
174 The URL syntax does normally not allow spaces anywhere, but they
175 should be encoded as %20 or '+'. When spaces are allowed, they
176 are still not allowed in the scheme. When space is used and al‐
177 lowed in a URL, it will be stored as-is unless CURLU_URLENCODE
178 is also set, which then makes libcurl URL-encode the space be‐
179 fore stored. This affects how the URL will be constructed when
180 curl_url_get(3) is subsequently used to extract the full URL or
181 individual parts. (Added in 7.78.0)
182 CURLU_DISALLOW_USER
184 If set, the URL parser will not accept embedded credentials for
185 the CURLUPART_URL, and will instead return CURLUE_USER_NOT_AL‐
186 LOWED for such URLs.
187
189 CURLUcode rc;
190 CURLU *url = curl_url();
191 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
192 if(!rc) {
193 char *scheme;
194 /* change it to an FTP URL */
195 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
196 }
197 curl_url_cleanup(url);
198
200 Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
201
203 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
204 went fine. See the libcurl-errors(3) man page for the full list with
205 descriptions.
206 The input string passed to curl_url_set(3) must be shorter than eight
208 million bytes. Otherwise this function returns CURLUE_MALFORMED_INPUT.
209 If this function returns an error, no URL part is set.
211
213 curl_url_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),
214 curl_url_strerror(3), CURLOPT_CURLU(3)
215libcurl 8.2.1 June 08, 2023 curl_url_set(3)