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