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 Setting a part to a NULL pointer will effectively remove that part's
26 contents from the CURLU handle.
27 The flags argument is a bitmask with independent features.
29
31 CURLUPART_URL
32 Allows the full URL of the handle to be replaced. If the handle
33 already is populated with a URL, the new URL can be relative to
34 the previous.
35 When successfully setting a new URL, relative or absolute, the
37 handle contents will be replaced with the information of the
38 newly set URL.
39 Pass a pointer to a null-terminated string to the url parameter.
41 The string must point to a correctly formatted "RFC 3986+" URL
42 or be a NULL pointer.
43 CURLUPART_SCHEME
45 Scheme cannot be URL decoded on set.
46 CURLUPART_USER
48 CURLUPART_PASSWORD
50 CURLUPART_OPTIONS
52 CURLUPART_HOST
54 The host name. If it is IDNA the string must then be encoded as
55 your locale says or UTF-8 (when WinIDN is used). If it is a
56 bracketed IPv6 numeric address it may contain a zone id (or you
57 can use CURLUPART_ZONEID).
58 CURLUPART_ZONEID
60 If the host name is a numeric IPv6 address, this field can also
61 be set.
62 CURLUPART_PORT
64 Port cannot be URL encoded on set. The given port number is pro‐
65 vided as a string and the decimal number must be between 1 and
66 65535. Anything else will return an error.
67 CURLUPART_PATH
69 If a path is set in the URL without a leading slash, a slash
70 will be inserted automatically when this URL is read from the
71 handle.
72 CURLUPART_QUERY
74 The query part will also get spaces converted to pluses when
75 asked to URL encode on set with the CURLU_URLENCODE bit.
76 If used together with the CURLU_APPENDQUERY bit, the provided
78 part will be appended on the end of the existing query - and if
79 the previous part didn't end with an ampersand (&), an ampersand
80 will be inserted before the new appended part.
81 When CURLU_APPENDQUERY is used together with CURLU_URLENCODE,
83 the first '=' symbol will not be URL encoded.
84 The question mark in the URL is not part of the actual query
86 contents.
87 CURLUPART_FRAGMENT
89 The hash sign in the URL is not part of the actual fragment con‐
90 tents.
91
93 The flags argument is zero, one or more bits set in a bitmask.
94 CURLU_NON_SUPPORT_SCHEME
96 If set, allows curl_url_set(3) to set a non-supported scheme.
97 CURLU_URLENCODE
99 When set, curl_url_set(3) URL encodes the part on entry, except
100 for scheme, port and URL.
101 When setting the path component with URL encoding enabled, the
103 slash character will be skipped.
104 The query part gets space-to-plus conversion before the URL con‐
106 version.
107 This URL encoding is charset unaware and will convert the input
109 on a byte-by-byte manner.
110 CURLU_DEFAULT_SCHEME
112 If set, will make libcurl allow the URL to be set without a
113 scheme and then sets that to the default scheme: HTTPS. Over‐
114 rides the CURLU_GUESS_SCHEME option if both are set.
115 CURLU_GUESS_SCHEME
117 If set, will make libcurl allow the URL to be set without a
118 scheme and it instead "guesses" which scheme that was intended
119 based on the host name. If the outermost sub-domain name
120 matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme
121 will be used, otherwise it picks HTTP. Conflicts with the
122 CURLU_DEFAULT_SCHEME option which takes precedence if both are
123 set.
124 CURLU_NO_AUTHORITY
126 If set, skips authority checks. The RFC allows individual
127 schemes to omit the host part (normally the only mandatory part
128 of the authority), but libcurl cannot know whether this is per‐
129 mitted for custom schemes. Specifying the flag permits empty au‐
130 thority sections, similar to how file scheme is handled.
131 CURLU_PATH_AS_IS
133 When set for CURLUPART_URL, this makes libcurl skip the normal‐
134 ization of the path. That's the procedure where curl otherwise
135 removes sequences of dot-slash and dot-dot etc. The same option
136 used for transfers is called CURLOPT_PATH_AS_IS(3).
137
139 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
140 went fine.
141 A URL string passed on to curl_url_set(3) for the CURLUPART_URL part,
143 must be shorter than 8000000 bytes otherwise it returns CURLUE_MAL‐
144 FORMED_INPUT (added in 7.65.0).
145 If this function returns an error, no URL part is set.
147
149 CURLUcode rc;
150 CURLU *url = curl_url();
151 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
152 if(!rc) {
153 char *scheme;
154 /* change it to an FTP URL */
155 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
156 }
157 curl_url_cleanup(url);
158
160 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
161
163 curl_url_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),
164 CURLOPT_CURLU(3),
165libcurl 7.76.1 February 21, 2021 curl_url_set(3)