KHTTP_URLABS(3)

💅 KHTTP_URLABS(3) — like, the URL-formatting one, bestie

okay so real quick before we dive in: this is a page from the Library Functions Manual for libkcgi, and it's literally just about gluing together absolute URLs. it's giving "small function, big responsibility" energy. let's go 🎀

---

🌸 NAME

khttp_urlabs, khttp_vurlabs — URL formatting for kcgi 💖

📚 LIBRARY

library “libkcgi” — that's the one, that's our girl 🫶

✨ SYNOPSIS

first you gotta invite the headers in, no cap:

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>

then the two functions themselves, looking all cute and symmetrical:

char *
khttp_urlabs(enum kscheme scheme, const char *host, uint16_t port,
    const char *path, ...);

char *
khttp_vurlabs(enum kscheme scheme, const char *host, uint16_t port,
    const char *path, va_list ap);

💫 DESCRIPTION

so what does it do? it formats an absolute (full) URL. that's it, that's the whole vibe. 🔥

fun fact time: in some standards, the host is called the "authority" — like, very demure, very mysterious, but it's just the host ok 💅

the shapes it can produce are:

scheme://host:port/path?key=val
scheme://host:port/path
scheme:path

here's where it gets interesting, bestie, pay attention 👀:

• if you pass a NULL or empty host, the whole // + host + port chunk gets omitted. gone. not invited to the party.
• if host is non-empty and not NULL, and path is also non-empty and not NULL, then path gets a mandatory slash prepended. like, the slash is not optional, it's the main character.
• if port is zero, it's omitted. periodt. and port only gets used at all if host is non-empty and not NULL — otherwise it's just sitting there, irrelevant.
• the variable arguments come in pairs, terminated by a single NULL. first of each pair is the query string key, second is the value. both are char *. and if the query string value is NULL? it gets rendered as an empty string. no drama, no crash. 🧚

⚠️ important caveat energy: only the query string pairs get URL-encoded. so you, yes you, the caller, have to make sure the characters in host and path are actually valid. this function is not your babysitter, she's your bestie. 🙈

also, the deprecated form of these functions, kutil_urlabs(), should no longer be used. she's retired, let her rest 💀

🦋 RETURN VALUES

returns newly-allocated strings that must be freed with free(3) — or NULL if allocation fails. that's it. free your memory, bestie, it's the responsible thing to do 💜

🌈 EXAMPLES

okay this is the fun part, examples!! 😭

to print a full URL:

khttp_urlabs(KSCHEME_HTTPS, foo.com, 80, b, c, d, NULL);

this assigns https://foo.com:80/b?c=d — slay, look at her go ✨

setting the port to zero eliminates the port:

khttp_urlabs(KSCHEME_HTTPS, foo.com, 0, b, c, d, NULL);

this assigns https://foo.com/b?c=d — see, no port, clean, iconic 🎀

an empty path component ends with the domain (or query string):

khttp_urlabs(KSCHEME_HTTPS, foo.com, 0, , c, d, NULL);

this assigns https://foo.com?c=d — the path just dipped, honestly relatable 🫶

to use a host-less scheme, specify a NULL or empty host:

khttp_urlabs(KSCHEME_MAILTO, NULL, 0, k@b.com, NULL);

this assigns mailto:k@b.com — no host needed, she's independent 💅

👑 AUTHORS

Written by Kristaps Dzonsons <kristaps@bsd.lv>. king behavior, honestly. 🌟

💀 CAVEATS

so, the tea ☕: these functions can currently be used to create semantically invalid URLs like https:?foo=bar by omitting components required for the scheme. yes, really. she'll let you do it. she won't stop you. 😭

semantically-correct URLs are the responsibility of the caller — that's you, bestie, no cap.

this behaviour may be verified for correctness in later versions of the software. so like, watch this space, iykyk 👀

---

and that's the whole page, mwah 💋 — this little number came from Debian, stamped $Mdocdate$, and it's filed under KHTTP_URLABS(3). go forth and format your URLs correctly, i'm obsessed with you 🧚‍♀️💖