KHTTP_TEMPLATE(3)

NAME
khttp_template, khttp_templatex, khttp_template_buf, khttp_templatex_buf - emit filled-in templates for kcgi

LIBRARY
libkcgi

SYNOPSIS
#include <stdint.h>
#include <kcgi.h>
int
khttp_template(struct kreq *req, const struct ktemplate *t, const char *fname);
int
khttp_templatex(const struct ktemplate *t, const char *fname, ktemplate_writef fp, void *arg);
int
khttp_template_buf(struct kreq *req, const struct ktemplate *t, const char *buf, size_t sz);
int
khttp_templatex_buf(const struct ktemplate *t, const char *buf, size_t sz, ktemplate_writef fp, void *arg);

DESCRIPTION
The khttp_template, khttp_templatex, khttp_template_buf, and khttp_templatex_buf functions comprise a template system for a kcgi(3) context allocated with khttp_parse(3). They may only be called after khttp_body(3), else behaviour is undefined.

khttp_template() and khttp_templatex() memory-map the regular file fname and pass the string into khttp_template_buf() and khttp_templatex_buf(). khttp_template() uses the khttp_write(3) family of functions for writing data, while khttp_templatex() uses a function callback fp and opaque pointer arg for applications to override this behaviour. Passing NULL as fp causes undefined behaviour.

khttp_template_buf() and khttp_templatex_buf() template an input buffer directly using khttp_write(3) and friends for khttp_template_buf() or fp and opaque pointer arg for khttp_templatex_buf(). The buffer is emitted until a @@foo@@ sequence (two "at" signs followed by a key, followed by a trailing pair of "at" signs) is encountered. The key is then looked up in the t argument's key array of size keysz. If found, the callback cb is invoked with the key index and the optional argument arg. Callbacks may continue to process, emit HTML trees, and so on. If it returns 0, khttp_template_buf fails. If the key is not found, it is emitted as opaque text via khttp_write(3) and friends.

If t is NULL, the buffer (or file) is emitted without any processing.

RETURN VALUES
khttp_template returns 0 if the fstat(2), open(2), or mmap(2) functions fail on the file, or the file is too large to map.

Both khttp_template and khttp_template_buf fail if the callback function returns 0. The khttp_templatex and khttp_atemplatex_buf functions may also return 0 if the write functions return 0.

SEE ALSO
kcgi(3), khttp_body(3), khttp_parse(3), khttp_write(3)

AUTHORS
The khttp_template library was written by Kristaps Dzonsons <kristaps@bsd.lv>.