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