KCGIJSON(3)

NAME
kcgijson, kjson_open, kjson_close, kjson_putbool, kjson_putboolp, kjson_putdouble, kjson_putdoublep, kjson_putint, kjson_putintp, kjson_putintstr, kjson_putintstrp, kjson_putnull, kjson_putnullp, kjson_putstring, kjson_putstringp, kjson_obj_open, kjson_objp_open, kjson_obj_close, kjson_array_open, kjson_arrayp_open, kjson_array_close, kjson_string_open, kjson_stringp_open, kjson_string_close, kjson_string_putdouble, kjson_string_putint, kjson_string_puts, kjson_string_write - JSON output for kcgi

LIBRARY
libkcgijson

SYNOPSIS
#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
#include <kcgijson.h>
enum kcgi_err
kjson_open(struct kjsonreq *r, struct kreq *req);
enum kcgi_err
kjson_close(struct kjsonreq *r);
enum kcgi_err
kjson_putbool(struct kjsonreq *r, int val);
enum kcgi_err
kjson_putboolp(struct kjsonreq *r, const char *key, int val);
enum kcgi_err
kjson_putdouble(struct kjsonreq *r, double val);
enum kcgi_err
kjson_putdoublep(struct kjsonreq *r, const char *key, double val);
enum kcgi_err
kjson_putint(struct kjsonreq *r, int64_t val);
enum kcgi_err
kjson_putintp(struct kjsonreq *r, const char *key, int64_t val);
enum kcgi_err
kjson_putintstr(struct kjsonreq *r, int64_t val);
enum kcgi_err
kjson_putintstrp(struct kjsonreq *r, const char *key, int64_t val);
enum kcgi_err
kjson_putnull(struct kjsonreq *r);
enum kcgi_err
kjson_putnullp(struct kjsonreq *r, const char *key);
enum kcgi_err
kjson_putstring(struct kjsonreq *r, const char *val);
enum kcgi_err
kjson_putstringp(struct kjsonreq *r, const char *key, const char *val);
enum kcgi_err
kjson_obj_open(struct kjsonreq *r);
enum kcgi_err
kjson_objp_open(struct kjsonreq *r, const char *key);
enum kcgi_err
kjson_obj_close(struct kjsonreq *r);
enum kcgi_err
kjson_array_open(struct kjsonreq *r);
enum kcgi_err
kjson_arrayp_open(struct kjsonreq *r, const char *key);
enum kcgi_err
kjson_array_close(struct kjsonreq *r);
enum kcgi_err
kjson_string_open(struct kjsonreq *r);
enum kcgi_err
kjson_stringp_open(struct kjsonreq *r, const char *key);
enum kcgi_err
kjson_string_close(struct kjsonreq *r);
enum kcgi_err
kjson_string_putdouble(struct kjsonreq *r, double val);
enum kcgi_err
kjson_string_putint(struct kjsonreq *r, int64_t val);
enum kcgi_err
kjson_string_puts(struct kjsonreq *r, const char *cp);
enum kcgi_err
kjson_string_write(const char *cp, size_t sz, void *arg);

DESCRIPTION
The kcgijson functions support output of JSON objects and arrays in a kcgi(3) context req allocated with khttp_parse(3). Only kjson_open() and kjson_close() may be called before khttp_body(3).

All kcgijson sequences begin with kjson_open(), create the root document context as either an array or object with kjson_array_open() or kjson_obj_open(), and end with kjson_close().

In general, kcgijson functions follow the convention of writing either pair-type (ending in "p") or standalone-type data. Standalone values are used in arrays; key-value pairs are used in objects. Passing a NULL value as the key for any key-value pair function is the same as calling the standalone version.

To use these functions, include the <kcgijson.h> header and compile with kcgijson, for example,

    % cc -I/usr/local/include -c -o sample.o sample.c
    % cc -L/usr/local/lib -o sample -lkcgijson -lkcgi -lz

On some systems (e.g., Linux), you may also need -lm as a linker flag.

kjson_open()
    Initialise the JSON context r.

kjson_close()
    Close the context opened by kjson_open(), closing out any open arrays, strings, and objects. After this, r may no longer be used.

kjson_arrayp_open(,) kjson_array_open()
    Start an array context with or without a name.

kjson_array_close()
    Close an array context with or without a name.

kjson_string_open(,) kjson_stringp_open()
    Start a string context with or without a name. This is usually used for complex values, or those created dynamically with khttp_template(3). The kjson_string_putdouble(), kjson_string_putint(), kjson_string_putintstr(), kjson_string_puts(), and kjson_string_write() functions may be used for serialising value data. See the documentation for kjson_putdoublep() for caveats on floating-point classes and kjson_putstringp() for character encoding.

kjson_string_close()
    Close a string context with or without a name.

kjson_obj_open(,) kjson_objp_open()
    Start an object context with or without a name.

kjson_obj_close()
    Close an object context with or without a name.

kjson_putstringp(,) kjson_putstring()
    Emit a string value with or without a name. Note that it is not checked for character encoding (assumed to be ASCII or UTF-8), but control characters, the solidus and reverse solidus, and quotes are escaped.

kjson_putboolp(,) kjson_putbool()
    Emit a Boolean value with or without a name. In the usual way, 0 evalutes to FALSE, non-zero to TRUE.

kjson_putnullp(,) kjson_putnull()
    Emit a null value with or without a name.

kjson_putintp(,) kjson_putint()
    Emit a 64-bit signed integer value with or without a name. Important note: while JSON supports arbitrary number lengths, JavaScript is limited to 53 bits of integer precision. Thus, use of this function should be avoided for JavaScript applications. Use kjson_putintstr() or kjson_putintstrp() instead, which emit a 64-bit signed integer value in a string context, with or without a name. This function is generally used for passing integers to JavaScript applications, which are limited in integer precision.

kjson_putdoublep(,) kjson_putdouble()
    Emit a double-precision floating point value with or without a name. This is formatted as with the %g argument to printf(3). Only normal, subnormal, or zero-classified numbers are allowed (see fpclassify(3)); otherwise this returns KCGI_FORM.

RETURN VALUES
All functions inherit return values from khttp_write(3). Some functions additionally return the KCGI_FORM code to indicate that the given operation is not allowed in the current context, such as invoking kjson_obj_close() without a previous invocation of kjson_array_open().

EXAMPLES
Let struct kreq *r already be initialised, and the request be for KMIME_APP_JSON. The following fragment prints out a simple JSON object. Error checking is omitted for brevity.

    kjson_open(&req, r);
    kcgi_writer_disable(r);
    khttp_head(r, kresps[KRESP_STATUS],
      "%s", khttps[KHTTP_200]);
    khttp_head(r, kresps[KRESP_CONTENT_TYPE],
      "%s", kmimetypes[r->mime]);
    khttp_body(r);
    kjson_objp_open(&req, "foo");
    kjson_putstringp(&req, "bar", "baz");
    kjson_obj_close(&req);
    kjson_close(&req);

Following the kcgi_writer_disable(3) call, no further writers may be allocated.

SEE ALSO
kcgi_writer_disable(3), khttp_body(3), khttp_head(3)

STANDARDS
The kcgijson functions conform to the ECMA-404 JSON Data Interchange Standard, also documented as RFC 7159. Parts of this document reference ECMAScript 5, commonly known as JavaScript.

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

CAVEATS
The current hard-coded limit of nested objects is 128 levels. When this is reached, the system will abort(3).