KHTTP_HEAD(3)

💅 khttp_head(3) — like, the header-emitting queen of libkcgi

Okay bestie, sit down, we're doing a manual page for khttp_head(3) from the Library Functions Manual (yes the whole library is libkcgi and yes she's iconic). This one is short and sweet, and fr fr you're gonna get it in like two minutes.

---

✨ NAME ✨

khttp_head — emit exactly one HTTP header for kcgi. One. Just one. That's her whole job and she does it slayfully 💅

---

📚 LIBRARY 📚

library “libkcgi” 🫶

---

🌈 SYNOPSIS 🌈

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

enum kcgi_err
khttp_head(struct kreq *req, const char *key, const char *fmt, ...);

extern const char *const kresps[KRESP__MAX];

That's it. That's the whole vibe check. Four includes, one function, one global array. Clean. Minimal. Main character energy 👑

---

🦋 DESCRIPTION 🦋

So khttp_head() takes a kcgi(3) context req — like, one that was already initialised by khttp_parse(3), don't get ahead of yourself bestie — and it emits one HTTP header with the given HTTP response key. Just one. If you want twelve headers you call her twelve times, that's the deal 🎀

The fmt string and the variable arguments that follow it use printf(3) syntax, and together they form the corresponding value in the HTTP response. So fmt is the template, the varargs fill it in, periodt.

⚠️ Okay this part matters so much: this function may only be invoked prior to khttp_body(3). If you call it after? The behaviour is undefined. Not "a little weird", not "we'll figure it out", undefined. Do not test her. 😭

The kresps global array is indexed with the KRESP_* symbolic constants that live in <kcgi.h>, and it gives you the standard HTTP key names. Use it for the key argument so you don't typo "Content-Tpye" and ruin your whole life. Like, just use it. It's right there. 🧚

And hmm, also: go read khttp_body(3) for the whole discussion about the "Content-Encoding" header…

🚨 Do not specify this header before doing so! Like, read khttp_body(3) first and then talk to me about "Content-Encoding". I'm serious. 💀

---

💜 RETURN VALUES 💜

khttp_head() returns an enum kcgi_err telling you the error state. So, the cast of characters:

• KCGI_OK — success! Not an error! We love a win 💖
• KCGI_ENOMEM — internal memory allocation failure. The memory was not giving 😭
• KCGI_SYSTEM — internal system error writing to the output stream. Something went sideways on the way out 📉
• KCGI_HUP — the output connection has been terminated. And like, for FastCGI connections specifically? You should release the current connection with khttp_free(3) and then reenter the parse loop. That's the whole protocol, iykyk 🔥

---

🍓 EXAMPLES 🍓

Say you wanna emit a session cookie — one-year expiration date, ckey as the key, cval as the value, for the global path. You'd invoke the following, bestie. Assume r is a pointer to a struct kreq that was successfully initialised by khttp_parse(3) ✨

const char *ckey = "foo", *cval = "bar";
char buf[64];

khttp_epoch2str(time(NULL) + 31536000, buf, 64);

khttp_head(r, kresps[KRESP_SET_COOKIE],
  "%s=%s; path=/; expires=%s", ckey, cval, buf);

Look at that. 31536000 seconds, one whole year, buf of 64 bytes, kresps[KRESP_SET_COOKIE] instead of a hand-typed string. That's the way. Ate and left no crumbs 🍪

---

👀 SEE ALSO 👀

kcgi(3), khttp_body(3), khttp_parse(3)

(the holy trinity, honestly 🌸)

---

📜 STANDARDS 📜

• RFC 2616, section 14: “Header Field Definitions”.
• The example references RFC 6265, section 4.1: “Set-Cookie”.

Both cited, both exact, no cap 📖

---

🫶 AUTHORS 🫶

The khttp_head() function was written by Kristaps Dzonsons <kristaps@bsd.lv>. Thank you king, we are obsessed 👑

---

and that's the whole page!! This cutie came from the Debian build, dated $Mdocdate$, and it's KHTTP_HEAD(3) forever and always. Bye bestie, go emit some headers responsibly 💖✨🎀🦋