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.
49 CURLUPART_USER
51 CURLUPART_PASSWORD
53 CURLUPART_OPTIONS
55 CURLUPART_HOST
57 The host name. If it is IDNA the string must then be encoded as
58 your locale says or UTF-8 (when WinIDN is used). If it is a
59 bracketed IPv6 numeric address it may contain a zone id (or you
60 can use CURLUPART_ZONEID).
61 CURLUPART_ZONEID
63 If the host name is a numeric IPv6 address, this field can also
64 be set.
65 CURLUPART_PORT
67 Port cannot be URL encoded on set. The given port number is pro‐
68 vided as a string and the decimal number must be between 1 and
69 65535. Anything else will return an error.
70 CURLUPART_PATH
72 If a path is set in the URL without a leading slash, a slash
73 will be inserted automatically when this URL is read from the
74 handle.
75 CURLUPART_QUERY
77 The query part will also get spaces converted to pluses when
78 asked to URL encode on set with the CURLU_URLENCODE bit.
79 If used together with the CURLU_APPENDQUERY bit, the provided
81 part will be appended on the end of the existing query - and if
82 the previous part didn't end with an ampersand (&), an ampersand
83 will be inserted before the new appended part.
84 When CURLU_APPENDQUERY is used together with CURLU_URLENCODE,
86 the first '=' symbol will not be URL encoded.
87 The question mark in the URL is not part of the actual query
89 contents.
90 CURLUPART_FRAGMENT
92 The hash sign in the URL is not part of the actual fragment con‐
93 tents.
94
96 The flags argument is zero, one or more bits set in a bitmask.
97 CURLU_NON_SUPPORT_SCHEME
99 If set, allows curl_url_set(3) to set a non-supported scheme.
100 CURLU_URLENCODE
102 When set, curl_url_set(3) URL encodes the part on entry, except
103 for scheme, port and URL.
104 When setting the path component with URL encoding enabled, the
106 slash character will be skipped.
107 The query part gets space-to-plus conversion before the URL con‐
109 version.
110 This URL encoding is charset unaware and will convert the input
112 on a byte-by-byte manner.
113 CURLU_DEFAULT_SCHEME
115 If set, will make libcurl allow the URL to be set without a
116 scheme and then sets that to the default scheme: HTTPS. Over‐
117 rides the CURLU_GUESS_SCHEME option if both are set.
118 CURLU_GUESS_SCHEME
120 If set, will make libcurl allow the URL to be set without a
121 scheme and it instead "guesses" which scheme that was intended
122 based on the host name. If the outermost sub-domain name
123 matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme
124 will be used, otherwise it picks HTTP. Conflicts with the
125 CURLU_DEFAULT_SCHEME option which takes precedence if both are
126 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's 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.
151
153 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
154 went fine.
155 A URL string passed on to curl_url_set(3) for the CURLUPART_URL part,
157 must be shorter than 8000000 bytes otherwise it returns CURLUE_MAL‐
158 FORMED_INPUT (added in 7.65.0).
159 If this function returns an error, no URL part is set.
161
163 CURLUcode rc;
164 CURLU *url = curl_url();
165 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
166 if(!rc) {
167 char *scheme;
168 /* change it to an FTP URL */
169 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
170 }
171 curl_url_cleanup(url);
172
174 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
175
177 curl_url_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),
178 CURLOPT_CURLU(3),
179libcurl 7.79.1 May 31, 2021 curl_url_set(3)