libcurl(3)

🎀 libcurl(3) — the libcurl url interface, but make it cute 🎀

okay so this is the libcurl url interface overview, bestie. it's your URL API cheat sheet, and we're gonna make it make sense. 💅

---

🌸 NAME 🌸

libcurl-url — URL interface overview.

✨ DESCRIPTION ✨

The URL interface gives you a set of functions for parsing and generating URLs. iconic behavior, honestly. 🦋

📦 INCLUDE 📦

You still only include <gnurl/curl.h> in your code. yes, that's the include. also note: 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 you're 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 gets parsed and stored in the handle. If the URL is not syntactically correct, it returns an error instead. no cap. 🫡

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

The 0 in the fourth argument is a bitmask for changing specific features. If it's 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 makes 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 0 in the fourth argument is a bitmask for changing specific features. (yes, again — it's that kind of bitmask 💀)

🧩 GET PARTS 🧩

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

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. And remember to free the returned string with curl_free(3) when you're done with it! don't leave your bestie hanging. 🫶

🛠️ SET PARTS 🛠️

A user can set individual URL parts, either after having parsed a full URL or instead of parsing such. choose your own adventure, bestie. 💅

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. periodt. 💖

🍬 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. slay. ✨

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

---

peace out, bestie 🫶 — source/version: libcurl; date: 10 Sep 2018; manual page: libcurl(3). mwah 💋