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 functions for parsing and generating URLs.
10

INCLUDE

12       You still only include <curl/curl.h> in your code.
13

CREATE

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

CLEANUP

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

DUPLICATE

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

PARSING

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

REDIRECT

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

GET URL

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

GET PARTS

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

SET PARTS

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

APPENDQUERY

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

AVALABILITY

122       The URL API was introduced in libcurl 7.62.0.
123