KCGIHTML(3) BSD Library Functions Manual KCGIHTML(3)NAME
kcgihtml, khtml_attr, khtml_attrx, khtml_close, khtml_closeelem,
khtml_closeto, khtml_double, khtml_elem, khtml_elemat, khtml_entity,
khtml_int, khtml_ncr, khtml_open, khtml_putc, khtml_puts, khtml_write —
HTML handling functions for kcgi
LIBRARY
library “libkcgihtml”
SYNOPSIS
#include <stdint.h>
#include <kcgi.h>
#include <kcgihtml.h>
void
khtml_attr(struct khtmlreq *req, enum kelem elem, ...);
void
khtml_attrx(struct khtmlreq *req, enum kelem elem, ...);
int
khtml_close(struct khtmlreq *req);
int
khtml_closeelem(struct khtmlreq *req, size_t count);
int
khtml_closeto(struct khtmlreq *req, size_t pos);
void
khtml_double(struct khtmlreq *req, double val);
void
khtml_elem(struct khtmlreq *req, enum kelem elem);
size_t
khtml_elemat(struct khtmlreq *req);
void
khtml_entity(struct khtmlreq *req, enum entity entity);
void
khtml_int(struct khtmlreq *req, int64_t val);
void
khtml_ncr(struct khtmlreq *req, uint16_t ncr);
void
khtml_open(struct khtmlreq *req, struct kreq *r);
void
khtml_putc(struct khtmlreq *req, char c);
void
khtml_puts(struct khtmlreq *req, const char *cp);
int
khtml_write(const char *cp, size_t sz, void *arg);
DESCRIPTION
The kcgihtml functions extend kcgi(3) output with HTML elements,
attributes, and text for contexts allocated with khttp_parse(3). None of
these functions may be called before khttp_body(3).
To use these functions, you must include the <kcgihtml.h> header and com‐
pile with library “kcgihtml”, for example,
% cc -I/usr/local/include -c -o sample.o sample.c
% cc -L/usr/local/lib -o sample -lkcgihtml -lkcgi -lz
All of the kcgihtml functions accept a struct khtmlreq object. To use
this properly, open a context with khtml_open(), then use whichever func‐
tions you wish, then close the context with khtml_close().
khtml_attr()
Open the scope of element elem with matching key-value pairs in
the varargs for its attributes. The maximum number of nested
scopes is fixed at 128. The terminating attribute key must be
ATTR__MAX.
khtml_attrx()
Like khtml_attr(), but accepts an addition parameter enum attrx
following the enum attr that specifies the attribute type. This
is useful for non-string attributes, for example, invoking with
KATTR_WIDTH, KATTRX_INT, and 100 will properly render the integer
type. The types route through to khtml_puts() for KATTRX_STRING,
khtml_int() for KATTRX_INT, khtml_double() for KATTRX_DOUBLE.
khtml_close()
Close an HTML context as opened with khtml_open(). This will
also close any open elements. You should not use the object
after invoking this function.
khtml_closeelem()
Close the last count scopes. This will call abort(3) if count
exceeds the number of open scopes. If count is zero, this will
close all scopes. Do not close HTML "void" elements such as
⟨meta⟩.
khtml_closeto()
Close until a certain level pos in the HTML tree, which must be
at or above the current level. Usually used with khtml_elemat().
If there are fewer open contexts than the requested, this will
only close the available open contexts.
khtml_double()
Wrapper over khtml_puts() for formatting a double-precision
floating point. This uses a buffer of size 256 and the %g to
snprintf(3), which may not be what you want.
khtml_elem()
Invokes khtml_attr() with no attributes.
khtml_elemat()
Save the current point in the HTML tree. Useful for saving a
khtml_closeto() rollback point.
khtml_entity()
Emit the numeric character reference for entity.
khtml_int()
Wrapper over khtml_puts() for formatting a 64-bit signed integer.
khtml_ncr()
Emit the numeric character reference ncr.
khtml_putc()
Emit the text c, escaping it (e.g., ‘>’) for HTML if necessary.
khtml_puts()
Invokes khtml_putc() for each character of the nil-terminated
string cp.
khtml_write()
Like khtml_puts(), but working with a sized buffer. This is gen‐
erally for use with khttp_template(3).
RETURN VALUES
The khtml_close(), khtml_closeelem(), and khtml_closeat() return zero if
the requested statement overruns (or underruns) the stack of open ele‐
ments.
STANDARDS
HTML5 compatible with the draft standard of February 2014.
AUTHORS
The kcgihtml library was written by Kristaps Dzonsons ⟨kristaps@bsd.lv⟩.
BSD April 29, 2024 BSD
