Jansson C Library Documentation

Upgrading from Jansson 1.x to 2.x involves both ABI and API incompatibilities.

• ABI Incompatibility: All programs dynamically linking to the Jansson library must be recompiled.
• API Incompatibility: Source code modifications are required to accommodate new function signatures and type changes.

Note: All 2.x releases (e.g., upgrading from 2.x to 2.y) are guaranteed to be backwards compatible for both ABI and API, requiring no recompilation or source changes.

You can generate local HTML documentation from the source using Sphinx (version 1.0 or newer required). The generated files will be located in doc/_build/html/index.html.

$ make html

Jansson supports CMake for out-of-tree builds. Create a build directory, enter it, and run cmake ...

Common CMake Options:

• -DJANSSON_BUILD_DOCS=OFF: Disable documentation building (required if Sphinx is not installed).
• -DJANSSON_BUILD_SHARED_LIBS=1: Build shared libraries instead of the default static libraries.
• -DCMAKE_INSTALL_PREFIX:PATH=/path: Set the installation destination (equivalent to --prefix in Autotools).

# Unix/macOS example
mkdir build && cd build
cmake .. -DJANSSON_BUILD_DOCS=OFF
make
make check
make install

# Windows (Visual Studio) example
md build
cd build
cmake -G "Visual Studio 15 2017" ..

# Windows (MinGW) example
md build
cd build
cmake -G "MinGW Makefiles" ..
mingw32-make

Jansson uses reference counting to manage memory.

• New References: Functions that create new values set the reference count to 1. You are responsible for calling json_decref() when the value is no longer needed.
• Borrowed References: Functions that return existing values do not increase the reference count. If you need to keep a borrowed reference, you must call json_incref().
• Stealing References: Functions suffixed with _new (e.g., json_array_append_new) 'steal' the reference of their arguments. You do not need to call json_decref() on the argument after calling a stealing function.

Core functions:

• json_t *json_incref(json_t *json): Increments the reference count.
• void json_decref(json_t *json): Decrements the reference count and destroys the value if it reaches zero.

Jansson uses a randomized seed for its hash function to prevent hash collision attacks. While the seed is automatically generated on the first call to json_object(), it is recommended to explicitly autoseed the hashtable before spawning any threads to ensure thread-safe initialization, especially on platforms where you are unsure of the implementation.

To autoseed, call json_object_seed(0) during program startup before creating threads.

Jansson is thread-safe and maintains no mutable global state, with a few exceptions.

• Read-only access: Sharing JSON values for read-only access across multiple threads is safe.
• Mutating values: Mutating a JSON value shared by multiple threads is not safe. You must implement your own locking mechanisms if multiple threads need to mutate shared JSON values.
• Reference counting: Functions json_incref() and json_decref() are typically thread-safe using atomic operations. You can verify if thread-safe reference counting is enabled by checking the JANSSON_THREAD_SAFE_REFCOUNT preprocessor constant. If this constant is not defined, reference counting may not be thread-safe, which can lead to issues when containers (objects/arrays) manage the reference counts of their contained values concurrently.

To compile a C program that uses Jansson for JSON parsing and libcurl for web communication on Unix-like systems with gcc, use the following command:

gcc -o github_commits github_commits.c -ljansson -lcurl

To use Jansson, include the jansson.h header in your source files. All library identifiers are prefixed with json_, constants with JSON_ (except version constants which use JANSSON_), and type names are suffixed with _t.

#include <jansson.h>