GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
KHTTP_TEMPLATEX(3) FreeBSD Library Functions Manual KHTTP_TEMPLATEX(3)

khttp_templatex, khttp_templatex_buf, khttp_templatex_fd
emit filled-in templates for kcgi

library “libkcgi”

#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);

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 sequences. 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 sequence, 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 processing.

Otherwise, the input is passed to x->writer 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 to x->fbk, if not NULL, or passed directly 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.

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.

These return an enum kcgi_err indicating the error state:
No error occurred.
Memory allocation failed.
A system call failed. For example, writing to the output stream failed, or khttp_template() failed to open(2) filename.
t->cb returned 0.

If the x->writer function returns anything but KCGI_OK, the return code is passed as the return value.

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

kcgi(3), khttp_body(3), khttp_parse(3), khttp_template(3), khttp_write(3)

Written by Kristaps Dzonsons <kristaps@bsd.lv>.
June 12, 2022 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.