KHTTP_TEMPLATE(3)

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

LIBRARY
libkcgi

SYNOPSIS
#include <stdarg.h>
#include <stdint.h>
#include <unistd.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, const struct ktemplatex *tx, 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, const struct ktemplatex *tx, 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.

These functions all accept struct ktemplate, which consists of the following fields:

const char *const *key
    An array of keys. When the template is parsed and encounters a key, it is looked up in this array.

size_t keysz
    The number of keys in key.

void *arg
    The optional argument passed to cb.

int (*cb)(size_t index, void *arg)
    The callback function called when a key in key is found. The index is the position in key, which is always less than keysz. The argument is given by the arg field to the structure.

The khttp_templatex and khttp_templatex_buf functions accept struct ktemplatex, which has the following fields:

int (*writer)(const char *b, size_t sz, void *arg)
    The function that writes data in b of size sz with private argument arg that's passed to the functions. This may not be NULL.

int (*fbk)(const char *k, size_t sz, void *arg)
    If the given key k of length sz is not found in the template array, this function is invoked. The arg is given within each function's struct ktemplate. This will usually use writer to write any data.

The khttp_template and khttp_templatex functions memory-map the regular file fname and pass the buffer into khttp_template_buf and khttp_templatex_buf, respectively. The khttp_template_buf function further invokes khttp_templatex_buf with khttp_write(3) as the writer function and req as the optional argument. So in the end, khttp_templatex_buf is always invoked.

When khttp_templatex_buf is invoked (it is used by all of the templating functions), 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 first 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. If not found and one of khttp_templatex or khttp_templatex_buf was used with a fallthrough callback function, the fallthrough callback function will be invoked. In either event, if the callback returns zero, khttp_templatex_buf fails. This will trigger the failure of any invoking function such as khttp_template. If the key is not found and there is no fallthrough callback, it is emitted as opaque text.

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>.

CAVEATS
The khttp_template and khttp_templatex functions need access to the file-system. So if you're sandboxing your application, you should read the files before the sandbox and use the buffer versions.