libcurl-url(3)

🌸 NAME 🌸

libcurl-url - URL interface overview. Yep bestie, you're on the libcurl-url(3) page from the Library Functions Manual, and it's literally the URL era 💅✨

🦋 DESCRIPTION 🦋

Okay so the URL interface is the friend group that handles parsing URLs and generating URLs. That's the whole vibe. 🌈

🎀 INCLUDE 🎀

You still only include <curl/curl.h> in your code. That's it, no extra includes, no cap 🧚

✨ CREATE ✨

Make a handle that holds URL info and resources with curl_url(3), like this:

CURLU *h = curl_url();

🫧 CLEANUP 🫧

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

curl_url_cleanup(h);

💖 DUPLICATE 💖

Need a copy of a handle? Just duplicate it with curl_url_dup(3):

CURLU *nh = curl_url_dup(h);

🔥 PARSING 🔥

Set a URL on the handle with curl_url_set(3), and the URL gets parsed and stored in the handle. If the URL isn't syntactically correct, you get an error back instead. No silent mess, periodt.

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

That 0 in the fourth argument is a bitmask for changing specific features.

When it works, the URL ends up stored in the handle as its individual parts. Cute.

🌀 REDIRECT 🌀

If a handle already has info about a URL, setting a relative URL makes it "redirect" to that. Iconic.

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

That 0 in the fourth argument is a bitmask for changing specific features. Yes, again. 💅

🌈 GET PARTS 🌈

Once a URL has been parsed or parts have been set, you can pull those pieces out of the handle at any time. It's giving build-your-own-URL.

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.

And remember to free the returned string with curl_free(3) when you're done with it. Do not ghost your allocations, bestie 😭

🍓 SET PARTS 🍓

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

rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 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.

🧚 CURLU_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). Slay.

Picture a handle holding 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 notices there's no ampersand (&) separator and injects one, so the handle's full URL then equals 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 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

https://example.com/?shoes=2&hat=1&candy=N%26N

💀 NOTES 💀

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

🫶 SEE ALSO 🫶

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

💖 That's the whole page, bestie! From libcurl, dated 2026-10-12, page libcurl-url(3). Byeeee! 🫶✨