1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: libcurl-url 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_URL (3) 9 - curl_url (3) 10 - curl_url_cleanup (3) 11 - curl_url_dup (3) 12 - curl_url_get (3) 13 - curl_url_set (3) 14 - curl_url_strerror (3) 15Protocol: 16 - All 17Added-in: 7.62.0 18--- 19 20# NAME 21 22libcurl-url - URL interface overview 23 24# DESCRIPTION 25 26The URL interface provides functions for parsing and generating URLs. 27 28# INCLUDE 29 30You still only include \<curl/curl.h\> in your code. 31 32# CREATE 33 34Create a handle that holds URL info and resources with curl_url(3): 35~~~c 36 CURLU *h = curl_url(); 37~~~ 38 39# CLEANUP 40 41When done with it, clean it up with curl_url_cleanup(3) 42~~~c 43 curl_url_cleanup(h); 44~~~ 45 46# DUPLICATE 47 48When you need a copy of a handle, just duplicate it with curl_url_dup(3): 49~~~c 50 CURLU *nh = curl_url_dup(h); 51~~~ 52 53# PARSING 54 55By setting a URL to the handle with curl_url_set(3), the URL is parsed 56and stored in the handle. If the URL is not syntactically correct it returns 57an error instead. 58~~~c 59 rc = curl_url_set(h, CURLUPART_URL, 60 "https://example.com:449/foo/bar?name=moo", 0); 61~~~ 62 63The zero in the fourth argument is a bitmask for changing specific features. 64 65If successful, this stores the URL in its individual parts within the handle. 66 67# REDIRECT 68 69When a handle already contains info about a URL, setting a relative URL makes 70it "redirect" to that. 71~~~c 72 rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); 73~~~ 74 75# GET URL 76 77The **CURLU** handle represents a URL and you can easily extract that with 78curl_url_get(3): 79~~~c 80 char *url; 81 rc = curl_url_get(h, CURLUPART_URL, &url, 0); 82 curl_free(url); 83~~~ 84The zero in the fourth argument is a bitmask for changing specific features. 85 86# GET PARTS 87 88When a URL has been parsed or parts have been set, you can extract those 89pieces from the handle at any time. 90 91~~~c 92 rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0); 93 rc = curl_url_get(h, CURLUPART_HOST, &host, 0); 94 rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0); 95 rc = curl_url_get(h, CURLUPART_PATH, &path, 0); 96 rc = curl_url_get(h, CURLUPART_PORT, &port, 0); 97 rc = curl_url_get(h, CURLUPART_QUERY, &query, 0); 98 rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0); 99 rc = curl_url_get(h, CURLUPART_USER, &user, 0); 100 rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0); 101~~~ 102 103Extracted parts are not URL decoded unless the user also asks for it with the 104*CURLU_URLDECODE* flag set in the fourth bitmask argument. 105 106Remember to free the returned string with curl_free(3) when you are done 107with it. 108 109# SET PARTS 110 111A user set individual URL parts, either after having parsed a full URL or 112instead of parsing such. 113 114~~~c 115 rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0); 116 rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0); 117 rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0); 118 rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0); 119 rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0); 120 rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0); 121 rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0); 122 rc = curl_url_set(urlp, CURLUPART_USER, "john", 0); 123 rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0); 124~~~ 125 126Set parts are not URL encoded unless the user asks for it with the 127*CURLU_URLENCODE* flag. 128 129# CURLU_APPENDQUERY 130 131An application can append a string to the right end of the query part with the 132*CURLU_APPENDQUERY* flag to curl_url_set(3). 133 134Imagine a handle that holds the URL "https://example.com/?shoes=2". An 135application can then add the string "hat=1" to the query part like this: 136 137~~~c 138 rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); 139~~~ 140 141It notices the lack of an ampersand (&) separator and injects one, and the 142handle's full URL then equals "https://example.com/?shoes=2&hat=1". 143 144The appended string can of course also get URL encoded on add, and if asked to 145URL encode, the encoding process skips the '=' character. For example, append 146"candy=N&N" to what we already have, and URL encode it to deal with the 147ampersand in the data: 148 149~~~c 150 rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", 151 CURLU_APPENDQUERY | CURLU_URLENCODE); 152~~~ 153 154Now the URL looks like 155 156~~~c 157 https://example.com/?shoes=2&hat=1&candy=N%26N 158~~~ 159 160# NOTES 161 162A URL with a literal IPv6 address can be parsed even when IPv6 support is not 163enabled. 164
