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

FreeBSD Manual Pages

  
 
  

home | help
KHTTP_TEMPLATE(3)      FreeBSD Library Functions Manual	     KHTTP_TEMPLATE(3)

NAME
     khttp_template, khttp_templatex, khttp_template_buf, khttp_templatex_buf,
     khttp_template_fd,	khttp_templatex_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_templatex(const struct ktemplate *t,	const char *filename,
	 const struct ktemplatex *tx, void *arg);

     enum kcgi_err
     khttp_template_buf(struct kreq *req, const	struct ktemplate *t,
	 const char *buf, size_t sz);

     enum kcgi_err
     khttp_templatex_buf(const struct ktemplate	*t, const char *buf,
	 size_t	sz, const struct ktemplatex *tx, void *arg);

     enum kcgi_err
     khttp_template_fd(struct kreq *req, const struct ktemplate	*t, int	fd,
	 const char *filename);

     enum kcgi_err
     khttp_templatex_fd(const struct ktemplate *t, int fd,
	 const char *filename, const struct ktemplatex *tx, void *arg);

DESCRIPTION
     These template functions write a block of HTTP output, replacing certain
     substrings	with variable content.	They operate in	a kcgi(3) context req
     allocated with khttp_parse(3) or khttp_fcgi_parse(3) and may only be
     called after khttp_body(3).

     All template functions accept a const struct ktemplate *t argument	con-
     sisting 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 to the current writing function.  This callback
	     function normally uses khttp_write(3) or tx-_writer to write
	     data.

     The khttp_template(), khttp_template_fd(),	and khttp_template_buf() func-
     tions use khttp_write(3) as the current writing function.

     The khttp_templatex(), khttp_templatex_buf(), and khttp_templatex_fd()
     functions extend this behaviour with an additional	const struct
     ktemplatex	*tx argument having the	following fields:

     enum kcgi_err (*writer)(const char	*b, size_t sz, void *arg)
	     Sets the current writing function that writes sz bytes pointed to
	     by	b.  The	arg argument is	as passed to the function; it may be
	     NULL.  Any	return value but KCGI_OK is considered an error.

     int (*fbk)(const char *k, size_t sz, void *arg)
	     If	an encountered key k of	length sz is not found in t-_key, this
	     function is invoked.  The field t-_arg is passed as the arg.
	     This function normally uses the writing function in tx-_writer to
	     write data.

     The tx-_writer callback may not be	NULL.

     The functions khttp_template() and	khttp_templatex() open filename	in
     read-only mode and	call the descriptor functions.

     The descriptor functions khttp_template_fd() and khttp_templatex_fd()
     read the template from the	open file descriptor fd	using mmap(2) and call
     the buffer	functions.  They only use the filename for error reporting.
     If	it is NULL, "<unknown descriptor>" is used.

     The buffer	functions khttp_template_buf() and khttp_templatex_buf() read
     the template from the buffer buf of length	sz.  If	sz is 0, the template
     is	considered empty and buf is ignored.

   Template language
     Each substring of the template buffer beginning and ending	with a pair of
     "at" signs, @@key@@, is called a "key sequence".  If the "at" pair	is es-
     caped 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.

     If	the key	is found in t-_key, the	key sequence is	removed	from the buf-
     fer and the callback t-_cb	is invoked.  Otherwise,	if the fallthrough
     callback tx-_fbk is not NULL, the key sequence is removed from the	buffer
     and the callback tx-fbk is	invoked.  If the key sequence is not found in
     t-_key and	the fallthrough	callback is NULL, the key sequence is passed
     unchanged to the current writing function.

     If	t is NULL, the whole template is passed	through	without	any process-
     ing.

RETURN VALUES
     These functions 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() or	khttp_templatex()
		  failed to open(2) filename.

     KCGI_FORM	  t-_cb	or tx-_fbk returned 0.

     An	empty template produces	no output, and KCGI_OK is returned.

SEE ALSO
     kcgi(3), khttp_body(3), khttp_parse(3), khttp_write(3)

AUTHORS
     These functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
     The khttp_template() and khttp_templatex()	functions need access to the
     file system.  Read	the files before entering a sandbox and	use the	buffer
     or	file descriptor	versions instead.

FreeBSD	13.0			April 19, 2018			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=khttp_template&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help