DragonFly On-Line Manual Pages

KCGIHTML(3)           DragonFly 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
     compile 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
     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.  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
             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>.

DragonFly 6.5-DEVELOPMENT        July 16, 2015       DragonFly 6.5-DEVELOPMENT