manpagez: man pages & more
man libcurl-url(3)
Home | html | info | man
libcurl(3)                          libcurl                         libcurl(3)


       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
         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
       returns an error instead.
         rc = curl_url_set(h, CURLUPART_URL,
                           "", 0);

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

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


       When a handle already contains info about a URL, setting a relative URL
       makes it "redirect" to that.
         rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);


       The CURLU handle represents a URL and you can easily extract that with
         char *url;
         rc = curl_url_get(h, CURLUPART_URL, &url, 0);
       The zero in the fourth argument is a bitmask for changing specific


       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_FRAGMENT, &fragment, 0);
         rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
         rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
         rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
         rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
         rc = curl_url_get(h, CURLUPART_QUERY, &query, 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_ZONEID, &zoneid, 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_FRAGMENT, "anchor", 0);
         rc = curl_url_set(urlp, CURLUPART_HOST, "", 0);
         rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
         rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
         rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
         rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 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_ZONEID, "eth0", 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

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

       It notices the lack of an ampersand (&) separator and injects one, and
       the handle's full URL then equals "".

       The appended string can of course also get URL encoded on add, and if
       asked to URL encode, the encoding process skips 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.

       A URL with a literal IPv6 address can be parsed even when IPv6 support
       is not enabled.


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

libcurl 8.4.0                 September 26, 2023                    libcurl(3)

curl 8.4.0 - Generated Thu Oct 26 08:44:28 CDT 2023
© 2000-2024
Individual documents may contain additional copyright information.