KCGIJSON(3) Library Functions Manual KCGIJSON(3)


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


library “libkcgijson”


#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);


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 library “kcgijson”, for example,
% cc -I/usr/local/include -c -o sample.o sample.c 
% cc -L/usr/local/lib -o sample -lkcgijson -lkcgi -lz
Initialise the JSON context r.
Close the context opened by kxml_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.
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.
Close a string context with or without a name.
kjson_obj_open(), kjson_objp_open()
Start an object context with or without a name.
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.


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 given operation is not allowed in the current context, such as invoking kjson_obj_close() with a previous invocation of kjson_array_open(). The return of any error code except KCGI_OK may leave the output state inconsistent, and should result in program termination.


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); 
khttp_head(r, kresps[KRESP_STATUS], 
  "%s", khttps[KHTTP_200]); 
khttp_head(r, kresps[KRESP_CONTENT_TYPE], 
  "%s", kmimetypes[r->mime]); 
kjson_objp_open(&req, "foo"); 
kjson_putstringp(&req, "bar", "baz"); 
Following the kcgi_writer_disable(3) call, no further writers may be allocated.


kcgi_writer_disable(3), khttp_body(3), khttp_head(3)


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.


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


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