KHTML_ELEM(3)

💅 KHTML_ELEM(3) — the khtml_elem page, bestie edition

okay so real quick: this is a page from the Library Functions Manual for libkcgihtml, and the star of the show is khtml_elem. it opens element scopes. that's the whole vibe. let's get into it 🫶

📚 LIBRARY

you'll find this in the library “libkcgihtml” — that's the one you're linking against, no cap ✨

🌸 SYNOPSIS

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

enum kcgi_err
khtml_elem(struct khtmlreq *req, enum kelem elem);

like, include all five of those headers or your build is gonna be giving nothing but errors 💀

✨ DESCRIPTION ✨

so what it does: it opens a new scope of element elem on the current element stack of req — and req is the one you already initialised with khtml_open(3). main character energy, honestly 👑

and then you close those scopes with khtml_closeelem(3), khtml_closeto(3). or khtml_close(3). (yes, that period is in the original, i'm not touching it, iykyk 🙈)

💡 tiny but crucial detail: if elem is a “void” element (self-closing, like KELEM_LINK) or KELEM_DOCTYPE, the scope gets immediately closed — so like, no new scope gets opened at all. it does the thing and dips 🦋

🔥 RETURN VALUES

returns an enum kcgi_err telling you the error state. so like, the vibe check result 💅

• KCGI_OK — success!! not an error!! we love a win 🌈
• KCGI_ENOMEM — internal memory allocation failure, and that includes hitting the maximum number of possible HTML scopes. yeah, there's a cap, and you found it 😭
• KCGI_HUP — the output connection got terminated. for FastCGI connections, you should release the current connection with khttp_free(3) and reenter the parse loop. 🫶
• KCGI_FORM — the connection is still expecting headers with khttp_head(3). this one means khttp_body(3) didn't return with success, or it just wasn't invoked at all. also: for FastCGI connections, release the current connection with khttp_free(3) and reenter the parse loop. same drill, different error 🎀
• KCGI_SYSTEM — internal system error while writing to the output stream. rough. 💀

---

🎀 EXAMPLES 🎀

this one outputs a simple HTML page. it assumes r is a struct kreq pointer. and for brevity — bestie, respect the brevity — it does no error checking whatsoever. iconic but dangerous 🙈

khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_TEXT_HTML]);
khttp_body(r);
khtml_open(&req, r, 0);
khtml_elem(&req, KELEM_DOCTYPE);
khtml_elem(&req, KELEM_HTML);
khtml_elem(&req, KELEM_HEAD);
khtml_elem(&req, KELEM_TITLE);
khtml_puts(&req, "Hello, world.");
khtml_close(&req);

look at all those khtml_elem calls stacking up — that's a stack, bestie, it's literally in the name 🧚

👀 SEE ALSO

• kcgihtml(3)

⭐ STANDARDS

the referenced HTML5 standard is HTML5.2 at https://www.w3.org/TR/html52 — go read it if you're feeling academic 💜

👑 AUTHORS

written by Kristaps Dzonsons <kristaps@bsd.lv>. king behavior, fr fr 🌸

---

and that's the page!! 💖 this build came from Debian, dated $Mdocdate$, and it's page KHTML_ELEM(3) of the Library Functions Manual — slay, go open some scopes 🦋✨🎀