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         CURLU *h = curl_url();
17

CLEANUP

19       When done with it, clean it up with curl_url_cleanup(3)
20         curl_url_cleanup(h);
21

DUPLICATE

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

PARSING

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

REDIRECT

41       When a handle already contains info about a URL, setting a relative URL
42       will make it "redirect" to adapt to it.
43         rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
44

GET URL

46       The  CURLU handle represents a URL and you can easily extract that with
47       curl_url_get(3):
48         char *url;
49         rc = curl_url_get(h, CURLUPART_URL, &url, 0);
50         curl_free(url);
51       The zero in the fourth argument is a bitmask for changing specific fea‐
52       tures.
53

GET PARTS

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

SET PARTS

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

CURLU_APPENDQUERY

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

AVAILABILITY

114       The URL API was introduced in libcurl 7.62.0.
115
116       A URL with a literal IPv6 address can be parsed even when IPv6  support
117       is not enabled.
118