khttp_template,
khttp_templatex,
khttp_template_buf,
khttp_templatex_buf,
khttp_template_fd,
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_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);
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 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 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() functions 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.
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
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.
If the
key is found in
t->key, the key sequence is removed from
the buffer 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 processing.
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.
kcgi(3),
khttp_body(3),
khttp_parse(3),
khttp_write(3)
These functions were written by
Kristaps
Dzonsons
<
kristaps@bsd.lv>.
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.