KCGIXML(3) Library Functions Manual KCGIXML(3)

NAME

kcgixml, kxml_close, kxml_open, kxml_push, kxml_pushattrs, kxml_pushnull, kxml_pushnullattrs, kxml_pop, kxml_popall, kxml_prologue, kxml_putc, kxml_puts, kxml_writeXML output for kcgi

LIBRARY

library “libkcgixml”

SYNOPSIS

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
#include <kcgixml.h>
enum kcgi_xml
kxml_close(struct kxmlreq *xml);
enum kcgi_xml
kxml_open(struct kxmlreq *xml, struct kreq *req, const char *const *elems, size_t elemsz);
enum kcgi_xml
kxml_push(struct kxmlreq *xml, size_t elem);
enum kcgi_xml
kxml_pushattrs(struct kxmlreq *xml, size_t elem, ...);
enum kcgi_xml
kxml_pushnull(struct kxmlreq *xml, size_t elem);
enum kcgi_xml
kxml_pushnullattrs(struct kxmlreq *xml, size_t elem, ...);
enum kcgi_xml
kxml_pop(struct kxmlreq *xml);
enum kcgi_xml
kxml_popall(struct kxmlreq *xml);
enum kcgi_xml
kxml_prologue(struct kxmlreq *xml);
enum kcgi_xml
kxml_putc(struct kxmlreq *xml, char c);
enum kcgi_xml
kxml_puts(struct kxmlreq *xml, const char *cp);
enum kcgi_xml
kxml_write(const char *cp, size_t sz, void *arg);

DESCRIPTION

The kcgixml functions support output of XML nodes in a kcgi(3) req allocated with khttp_parse(3). Only kxml_open() and kxml_close() may be called before khttp_body(3).
All kcgixml sequences begin with kxml_open(), emit the standard XML prologue with kxml_prologue(), create XML nodes, and end with kxml_close(). An array of possible elements elems is passed to kxml_open(). This is later indexed into with kxml_push(), kxml_pushnull(), kxml_pushattrs(), and kxml_pushnullattrs() to open elements. The kxml_pop() family closes out opened elements.
To use these functions, you must include the <kcgixml.h> header and compile with library “kcgixml”, for example,
% cc -I/usr/local/include -c -o sample.o sample.c 
% cc -L/usr/local/lib -o sample -lkcgixml -lkcgi -lz
 
 
kxml_close()
Closes the context opened by kxml_open(), popping all open tags in doing so. After being called, the struct kcgixml may no longer be used.
 
 
kxml_open()
Open an XML context, binding it to elems, a set of elements (e.g., “DAV:set” or “html”), the number of elements elemsz, the kcgi(3) request object req, and an output object xml. The context is closed by kxml_close().
 
 
kxml_push()
Push the element-open tag indexed by elem() onto the output stream.
 
 
kxml_pushattrs()
Push the element-open tag indexed by elem() onto the output stream, as well as a sequence of NUL-terminated pairs of attributes. The last attribute key must be a NULL to terminate the list.
 
 
kxml_pushnull()
Like kxml_push(), but producing an empty-element tag.
 
 
kxml_pushnullattrs()
Like kxml_pushattrs(), but producing an empty-element tag.
 
 
kxml_pop()
Pop the current open tag as opened by kxml_push() or kxml_pushattrs().
 
 
kxml_popall()
Pop all open tags.
 
 
kxml_putc()
Write a single character within the currently-open tag, escaping it properly as opaque text.
 
 
kxml_prologue()
Emit the XML document prologue. This should only be called once.
 
 
kxml_puts()
Invokes kxml_putc() for all characters in the NUL-terminated string.
 
 
kxml_write()
Invokes kxml_putc() for all elements in the bounded buffer.

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. Some functions return the KCGI_FORM code to indicate that the maximum number of scopes has already been opened.

STANDARDS

The kcgixml functions conform to the XML 1.0 mark-up specification.

AUTHORS

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

CAVEATS

The current hard-coded limit of nested scopes is 128 levels.
January 14, 2018 OpenBSD 6.2