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 output for kcgi

LIBRARY
libkcgihtml

SYNOPSIS
#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
#include <kcgihtml.h>
enum kcgi_err
khtml_attr(struct khtmlreq *req, enum kelem elem, ...);
enum kcgi_err
khtml_attrx(struct khtmlreq *req, enum kelem elem, ...);
enum kcgi_err
khtml_close(struct khtmlreq *req);
enum kcgi_err
khtml_closeelem(struct khtmlreq *req, size_t count);
enum kcgi_err
khtml_closeto(struct khtmlreq *req, size_t pos);
enum kcgi_err
khtml_double(struct khtmlreq *req, double val);
enum kcgi_err
khtml_elem(struct khtmlreq *req, enum kelem elem);
enum kcgi_err
khtml_elemat(struct khtmlreq *req);
enum kcgi_err
khtml_entity(struct khtmlreq *req, enum entity entity);
enum kcgi_err
khtml_int(struct khtmlreq *req, int64_t val);
enum kcgi_err
khtml_ncr(struct khtmlreq *req, uint16_t ncr);
enum kcgi_err
khtml_open(struct khtmlreq *req, struct kreq *r, int opts);
enum kcgi_err
khtml_putc(struct khtmlreq *req, char c);
enum kcgi_err
khtml_puts(struct khtmlreq *req, const char *cp);
enum kcgi_err
khtml_write(const char *cp, size_t sz, void *arg);

DESCRIPTION
The kcgihtml functions support output of HTML5 nodes in a kcgi(3) req allocated with khttp_parse(3). Onl khtml_open() and khtml_close() 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_open()
    Initialise an HTML output context. This accepts the underlying request as well as a bit-mask of options opts. This can be set to KHTML_PRETTY, in which case the output is lightly “pretty-printed” with newlines and indentation spaces. By default, output is all on one line.

khtml_puts()
    Invokes khtml_putc() for each character of the NUL-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
All functions return an enum kcgi_err indicating the error state: KCGI_OK for no error, KCGI_ENOMEM for an internal memory allocation failure, or KCGI_SYSTEM for an internal system error writing to the output stream. The kkhtml_closeto() function returns KCGI_FORM if the requested number of scopes exceeds available scopes. The return of any error code except KCGI_OK may leave the output state inconsistent, and should result in program termination.

STANDARDS
HTML5 compatible with the draft standard of February 2014.

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