Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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 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
	     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	pro-

     Otherwise,	the input is passed to x-_writer until a key sequence in en-
     countered 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 buf-
     fer buf of	length sz; and khttpx_template_fd(), which reads from a	file
     descriptor	fd with	optional file-name fname used only for logging pur-

     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 back-
     slash followed by the trailing pair.

     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)

     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.

     The following simple example takes	a buffer buf and applies the replace-
     ment 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 <>.

FreeBSD	13.0		       October 17, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help