KHTTP_TEMPLATE(3) Library Functions Manual KHTTP_TEMPLATE(3)

NAME

khttp_template, khttp_templatex, khttp_template_buf, khttp_templatex_buf, khttp_template_fd, khttp_templatex_fdemit filled-in templates for kcgi

LIBRARY

library “libkcgi”

SYNOPSIS

#include <sys/types.h>
#include <stdarg.h>
#include <stddef.h>
#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, 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);
int
khttp_template_fd(struct kreq *req, const struct ktemplate *t, int fd, const char *filename);
int
khttp_templatex_fd(const struct ktemplate *t, int fd, const char *filename, const struct ktemplatex *tx, void *arg);

DESCRIPTION

The khttp_template, khttp_templatex, khttp_template_buf, khttp_templatex_buf, khttp_template_fd, and khttp_templatex_fd 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, khttp_templatex_buf, and khttp_templatex_fd 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 buffer version of this set accept a buffer buf of length sz. The file descriptor version accepts fd, an open file descriptor that will be passed to mmap(2) and on to the buffer version; and the associated filename, which is used for error reporting and may be NULL (in which case <unknown descriptor> is used). The file version accepts fname, the file that will be opened read-only and passed into the file descriptor version.
When khttp_templatex_buf is invoked (it is internally 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, khttp_templatex_fd, 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.
The khttp_template, khttp_template_buf, and khttp_template_fd functions fail if the callback function returns 0. The khttp_templatex, khttp_atemplatex_buf, and khttp_atemplatex_fd 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 or file descriptor versions.
September 22, 2017 OpenBSD 5.8