Provided by: libcurl4-doc_7.88.1-8ubuntu1_all bug


       libcurl-url - URL interface overview


       The URL interface provides functions for parsing and generating URLs.


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


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


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


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


       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,
                           "", 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.


       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);


       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);
       The zero in the fourth argument is a bitmask for changing specific features.


       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 are done with it!


       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, "", 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.


       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 "". 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 "".

       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


       The URL API was introduced in libcurl 7.62.0.


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