KHTTP_TEMPLATE(3)

🌸 NAME 🌸

Okay bestie, this is KHTTP_TEMPLATE(3) from the Library Functions Manual, and it’s literally the page for khttp_template, khttp_template_buf, khttp_template_fd — all about emitting filled-in templates for kcgi. Periodt. ✨

📚 LIBRARY 📚

library “libkcgi” — that’s the one. 💖

🛠️ SYNOPSIS 🛠️

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

enum kcgi_err
khttp_template(struct kreq *req, const struct ktemplate *t,
    const char *filename);

enum kcgi_err
khttp_template_buf(struct kreq *req, const struct ktemplate *t,
    const char *buf, size_t sz);

enum kcgi_err
khttp_template_fd(struct kreq *req, const struct ktemplate *t, int fd,
    const char *filename);

💬 DESCRIPTION 💬

So the whole gig is modifying input by replacing keys in a template. You may only call these after khttp_body(3) — no cap, that’s the rule. Output is written with khttp_write(3) using the req previously allocated with khttp_parse(3) or khttp_fcgi_parse(3). And if you want alternative writers, the khttp_templatex(3) family has your back. 🫶

All functions accept a template t consisting of the following fields:

• const char *const *key — An array of keys to be replaced in the template.
• size_t keysz — The number of keys in t->key.
• void *arg — An optional argument passed to t->cb.
• int (*cb)(size_t index, void *arg) — The callback function invoked when a key at position index, which is always less than t->keysz, is found in t->key. The optional arg is passed to the function. The function must return zero on failure, non-zero on success.

If t is NULL, the input is passed through to khttp_write(3) without any processing.

Otherwise, the input is passed to khttp_write(3) until a key sequence is encountered matching a key in t->key. The callback t->cb is then invoked instead of printing the key sequence. If there are multiple matching keys in t->key, only one is used (which is not yet fixed) 😬. If the key sequence is not found in t->key, it is passed unchanged to khttp_write(3).

The different input types are khttp_template(), which reads input from the file filename; khttp_template_buf(), which reads from a binary buffer buf of length sz; and khttp_template_fd(), which reads from a file descriptor fd with optional file-name fname used only for logging purposes.

🔑 SYNTAX 🔑

Each substring of the input beginning and ending with a pair of “at” signs, @@key@@, is called a "key sequence". Zero-length keys @@@@ are allowed and match empty template keys. If the @@ pair is escaped with a single backslash, \@@, the backslash is removed and it’s emitted as @@.

A key sequence may not contain an escaped pair: this is parsed as a backslash followed by the trailing pair.

🎯 RETURN VALUES 🎯

These return an enum kcgi_err indicating the error state:

• KCGI_OK — No error occurred.
• KCGI_ENOMEM — Memory allocation failed.
• KCGI_SYSTEM — A system call failed. For example, writing to the output stream failed, or khttp_template() failed to open(2) filename.
• KCGI_FORM — t->cb returned 0.

💻 EXAMPLES 💻

The following simple example takes a buffer buf and applies the replacement template of two values, writing it to the current context req.

static int writer(size_t idx, void *arg)
{
  struct kreq *r = arg;
  if (idx == 0)
    khttp_puts(r, "foo-value");
  else if (idx == 1)
    khttp_puts(r, "bar-value");
  return 1;
}

enum kcgi_err format(struct kreq *r)
{
  const char *const keys[] = { "foo", "bar" };
  struct ktemplate t = {
    .key = keys,
    .keysz = 2,
    .arg = r,
    .cb = writer
  };
  const char *buf = "foo=@@foo@@, bar=@@bar@@";
  return khttp_template_buf(r, &t, buf, strlen(buf));
}

The function will produce "foo=foo-value, bar=bar-value".

👀 SEE ALSO 👀

• kcgi(3)
• khttp_body(3)
• khttp_parse(3)
• khttp_templatex(3)
• khttp_write(3)

👑 AUTHORS 👑

Written by Kristaps Dzonsons <kristaps@bsd.lv>.

---

💖 And that’s a wrap, bestie! Source/version: Debian; date: $Mdocdate$; and the page is KHTTP_TEMPLATE(3). Slay, bye! 💅✨