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