libcurl-url(3)

1libcurl(3)                   libcurl url interface                  libcurl(3)
2
3
4

NAME

6       libcurl-url - URL interface overview
7

DESCRIPTION

9       The  URL interface provides a set of functions for parsing and generat‐
10       ing URLs.
11

INCLUDE

13       You still only include <curl/curl.h> in your code. Note  that  the  URL
14       API was introduced in 7.62.0.
15

CREATE

17       Create a handle that holds URL info and resources with curl_url(3):
18
19         CURLU *h = curl_url();
20

CLEANUP

22       When done with it, clean it up with curl_url_cleanup(3):
23
24         curl_url_cleanup(h);
25

DUPLICATE

27       When   you   need   a   copy  of  a  handle,  just  duplicate  it  with
28       curl_url_dup(3):
29
30         CURLU *nh = curl_url_dup(h);
31

PARSING

33       By "setting" a URL to the  handle  with  curl_url_set(3),  the  URL  is
34       parsed  and  stored in the handle. If the URL is not syntactically cor‐
35       rect it will return an error instead.
36
37         rc = curl_url_set(h, CURLUPART_URL,
38                           "https://example.com:449/foo/bar?name=moo", 0);
39
40       The zero in the fourth argument is a bitmask for changing specific fea‐
41       tures.
42
43       If  successful,  this stores the URL in its individual parts within the
44       handle.
45

REDIRECT

47       When a handle already contains info about a URL, setting a relative URL
48       will make it "redirect" to adapt to it.
49
50         rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
51

GET URL

53       The  `CURLU`  handle  represents  a URL and you can easily extract that
54       with curl_url_get(3):
55
56         char *url;
57         rc = curl_url_get(h, CURLUPART_URL, &url, 0);
58         curl_free(url);
59
60       The zero in the fourth argument is a bitmask for changing specific fea‐
61       tures.
62

GET PARTS

64       When  a  URL  has  been  parsed or parts have been set, you can extract
65       those pieces from the handle at any time.
66
67         rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
68         rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
69         rc = curl_url_get(h, CURLUPART_USER, &user, 0);
70         rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
71         rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
72         rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
73         rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
74         rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
75
76       Extracted parts are not URL decoded unless the user also  asks  for  it
77       with the CURLU_URLDECODE flag set in the fourth bitmask argument.
78
79       Remember to free the returned string with curl_free(3) when you're done
80       with it!
81

SET PARTS

83       A user set individual URL parts, either after having parsed a full  URL
84       or instead of parsing such.
85
86         rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
87         rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
88         rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
89         rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
90         rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
91         rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
92         rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
93         rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
94
95       Set  parts  are  not  URL  encoded unless the user asks for it with the
96       `CURLU_URLENCODE` flag.
97

APPENDQUERY

99       An application can append a string to the right end of the  query  part
100       with the `CURLU_APPENDQUERY` flag to curl_url_set(3).
101
102       Imagine  a handle that holds the URL `https://example.com/?shoes=2`. An
103       application can then add the string `hat=1`  to  the  query  part  like
104       this:
105
106         rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
107
108       It will even notice the lack of an ampersand (`&`) separator so it will
109       inject one too, and the handle's full URL will then equal  `https://ex‐
110       ample.com/?shoes=2&hat=1`.
111
112       The  appended  string can of course also get URL encoded on add, and if
113       asked to URL encode, the encoding process will skip the '='  character.
114       For example, append `candy=N&N` to what we already have, and URL encode
115       it to deal with the ampersand in the data:
116
117         rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
118                           CURLU_APPENDQUERY | CURLU_URLENCODE);
119
120       Now the URL looks like
121         https://example.com/?shoes=2&hat=1&candy=N%26N`
122