KHTTP_TEMPLATE(3) Library Functions Manual KHTTP_TEMPLATE(3)
NAME
khttp_template, khttp_template_buf, khttp_template_fd — emit filled-in templates for kcgi
LIBRARY
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_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
Modify input by replacing keys in a template. May only be called after khttp_body(3). Output is written with khttp_write(3) using the req previously allocated with khttp_parse(3) or khttp_fcgi_parse(3). The khttp_templatex(3) family allows for alternative writers.
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 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 in 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 <[email protected]>. GNU $Mdocdate$ KHTTP_TEMPLATE(3)