.\" Man page generated from reStructuredText.

.

.TH "LIBJANSSON" "3LIB" "October 28, 2014" "2.7" "Jansson"

.SH NAME

jansson \- Jansson Documentation

.sp

This is the documentation for \fI\%Jansson\fP 2.7, last updated October 28, 2014\&.

.SH INTRODUCTION

.sp

\fI\%Jansson\fP is a C library for encoding, decoding and manipulating JSON

data. Its main features and design principles are:

.INDENT 0.0

.IP \(bu 2

Simple and intuitive API and data model

.IP \(bu 2

Comprehensive documentation

.IP \(bu 2

No dependencies on other libraries

.IP \(bu 2

Full Unicode support (UTF\-8)

.IP \(bu 2

Extensive test suite

.UNINDENT

.sp

Jansson is licensed under the \fI\%MIT license\fP; see LICENSE in the

source distribution for details.

.sp

Jansson is used in production and its API is stable. It works on

numerous platforms, including numerous Unix like systems and Windows.

It\(aqs suitable for use on any system, including desktop, server, and

small embedded systems.

.SH CONTENTS

.SS Getting Started

.SS Compiling and Installing Jansson

.sp

The Jansson source is available at

\fI\%http://www.digip.org/jansson/releases/\fP\&.

.SS Unix\-like systems (including MinGW)

.sp

Unpack the source tarball and change to the source directory:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

bunzip2 \-c jansson\-2.7\&.tar.bz2 | tar xf \-

cd jansson\-2.7

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

The source uses GNU Autotools (\fI\%autoconf\fP, \fI\%automake\fP, \fI\%libtool\fP), so

compiling and installing is extremely simple:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

\&./configure

make

make check

make install

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

To change the destination directory (\fB/usr/local\fP by default), use

the \fB\-\-prefix=DIR\fP argument to \fB\&./configure\fP\&. See \fB\&./configure

\-\-help\fP for the list of all possible installation options. (There are

no options to customize the resulting Jansson binary.)

.sp

The command \fBmake check\fP runs the test suite distributed with

Jansson. This step is not strictly necessary, but it may find possible

problems that Jansson has on your platform. If any problems are found,

please report them.

.sp

If you obtained the source from a Git repository (or any other source

control system), there\(aqs no \fB\&./configure\fP script as it\(aqs not kept in

version control. To create the script, the build system needs to be

bootstrapped. There are many ways to do this, but the easiest one is

to use \fBautoreconf\fP:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

autoreconf \-vi

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

This command creates the \fB\&./configure\fP script, which can then be

used as described above.

.SS CMake (various platforms, including Windows)

.sp

Jansson can be built using \fI\%CMake\fP\&. Create a build directory for an

out\-of\-tree build, change to that directory, and run \fBcmake\fP (or \fBccmake\fP,

\fBcmake\-gui\fP, or similar) to configure the project.

.sp

See the examples below for more detailed information.

.sp

\fBNOTE:\fP

.INDENT 0.0

.INDENT 3.5

In the below examples \fB\&..\fP is used as an argument for \fBcmake\fP\&.

This is simply the path to the jansson project root directory.

In the example it is assumed you\(aqve created a sub\-directory \fBbuild\fP

and are using that. You could use any path you want.

.UNINDENT

.UNINDENT

.SS Unix (Make files)

.sp

Generating make files on unix:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

bunzip2 \-c jansson\-2.7\&.tar.bz2 | tar xf \-

cd jansson\-2.7

mkdir build

cd build

cmake .. # or \fBccmake ..()\fP for a GUI.

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

Then to build:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

make

make check

make install

.ft R

.fi

.UNINDENT

.UNINDENT

.SS Windows (Visual Studio)

.sp

Creating Visual Studio project files from the command line:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

<unpack>

cd jansson\-2.7

md build

cd build

cmake \-G "Visual Studio 10" ..

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

You will now have a \fIVisual Studio Solution\fP in your build directory.

To run the unit tests build the \fBRUN_TESTS\fP project.

.sp

If you prefer a GUI the \fBcmake\fP line in the above example can

be replaced with:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

cmake\-gui ..

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

For command line help (including a list of available generators)

for \fI\%CMake\fP simply run:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

cmake

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

To list available \fI\%CMake\fP settings (and what they are currently set to)

for the project, run:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

cmake \-LH ..

.ft R

.fi

.UNINDENT

.UNINDENT

.SS Mac OSX (Xcode)

.sp

If you prefer using Xcode instead of make files on OSX,

do the following. (Use the same steps as

for \fIUnix\fP):

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

\&...

cmake \-G "Xcode" ..

.ft R

.fi

.UNINDENT

.UNINDENT

.SS Additional CMake settings

.SS Shared library

.sp

By default the \fI\%CMake\fP project will generate build files for building the

static library. To build the shared version use:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

\&...

cmake \-DJANSSON_BUILD_SHARED_LIBS=1 ..

.ft R

.fi

.UNINDENT

.UNINDENT

.SS Changing install directory (same as autoconf \-\-prefix)

.sp

Just as with the \fI\%autoconf\fP project you can change the destination directory

for \fBmake install\fP\&. The equivalent for autoconfs \fB\&./configure \-\-prefix\fP

in \fI\%CMake\fP is:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

\&...

cmake \-DCMAKE_INSTALL_PREFIX:PATH=/some/other/path ..

make install

.ft R

.fi

.UNINDENT

.UNINDENT

.SS Android

.sp

Jansson can be built for Android platforms. Android.mk is in the

source root directory. The configuration header file is located in the

\fBandroid\fP directory in the source distribution.

.SS Other Systems

.sp

On non Unix\-like systems, you may be unable to run the \fB\&./configure\fP

script. In this case, follow these steps. All the files mentioned can

be found in the \fBsrc/\fP directory.

.INDENT 0.0

.IP 1. 3

Create \fBjansson_config.h\fP (which has some platform\-specific

parameters that are normally filled in by the \fB\&./configure\fP

script). Edit \fBjansson_config.h.in\fP, replacing all \fB@variable@\fP

placeholders, and rename the file to \fBjansson_config.h\fP\&.

.IP 2. 3

Make \fBjansson.h\fP and \fBjansson_config.h\fP available to the

compiler, so that they can be found when compiling programs that

use Jansson.

.IP 3. 3

Compile all the \fB\&.c\fP files (in the \fBsrc/\fP directory) into a

library file. Make the library available to the compiler, as in

step 2.

.UNINDENT

.SS Building the Documentation

.sp

(This subsection describes how to build the HTML documentation you are

currently reading, so it can be safely skipped.)

.sp

Documentation is in the \fBdoc/\fP subdirectory. It\(aqs written in

\fI\%reStructuredText\fP with \fI\%Sphinx\fP annotations. To generate the HTML

documentation, invoke:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

make html

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

and point your browser to \fBdoc/_build/html/index.html\fP\&. \fI\%Sphinx\fP 1.0

or newer is required to generate the documentation.

.SS Compiling Programs that Use Jansson

.sp

Jansson involves one C header file, \fBjansson.h\fP, so it\(aqs enough

to put the line

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

#include <jansson.h>

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

in the beginning of every source file that uses Jansson.

.sp

There\(aqs also just one library to link with, \fBlibjansson\fP\&. Compile and

link the program as follows:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

cc \-I/usr/include/jansson \-o prog prog.c \-ljansson

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

Starting from version 1.2, there\(aqs also support for \fI\%pkg\-config\fP:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

cc \-o prog prog.c \(gapkg\-config \-\-cflags \-\-libs jansson\(ga

.ft R

.fi

.UNINDENT

.UNINDENT

.SS Upgrading from 1.x

.sp

This chapter lists the backwards incompatible changes introduced in

Jansson 2.0, and the steps that are needed for upgrading your code.

.sp

\fBThe incompatibilities are not dramatic.\fP The biggest change is that

all decoding functions now require and extra parameter. Most programs

can be modified to work with 2.0 by adding a \fB0\fP as the second

parameter to all calls of \fBjson_loads()\fP, \fBjson_loadf()\fP

and \fBjson_load_file()\fP\&.

.SS Compatibility

.sp

Jansson 2.0 is backwards incompatible with the Jansson 1.x releases.

It is ABI incompatible, i.e. all programs dynamically linking to the

Jansson library need to be recompiled. It\(aqs also API incompatible,

i.e. the source code of programs using Jansson 1.x may need

modifications to make them compile against Jansson 2.0.

.sp

All the 2.x releases are guaranteed to be backwards compatible for

both ABI and API, so no recompilation or source changes are needed

when upgrading from 2.x to 2.y.

.SS List of Incompatible Changes

.INDENT 0.0

.TP

.B \fBDecoding flags\fP

For future needs, a \fBflags\fP parameter was added as the second

parameter to all decoding functions, i.e. \fBjson_loads()\fP,

\fBjson_loadf()\fP and \fBjson_load_file()\fP\&. All calls to

these functions need to be changed by adding a \fB0\fP as the second

argument. For example:

.INDENT 7.0

.INDENT 3.5

.sp

.nf

.ft CW

/* old code */

json_loads(input, &error);

/* new code */

json_loads(input, 0, &error);

.ft R

.fi

.UNINDENT

.UNINDENT

.TP

.B \fBUnderlying type of JSON integers\fP

The underlying C type of JSON integers has been changed from

\fBint\fP to the widest available signed integer type, i.e.

\fBlong long\fP or \fBlong\fP, depending on whether

\fBlong long\fP is supported on your system or not. This makes

the whole 64\-bit integer range available on most modern systems.

.sp

\fBjansson.h\fP has a typedef \fBjson_int_t\fP to the underlying

integer type. \fBint\fP should still be used in most cases when

dealing with smallish JSON integers, as the compiler handles

implicit type coercion. Only when the full 64\-bit range is needed,

\fBjson_int_t\fP should be explicitly used.

.TP

.B \fBMaximum encoder indentation depth\fP

The maximum argument of the \fBJSON_INDENT()\fP macro has been

changed from 255 to 31, to free up bits from the \fBflags\fP

parameter of \fBjson_dumps()\fP, \fBjson_dumpf()\fP and

\fBjson_dump_file()\fP\&. If your code uses a bigger indentation

than 31, it needs to be changed.

.TP

.B \fBUnsigned integers in API functions\fP

Version 2.0 unifies unsigned integer usage in the API. All uses of

\fBunsigned int\fP and \fBunsigned long\fP have been replaced

with \fBsize_t\fP\&. This includes flags, container sizes, etc.

This should not require source code changes, as both

\fBunsigned int\fP and \fBunsigned long\fP are usually

compatible with \fBsize_t\fP\&.

.UNINDENT

.SS Tutorial

.sp

In this tutorial, we create a program that fetches the latest commits

of a repository in \fI\%GitHub\fP over the web. \fI\%GitHub API\fP uses JSON, so

the result can be parsed using Jansson.

.sp

To stick to the the scope of this tutorial, we will only cover the the

parts of the program related to handling JSON data. For the best user

experience, the full source code is available:

\fBgithub_commits.c\fP\&. To compile it (on Unix\-like systems with

gcc), use the following command:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

gcc \-o github_commits github_commits.c \-ljansson \-lcurl

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

\fI\%libcurl\fP is used to communicate over the web, so it is required to

compile the program.

.sp

The command line syntax is:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

github_commits USER REPOSITORY

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

\fBUSER\fP is a GitHub user ID and \fBREPOSITORY\fP is the repository

name. Please note that the GitHub API is rate limited, so if you run

the program too many times within a short period of time, the sever

starts to respond with an error.

.SS The GitHub Repo Commits API

.sp

The \fI\%GitHub Repo Commits API\fP is used by sending HTTP requests to

URLs like \fBhttps://api.github.com/repos/USER/REPOSITORY/commits\fP,

where \fBUSER\fP and \fBREPOSITORY\fP are the GitHub user ID and the name

of the repository whose commits are to be listed, respectively.

.sp

GitHub responds with a JSON array of the following form:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

[

    {

        "sha": "<the commit ID>",

        "commit": {

            "message": "<the commit message>",

            <more fields, not important to this tutorial...>

        },

        <more fields...>

    },

    {

        "sha": "<the commit ID>",

        "commit": {

            "message": "<the commit message>",

            <more fields...>

        },

        <more fields...>

    },

    <more commits...>

]

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

In our program, the HTTP request is sent using the following

function:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

static char *request(const char *url);

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

It takes the URL as a parameter, preforms a HTTP GET request, and

returns a newly allocated string that contains the response body. If

the request fails, an error message is printed to stderr and the

return value is \fINULL\fP\&. For full details, refer to \fBthe code\fP, as the actual implementation is not important

here.

.SS The Program

.sp

First the includes:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft CW

#include <string.h>

#include <jansson.h>

.ft R

.fi

.UNINDENT

.UNINDENT

.sp

Like all the programs using Jansson, we need to include

\fBjansson.h\fP\&.

.sp

The following definitions are used to build the GitHub API request