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
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 compile with 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 functions 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. “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 generally 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 elements.

STANDARDS
HTML5 compatible with the draft standard of February 2014.

AUTHORS
The kcgihtml library was written by Kristaps Dzonsons <kristaps@bsd.lv>.