NAME

       libcurl-url - URL interface overview

DESCRIPTION

       The URL interface provides a set of functions for parsing and generating URLs.

INCLUDE

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

CREATE

       Create a handle that holds URL info and resources with curl_url(3):

         CURLU *h = curl_url();

CLEANUP

       When done with it, clean it up with curl_url_cleanup(3):

         curl_url_cleanup(h);

DUPLICATE

       When you need a copy of a handle, just duplicate it with curl_url_dup(3):

         CURLU *nh = curl_url_dup(h);

PARSING

       By "setting" a URL to the handle with curl_url_set(3), the URL is parsed and stored in the
       handle. If the URL is not syntactically correct it will return an error instead.

         rc = curl_url_set(h, CURLUPART_URL,
                           "https://example.com:449/foo/bar?name=moo", 0);

       The zero in the fourth argument is a bitmask for changing specific features.

       If successful, this stores the URL in its individual parts within the handle.

REDIRECT

       When  a  handle  already  contains  info  about a URL, setting a relative URL will make it
       "redirect" to adapt to it.

         rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);

GET URL

       The `CURLU` handle represents a URL and you can easily extract that with curl_url_get(3):

         char *url;
         rc = curl_url_get(h, CURLUPART_URL, &url, 0);
         curl_free(url);

       The zero in the fourth argument is a bitmask for changing specific features.

GET PARTS

       When a URL has been parsed or parts have been set, you can extract those pieces  from  the
       handle at any time.

         rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
         rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
         rc = curl_url_get(h, CURLUPART_USER, &user, 0);
         rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
         rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
         rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
         rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
         rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);

       Extracted  parts  are  not  URL  decoded  unless  the  user  also  asks  for  it  with the
       CURLU_URLDECODE flag set in the fourth bitmask argument.

       Remember to free the returned string with curl_free(3) when you're done with it!

SET PARTS

       A user set individual URL parts, either after having parsed  a  full  URL  or  instead  of
       parsing such.

         rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
         rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
         rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
         rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
         rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
         rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
         rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
         rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);

       Set parts are not URL encoded unless the user asks for it with the `CURLU_URLENCODE` flag.

APPENDQUERY

       An  application  can  append  a  string  to  the  right  end  of  the  query part with the
       `CURLU_APPENDQUERY` flag to curl_url_set(3).

       Imagine a handle that holds the URL  `https://example.com/?shoes=2`.  An  application  can
       then add the string `hat=1` to the query part like this:

         rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);

       It  will  even  notice the lack of an ampersand (`&`) separator so it will inject one too,
       and the handle's full URL will then equal `https://example.com/?shoes=2&hat=1`.

       The appended string can of course also get URL encoded on add, and if asked to URL encode,
       the  encoding process will skip the '=' character. For example, append `candy=N&N` to what
       we already have, and URL encode it to deal with the ampersand in the data:

         rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
                           CURLU_APPENDQUERY | CURLU_URLENCODE);

       Now the URL looks like
         https://example.com/?shoes=2&hat=1&candy=N%26N`

SEE ALSO

       curl_url(3),  curl_url_cleanup(3),  curl_url_get(3),   curl_url_dup(3),   curl_url_set(3),
       CURLOPT_URL(3),