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 The flags argument is a bitmask with independent features.
32
34 CURLUPART_URL
35 Allows the full URL of the handle to be replaced. If the handle
36 already is populated with a URL, the new URL can be relative to
37 the previous.
38 When successfully setting a new URL, relative or absolute, the
40 handle contents will be replaced with the information of the
41 newly set URL.
42 Pass a pointer to a null-terminated string to the url parameter.
44 The string must point to a correctly formatted "RFC 3986+" URL
45 or be a NULL pointer.
46 CURLUPART_SCHEME
48 Scheme cannot be URL decoded on set. libcurl only accepts set‐
49 ting schemes up to 40 bytes long.
50 CURLUPART_USER
52 CURLUPART_PASSWORD
54 CURLUPART_OPTIONS
56 CURLUPART_HOST
58 The host name. If it is IDNA the string must then be encoded as
59 your locale says or UTF-8 (when WinIDN is used). If it is a
60 bracketed IPv6 numeric address it may contain a zone id (or you
61 can use CURLUPART_ZONEID).
62 CURLUPART_ZONEID
64 If the host name is a numeric IPv6 address, this field can also
65 be set.
66 CURLUPART_PORT
68 Port cannot be URL encoded on set. The given port number is pro‐
69 vided as a string and the decimal number must be between 1 and
70 65535. Anything else will return an error.
71 CURLUPART_PATH
73 If a path is set in the URL without a leading slash, a slash
74 will be inserted automatically when this URL is read from the
75 handle.
76 CURLUPART_QUERY
78 The query part will also get spaces converted to pluses when
79 asked to URL encode on set with the CURLU_URLENCODE bit.
80 If used together with the CURLU_APPENDQUERY bit, the provided
82 part will be appended on the end of the existing query - and if
83 the previous part did not end with an ampersand (&), an amper‐
84 sand will be inserted before the new appended part.
85 When CURLU_APPENDQUERY is used together with CURLU_URLENCODE,
87 the first '=' symbol will not be URL encoded.
88 The question mark in the URL is not part of the actual query
90 contents.
91 CURLUPART_FRAGMENT
93 The hash sign in the URL is not part of the actual fragment con‐
94 tents.
95
97 The flags argument is zero, one or more bits set in a bitmask.
98 CURLU_NON_SUPPORT_SCHEME
100 If set, allows curl_url_set(3) to set a non-supported scheme.
101 CURLU_URLENCODE
103 When set, curl_url_set(3) URL encodes the part on entry, except
104 for scheme, port and URL.
105 When setting the path component with URL encoding enabled, the
107 slash character will be skipped.
108 The query part gets space-to-plus conversion before the URL con‐
110 version.
111 This URL encoding is charset unaware and will convert the input
113 on a byte-by-byte manner.
114 CURLU_DEFAULT_SCHEME
116 If set, will make libcurl allow the URL to be set without a
117 scheme and then sets that to the default scheme: HTTPS. Over‐
118 rides the CURLU_GUESS_SCHEME option if both are set.
119 CURLU_GUESS_SCHEME
121 If set, will make libcurl allow the URL to be set without a
122 scheme and it instead "guesses" which scheme that was intended
123 based on the host name. If the outermost sub-domain name matches
124 DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme will be
125 used, otherwise it picks HTTP. Conflicts with the CURLU_DE‐
126 FAULT_SCHEME option which takes precedence if both are set.
127 CURLU_NO_AUTHORITY
129 If set, skips authority checks. The RFC allows individual
130 schemes to omit the host part (normally the only mandatory part
131 of the authority), but libcurl cannot know whether this is per‐
132 mitted for custom schemes. Specifying the flag permits empty au‐
133 thority sections, similar to how file scheme is handled.
134 CURLU_PATH_AS_IS
136 When set for CURLUPART_URL, this makes libcurl skip the normal‐
137 ization of the path. That is the procedure where curl otherwise
138 removes sequences of dot-slash and dot-dot etc. The same option
139 used for transfers is called CURLOPT_PATH_AS_IS(3).
140 CURLU_ALLOW_SPACE
142 If set, a the URL parser allows space (ASCII 32) where possible.
143 The URL syntax does normally not allow spaces anywhere, but they
144 should be encoded as %20 or '+'. When spaces are allowed, they
145 are still not allowed in the scheme. When space is used and al‐
146 lowed in a URL, it will be stored as-is unless CURLU_URLENCODE
147 is also set, which then makes libcurl URL-encode the space be‐
148 fore stored. This affects how the URL will be constructed when
149 curl_url_get(3) is subsequently used to extract the full URL or
150 individual parts. (Added in 7.78.0)
151
153 CURLUcode rc;
154 CURLU *url = curl_url();
155 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
156 if(!rc) {
157 char *scheme;
158 /* change it to an FTP URL */
159 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
160 }
161 curl_url_cleanup(url);
162
164 Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
165
167 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
168 went fine. See the libcurl-errors(3) man page for the full list with
169 descriptions.
170 A URL string passed on to curl_url_set(3) for the CURLUPART_URL part,
172 must be shorter than 8000000 bytes otherwise it returns CURLUE_MAL‐
173 FORMED_INPUT (added in 7.65.0).
174 If this function returns an error, no URL part is set.
176
178 curl_url_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),
179 curl_url_strerror(3), CURLOPT_CURLU(3)
180libcurl 7.82.0 January 08, 2022 curl_url_set(3)