KHTTP_TEMPLATE(3)

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

LIBRARY
libkcgi

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_templatex(const struct ktemplate *t, const char *filename, const struct ktemplatex *tx, void *arg);
enum kcgi_err
khttp_template_buf(struct kreq *req, const struct ktemplate *t, const char *buf, size_t sz);
enum kcgi_err
khttp_templatex_buf(const struct ktemplate *t, const char *buf, size_t sz, const struct ktemplatex *tx, void *arg);
enum kcgi_err
khttp_template_fd(struct kreq *req, const struct ktemplate *t, int fd, const char *filename);
enum kcgi_err
khttp_templatex_fd(const struct ktemplate *t, int fd, const char *filename, const struct ktemplatex *tx, void *arg);

DESCRIPTION
These template functions write a block of HTTP output, replacing certain substrings with variable content. They operate in a kcgi(3) context req allocated with khttp_parse(3) or khttp_fcgi_parse(3) and may only be called after khttp_body(3).

All template functions accept a const struct ktemplate *t argument 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 current writing function. This callback function normally uses khttp_write(3) or tx->writer to write data.

The khttp_template(), khttp_template_fd(), and khttp_template_buf() functions use khttp_write(3) as the current writing function.

The khttp_templatex(), khttp_templatex_buf(), and khttp_templatex_fd() functions extend this behaviour with an additional const struct ktemplatex *tx argument having the following fields:

enum kcgi_err (*writer)(const char *b, size_t sz, void *arg)
    Sets the current writing function that writes sz bytes pointed to by b. The arg argument is as passed to the function; it may be NULL. Any return value but KCGI_OK is considered an error.

int (*fbk)(const char *k, size_t sz, void *arg)
    If an encountered key k of length sz is not found in t->key, this function is invoked. The field t->arg is passed as the arg. This function normally uses the writing function in tx->writer to write data.

The tx->writer callback may not be NULL.

The functions khttp_template() and khttp_templatex() open filename in read-only mode and call the descriptor functions.

The descriptor functions khttp_template_fd() and khttp_templatex_fd() read the template from the open file descriptor fd using mmap(2) and call the buffer functions. They only use the filename for error reporting. If it is NULL, "<unknown descriptor>" is used.

The buffer functions khttp_template_buf() and khttp_templatex_buf() read the template from the buffer buf of length sz. If sz is 0, the template is considered empty and buf is ignored.

  Template language
Each substring of the template buffer beginning and ending with a pair of “at” signs, @@key@@, is called a “key sequence”. If the “at” 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.

If the key is found in t->key, the key sequence is removed from the buffer and the callback t->cb is invoked. Otherwise, if the fallthrough callback tx->fbk is not NULL, the key sequence is removed from the buffer and the callback tx-fbk is invoked. If the key sequence is not found in t->key and the fallthrough callback is NULL, the key sequence is passed unchanged to the current writing function.

If t is NULL, the whole template is passed through without any processing.

RETURN VALUES
These functions 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() or khttp_templatex() failed to open(2) filename.

KCGI_FORM
    t->cb or tx->fbk returned 0.

An empty template produces no output, and KCGI_OK is returned.

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

AUTHORS
These functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
The khttp_template() and khttp_templatex() functions need access to the file system. Read the files before entering a sandbox and use the buffer or file descriptor versions instead.