FreeBSD Manual Pages
KHTTP_TEMPLATEX(3) Library Functions Manual KHTTP_TEMPLATEX(3) NAME khttp_templatex, khttp_templatex_buf, 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_templatex(const struct ktemplate *t, const char *filename, const struct ktemplatex *x, void *arg); enum kcgi_err khttp_templatex_buf(const struct ktemplate *t, const char *buf, size_t sz, const struct ktemplatex *x, void *arg); enum kcgi_err khttp_templatex_fd(const struct ktemplate *t, int fd, const char *filename, const struct ktemplatex *x, void *arg); DESCRIPTION Modify input by replacing keys in a template. This generalises the khttp_template(3) family of functions with generic writing functions. 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. They further accept an extension x consisting of the following: writer A writing function for writing input that does not match key se- quences. If it is invoked and the return value is not KCGI_OK, templating stops and the return value is returned to the caller. fbk A fall-back function invoked if a key sequences was not found in the c->key array. This accepts the key sequence, length of the se- quence, and arg. If NULL, key sequences not found are passed to writer. If t is NULL, the input is passed through to x->writer without any process- ing. Otherwise, the input is passed to x->writer until a key sequence in encoun- tered 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 to x->fbk, if not NULL, or passed di- rectly to x->writer otherwise. The different input types are khttpx_template(), which reads input from the file filename; khttpx_template_buf(), which reads from a binary buffer buf of length sz; and khttpx_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 back- slash, \@@, the backslash is removed and it's emitted as @@. A key sequence may not contain an escaped pair: this is parsed as a back- slash 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. If the x->writer function returns anything but KCGI_OK, the return code is passed as the return value. EXAMPLES The following simple example takes a buffer buf and applies the replacement template of two values, writing it to the current context req. It stores the result in the given buffer out. static int writer(size_t idx, void *arg) { struct kcgi_buf *p = arg; if (idx == 0) kcgi_buf_puts(p, "foo-value"); else if (idx == 1) kcgi_buf_puts(p, "bar-value"); return 1; } enum kcgi_err format(struct kcgi_buf *out) { const char *const keys[] = { "foo", "bar" }; struct ktemplate t = { .key = keys, .keysz = 2, .arg = out, .cb = writer }; struct ktemplatex x = { .writer = kcgi_buf_write, .fbk = NULL }; const char *in = "foo=@@foo@@, bar=@@bar@@"; memset(out, 0, sizeof(struct kcgi_buf)); return khttp_templatex_buf (&t, in, strlen(in), &x, out); } The function will produce "foo=foo-value, bar=bar-value". SEE ALSO kcgi(3), khttp_body(3), khttp_parse(3), khttp_template(3), khttp_write(3) AUTHORS Written by Kristaps Dzonsons <kristaps@bsd.lv>. FreeBSD ports 15.quarterly $Mdocdate$ KHTTP_TEMPLATEX(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SYNTAX | RETURN VALUES | EXAMPLES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=khttp_templatex&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>