KJSON_OPEN(3)

💖 KJSON_OPEN(3) — ok so this is the kcgijson one, bestie 🎀

Hey bestie! Welcome to KJSON_OPEN(3), a page from the Library Functions Manual. Yes it's a manual page, no it's not boring, stay with me 💅

✨ NAME ✨

kjson_open — open a kcgijson context. That's it, that's the whole job, and she does it flawlessly 🫶

📚 LIBRARY 📚

You're gonna need the library “libkcgijson”. Iconic. No cap.

🌸 SYNOPSIS 🌸

Okay so before you do literally anything, you gotta pull in all these headers, in exactly this order, don't @ me:

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

enum kcgi_err
kjson_open(struct kjsonreq *req, struct kreq *r);

💫 DESCRIPTION 💫

So basically kjson_open zeroes and initialises a brand-new context req, and it rides on top of the underlying kcgi(3) context r — the one you already got from khttp_parse(3) or khttp_fcgi_parse(3). Slay.

⚠️ Timing check bestie: you should only call this after khttp_body(3). Not before. Not during. After. Periodt.

Once she's initialised, the scope that's open is the “root” scope. And the root scope is a little different from the others — it accepts content similar to what arrays take, like kjson_putstring(3), instead of kjson_putstringp(3). Iykyk 🦋

💀 And listen — if kcgi_writer_disable(3) has been called, your process will be killed with an uncatchable signal. Not a warning. Not an error return. Straight up murdered. So like… don't do that 🙈

👑 RETURN VALUES 👑

She returns an enum kcgi_err telling you what the error state is. Here's the whole squad:

• KCGI_OK — Success! Not an error, we love to see it 🎉
• KCGI_ENOMEM — Internal memory allocation failure 😭 the allocator said no.
• KCGI_HUP — The output connection has been terminated. For FastCGI connections, you should release the current connection with khttp_free(3) and reenter the parse loop. (Relatable, honestly.)
• KCGI_FORM — The connection is still expecting headers via khttp_head(3). This means khttp_body(3) either didn't return success or literally was never invoked. For FastCGI connections, same deal: release the current connection with khttp_free(3) and reenter the parse loop.
• KCGI_SYSTEM — Internal system error while writing to the output stream. Rude.

🔥 EXAMPLES 🔥

Okay here's the cute little example that outputs a simple JSON page. It assumes r is a struct kreq pointer. And for brevity, it does zero error checking — main character energy, honestly:

khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_APP_JSON]);
khttp_body(r);
kjson_open(&req, r);
kjson_obj_open(&req);
kjson_putstringp(&req, "foo", "bar");
kjson_close(&req);

Look at her go 🥹✨

🌈 SEE ALSO 🌈

• kcgijson(3) — go read that one next, bestie, it's giving essential.

💜 AUTHORS 💜

Written by Kristaps Dzonsons <kristaps@bsd.lv>. Thanks king 👑

---

✨ that's the whole page ✨ This came from the Debian build, version $Mdocdate$, and she's filed under KJSON_OPEN(3). Now go open some JSON contexts, you got this 🎀💖