1 .\" Man page generated from reStructuredText.

     2 .

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

     4 .SH NAME

     5 jansson \- Jansson Documentation

     6 .sp

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

     8 .SH INTRODUCTION

     9 .sp

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

    11 data. Its main features and design principles are:

    12 .INDENT 0.0

    13 .IP \(bu 2

    14 Simple and intuitive API and data model

    15 .IP \(bu 2

    16 Comprehensive documentation

    17 .IP \(bu 2

    18 No dependencies on other libraries

    19 .IP \(bu 2

    20 Full Unicode support (UTF\-8)

    21 .IP \(bu 2

    22 Extensive test suite

    23 .UNINDENT

    24 .sp

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

    26 source distribution for details.

    27 .sp

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

    29 numerous platforms, including numerous Unix like systems and Windows.

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

    31 small embedded systems.

    32 .SH CONTENTS

    33 .SS Getting Started

    34 .SS Compiling and Installing Jansson

    35 .sp

    36 The Jansson source is available at

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

    38 .SS Unix\-like systems (including MinGW)

    39 .sp

    40 Unpack the source tarball and change to the source directory:

    41 .INDENT 0.0

    42 .INDENT 3.5

    43 .sp

    44 .nf

    45 .ft CW

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

    47 cd jansson\-2.7

    48 .ft R

    49 .fi

    50 .UNINDENT

    51 .UNINDENT

    52 .sp

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

    54 compiling and installing is extremely simple:

    55 .INDENT 0.0

    56 .INDENT 3.5

    57 .sp

    58 .nf

    59 .ft CW

    60 \&./configure

    61 make

    62 make check

    63 make install

    64 .ft R

    65 .fi

    66 .UNINDENT

    67 .UNINDENT

    68 .sp

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

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

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

    72 no options to customize the resulting Jansson binary.)

    73 .sp

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

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

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

    77 please report them.

    78 .sp

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

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

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

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

    83 to use \fBautoreconf\fP:

    84 .INDENT 0.0

    85 .INDENT 3.5

    86 .sp

    87 .nf

    88 .ft CW

    89 autoreconf \-vi

    90 .ft R

    91 .fi

    92 .UNINDENT

    93 .UNINDENT

    94 .sp

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

    96 used as described above.

    97 .SS CMake (various platforms, including Windows)

    98 .sp

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

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

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

   102 .sp

   103 See the examples below for more detailed information.

   104 .sp

   105 \fBNOTE:\fP

   106 .INDENT 0.0

   107 .INDENT 3.5

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

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

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

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

   112 .UNINDENT

   113 .UNINDENT

   114 .SS Unix (Make files)

   115 .sp

   116 Generating make files on unix:

   117 .INDENT 0.0

   118 .INDENT 3.5

   119 .sp

   120 .nf

   121 .ft CW

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

   123 cd jansson\-2.7

   124 

   125 mkdir build

   126 cd build

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

   128 .ft R

   129 .fi

   130 .UNINDENT

   131 .UNINDENT

   132 .sp

   133 Then to build:

   134 .INDENT 0.0

   135 .INDENT 3.5

   136 .sp

   137 .nf

   138 .ft CW

   139 make

   140 make check

   141 make install

   142 .ft R

   143 .fi

   144 .UNINDENT

   145 .UNINDENT

   146 .SS Windows (Visual Studio)

   147 .sp

   148 Creating Visual Studio project files from the command line:

   149 .INDENT 0.0

   150 .INDENT 3.5

   151 .sp

   152 .nf

   153 .ft CW

   154 <unpack>

   155 cd jansson\-2.7

   156 

   157 md build

   158 cd build

   159 cmake \-G "Visual Studio 10" ..

   160 .ft R

   161 .fi

   162 .UNINDENT

   163 .UNINDENT

   164 .sp

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

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

   167 .sp

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

   169 be replaced with:

   170 .INDENT 0.0

   171 .INDENT 3.5

   172 .sp

   173 .nf

   174 .ft CW

   175 cmake\-gui ..

   176 .ft R

   177 .fi

   178 .UNINDENT

   179 .UNINDENT

   180 .sp

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

   182 for \fI\%CMake\fP simply run:

   183 .INDENT 0.0

   184 .INDENT 3.5

   185 .sp

   186 .nf

   187 .ft CW

   188 cmake

   189 .ft R

   190 .fi

   191 .UNINDENT

   192 .UNINDENT

   193 .sp

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

   195 for the project, run:

   196 .INDENT 0.0

   197 .INDENT 3.5

   198 .sp

   199 .nf

   200 .ft CW

   201 cmake \-LH ..

   202 .ft R

   203 .fi

   204 .UNINDENT

   205 .UNINDENT

   206 .SS Mac OSX (Xcode)

   207 .sp

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

   209 do the following. (Use the same steps as

   210 for \fIUnix\fP):

   211 .INDENT 0.0

   212 .INDENT 3.5

   213 .sp

   214 .nf

   215 .ft CW

   216 \&...

   217 cmake \-G "Xcode" ..

   218 .ft R

   219 .fi

   220 .UNINDENT

   221 .UNINDENT

   222 .SS Additional CMake settings

   223 .SS Shared library

   224 .sp

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

   226 static library. To build the shared version use:

   227 .INDENT 0.0

   228 .INDENT 3.5

   229 .sp

   230 .nf

   231 .ft CW

   232 \&...

   233 cmake \-DJANSSON_BUILD_SHARED_LIBS=1 ..

   234 .ft R

   235 .fi

   236 .UNINDENT

   237 .UNINDENT

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

   239 .sp

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

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

   242 in \fI\%CMake\fP is:

   243 .INDENT 0.0

   244 .INDENT 3.5

   245 .sp

   246 .nf

   247 .ft CW

   248 \&...

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

   250 make install

   251 .ft R

   252 .fi

   253 .UNINDENT

   254 .UNINDENT

   255 .SS Android

   256 .sp

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

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

   259 \fBandroid\fP directory in the source distribution.

   260 .SS Other Systems

   261 .sp

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

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

   264 be found in the \fBsrc/\fP directory.

   265 .INDENT 0.0

   266 .IP 1. 3

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

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

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

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

   271 .IP 2. 3

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

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

   274 use Jansson.

   275 .IP 3. 3

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

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

   278 step 2.

   279 .UNINDENT

   280 .SS Building the Documentation

   281 .sp

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

   283 currently reading, so it can be safely skipped.)

   284 .sp

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

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

   287 documentation, invoke:

   288 .INDENT 0.0

   289 .INDENT 3.5

   290 .sp

   291 .nf

   292 .ft CW

   293 make html

   294 .ft R

   295 .fi

   296 .UNINDENT

   297 .UNINDENT

   298 .sp

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

   300 or newer is required to generate the documentation.

   301 .SS Compiling Programs that Use Jansson

   302 .sp

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

   304 to put the line

   305 .INDENT 0.0

   306 .INDENT 3.5

   307 .sp

   308 .nf

   309 .ft CW

   310 #include <jansson.h>

   311 .ft R

   312 .fi

   313 .UNINDENT

   314 .UNINDENT

   315 .sp

   316 in the beginning of every source file that uses Jansson.

   317 .sp

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

   319 link the program as follows:

   320 .INDENT 0.0

   321 .INDENT 3.5

   322 .sp

   323 .nf

   324 .ft CW

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

   326 .ft R

   327 .fi

   328 .UNINDENT

   329 .UNINDENT

   330 .sp

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

   332 .INDENT 0.0

   333 .INDENT 3.5

   334 .sp

   335 .nf

   336 .ft CW

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

   338 .ft R

   339 .fi

   340 .UNINDENT

   341 .UNINDENT

   342 .SS Upgrading from 1.x

   343 .sp

   344 This chapter lists the backwards incompatible changes introduced in

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

   346 .sp

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

   348 all decoding functions now require and extra parameter. Most programs

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

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

   351 and \fBjson_load_file()\fP\&.

   352 .SS Compatibility

   353 .sp

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

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

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

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

   358 modifications to make them compile against Jansson 2.0.

   359 .sp

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

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

   362 when upgrading from 2.x to 2.y.

   363 .SS List of Incompatible Changes

   364 .INDENT 0.0

   365 .TP

   366 .B \fBDecoding flags\fP

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

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

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

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

   371 argument. For example:

   372 .INDENT 7.0

   373 .INDENT 3.5

   374 .sp

   375 .nf

   376 .ft CW

   377 /* old code */

   378 json_loads(input, &error);

   379 

   380 /* new code */

   381 json_loads(input, 0, &error);

   382 .ft R

   383 .fi

   384 .UNINDENT

   385 .UNINDENT

   386 .TP

   387 .B \fBUnderlying type of JSON integers\fP

   388 The underlying C type of JSON integers has been changed from

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

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

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

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

   393 .sp

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

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

   396 dealing with smallish JSON integers, as the compiler handles

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

   398 \fBjson_int_t\fP should be explicitly used.

   399 .TP

   400 .B \fBMaximum encoder indentation depth\fP

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

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

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

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

   405 than 31, it needs to be changed.

   406 .TP

   407 .B \fBUnsigned integers in API functions\fP

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

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

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

   411 This should not require source code changes, as both

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

   413 compatible with \fBsize_t\fP\&.

   414 .UNINDENT

   415 .SS Tutorial

   416 .sp

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

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

   419 the result can be parsed using Jansson.

   420 .sp

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

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

   423 experience, the full source code is available:

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

   425 gcc), use the following command:

   426 .INDENT 0.0

   427 .INDENT 3.5

   428 .sp

   429 .nf

   430 .ft CW

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

   432 .ft R

   433 .fi

   434 .UNINDENT

   435 .UNINDENT

   436 .sp

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

   438 compile the program.

   439 .sp

   440 The command line syntax is:

   441 .INDENT 0.0

   442 .INDENT 3.5

   443 .sp

   444 .nf

   445 .ft CW

   446 github_commits USER REPOSITORY

   447 .ft R

   448 .fi

   449 .UNINDENT

   450 .UNINDENT

   451 .sp

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

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

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

   455 starts to respond with an error.

   456 .SS The GitHub Repo Commits API

   457 .sp

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

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

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

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

   462 .sp

   463 GitHub responds with a JSON array of the following form:

   464 .INDENT 0.0

   465 .INDENT 3.5

   466 .sp

   467 .nf

   468 .ft CW

   469 [

   470     {

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

   472         "commit": {

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

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

   475         },

   476         <more fields...>

   477     },

   478     {

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

   480         "commit": {

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

   482             <more fields...>

   483         },

   484         <more fields...>

   485     },

   486     <more commits...>

   487 ]

   488 .ft R

   489 .fi

   490 .UNINDENT

   491 .UNINDENT

   492 .sp

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

   494 function:

   495 .INDENT 0.0

   496 .INDENT 3.5

   497 .sp

   498 .nf

   499 .ft CW

   500 static char *request(const char *url);

   501 .ft R

   502 .fi

   503 .UNINDENT

   504 .UNINDENT

   505 .sp

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

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

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

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

   510 here.

   511 .SS The Program

   512 .sp

   513 First the includes:

   514 .INDENT 0.0

   515 .INDENT 3.5

   516 .sp

   517 .nf

   518 .ft CW

   519 #include <string.h>

   520 #include <jansson.h>

   521 .ft R

   522 .fi

   523 .UNINDENT

   524 .UNINDENT

   525 .sp

   526 Like all the programs using Jansson, we need to include

   527 \fBjansson.h\fP\&.

   528 .sp

   529 The following definitions are used to build the GitHub API request

   530 URL:

   531 .INDENT 0.0

   532 .INDENT 3.5

   533 .sp

   534 .nf

   535 .ft CW

   536 #define URL_FORMAT   "https://api.github.com/repos/%s/%s/commits"

   537 #define URL_SIZE     256

   538 .ft R

   539 .fi

   540 .UNINDENT

   541 .UNINDENT

   542 .sp

   543 The following function is used when formatting the result to find the

   544 first newline in the commit message:

   545 .INDENT 0.0

   546 .INDENT 3.5

   547 .sp

   548 .nf

   549 .ft CW

   550 /* Return the offset of the first newline in text or the length of

   551    text if there\(aqs no newline */

   552 static int newline_offset(const char *text)

   553 {

   554     const char *newline = strchr(text, \(aq\en\(aq);

   555     if(!newline)

   556         return strlen(text);

   557     else

   558         return (int)(newline \- text);

   559 }

   560 .ft R

   561 .fi

   562 .UNINDENT

   563 .UNINDENT

   564 .sp

   565 The main function follows. In the beginning, we first declare a bunch

   566 of variables and check the command line parameters:

   567 .INDENT 0.0

   568 .INDENT 3.5

   569 .sp

   570 .nf

   571 .ft CW

   572 int main(int argc, char *argv[])

   573 {

   574     size_t i;

   575     char *text;

   576     char url[URL_SIZE];

   577 

   578     json_t *root;

   579     json_error_t error;

   580 

   581     if(argc != 3)

   582     {

   583         fprintf(stderr, "usage: %s USER REPOSITORY\en\en", argv[0]);

   584         fprintf(stderr, "List commits at USER\(aqs REPOSITORY.\en\en");

   585         return 2;

   586     }

   587 .ft R

   588 .fi

   589 .UNINDENT

   590 .UNINDENT

   591 .sp

   592 Then we build the request URL using the user and repository names

   593 given as command line parameters:

   594 .INDENT 0.0

   595 .INDENT 3.5

   596 .sp

   597 .nf

   598 .ft CW

   599 snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]);

   600 .ft R

   601 .fi

   602 .UNINDENT

   603 .UNINDENT

   604 .sp

   605 This uses the \fBURL_SIZE\fP and \fBURL_FORMAT\fP constants defined above.

   606 Now we\(aqre ready to actually request the JSON data over the web:

   607 .INDENT 0.0

   608 .INDENT 3.5

   609 .sp

   610 .nf

   611 .ft CW

   612 text = request(url);

   613 if(!text)

   614     return 1;

   615 .ft R

   616 .fi

   617 .UNINDENT

   618 .UNINDENT

   619 .sp

   620 If an error occurs, our function \fBrequest\fP prints the error and

   621 returns \fINULL\fP, so it\(aqs enough to just return 1 from the main

   622 function.

   623 .sp

   624 Next we\(aqll call \fBjson_loads()\fP to decode the JSON text we got

   625 as a response:

   626 .INDENT 0.0

   627 .INDENT 3.5

   628 .sp

   629 .nf

   630 .ft CW

   631 root = json_loads(text, 0, &error);

   632 free(text);

   633 

   634 if(!root)

   635 {

   636     fprintf(stderr, "error: on line %d: %s\en", error.line, error.text);

   637     return 1;

   638 }

   639 .ft R

   640 .fi

   641 .UNINDENT

   642 .UNINDENT

   643 .sp

   644 We don\(aqt need the JSON text anymore, so we can free the \fBtext\fP

   645 variable right after decoding it. If \fBjson_loads()\fP fails, it

   646 returns \fINULL\fP and sets error information to the \fBjson_error_t\fP

   647 structure given as the second parameter. In this case, our program

   648 prints the error information out and returns 1 from the main function.

   649 .sp

   650 Now we\(aqre ready to extract the data out of the decoded JSON response.

   651 The structure of the response JSON was explained in section

   652 \fI\%The GitHub Repo Commits API\fP\&.

   653 .sp

   654 We check that the returned value really is an array:

   655 .INDENT 0.0

   656 .INDENT 3.5

   657 .sp

   658 .nf

   659 .ft CW

   660 if(!json_is_array(root))

   661 {

   662     fprintf(stderr, "error: root is not an array\en");

   663     json_decref(root);

   664     return 1;

   665 }

   666 .ft R

   667 .fi

   668 .UNINDENT

   669 .UNINDENT

   670 .sp

   671 Then we proceed to loop over all the commits in the array:

   672 .INDENT 0.0

   673 .INDENT 3.5

   674 .sp

   675 .nf

   676 .ft CW

   677 for(i = 0; i < json_array_size(root); i++)

   678 {

   679     json_t *data, *sha, *commit, *message;

   680     const char *message_text;

   681 

   682     data = json_array_get(root, i);

   683     if(!json_is_object(data))

   684     {

   685         fprintf(stderr, "error: commit data %d is not an object\en", i + 1);

   686         json_decref(root);

   687         return 1;

   688     }

   689 \&...

   690 .ft R

   691 .fi

   692 .UNINDENT

   693 .UNINDENT

   694 .sp

   695 The function \fBjson_array_size()\fP returns the size of a JSON

   696 array. First, we again declare some variables and then extract the

   697 i\(aqth element of the \fBroot\fP array using \fBjson_array_get()\fP\&.

   698 We also check that the resulting value is a JSON object.

   699 .sp

   700 Next we\(aqll extract the commit ID (a hexadecimal SHA\-1 sum),

   701 intermediate commit info object, and the commit message from that

   702 object. We also do proper type checks:

   703 .INDENT 0.0

   704 .INDENT 3.5

   705 .sp

   706 .nf

   707 .ft CW

   708     sha = json_object_get(data, "sha");

   709     if(!json_is_string(sha))

   710     {

   711         fprintf(stderr, "error: commit %d: sha is not a string\en", i + 1);

   712         json_decref(root);

   713         return 1;

   714     }

   715 

   716     commit = json_object_get(data, "commit");

   717     if(!json_is_object(commit))

   718     {

   719         fprintf(stderr, "error: commit %d: commit is not an object\en", i + 1);

   720         json_decref(root);

   721         return 1;

   722     }

   723 

   724     message = json_object_get(commit, "message");

   725     if(!json_is_string(message))

   726     {

   727         fprintf(stderr, "error: commit %d: message is not a string\en", i + 1);

   728         json_decref(root);

   729         return 1;

   730     }

   731 \&...

   732 .ft R

   733 .fi

   734 .UNINDENT

   735 .UNINDENT

   736 .sp

   737 And finally, we\(aqll print the first 8 characters of the commit ID and

   738 the first line of the commit message. A C\-style string is extracted

   739 from a JSON string using \fBjson_string_value()\fP:

   740 .INDENT 0.0

   741 .INDENT 3.5

   742 .sp

   743 .nf

   744 .ft CW

   745     message_text = json_string_value(message);

   746     printf("%.8s %.*s\en",

   747            json_string_value(id),

   748            newline_offset(message_text),

   749            message_text);

   750 }

   751 .ft R

   752 .fi

   753 .UNINDENT

   754 .UNINDENT

   755 .sp

   756 After sending the HTTP request, we decoded the JSON text using

   757 \fBjson_loads()\fP, remember? It returns a \fInew reference\fP to the

   758 JSON value it decodes. When we\(aqre finished with the value, we\(aqll need

   759 to decrease the reference count using \fBjson_decref()\fP\&. This way

   760 Jansson can release the resources:

   761 .INDENT 0.0

   762 .INDENT 3.5

   763 .sp

   764 .nf

   765 .ft CW

   766 json_decref(root);

   767 return 0;

   768 .ft R

   769 .fi

   770 .UNINDENT

   771 .UNINDENT

   772 .sp

   773 For a detailed explanation of reference counting in Jansson, see

   774 \fIapiref\-reference\-count\fP in \fIapiref\fP\&.

   775 .sp

   776 The program\(aqs ready, let\(aqs test it and view the latest commits in

   777 Jansson\(aqs repository:

   778 .INDENT 0.0

   779 .INDENT 3.5

   780 .sp

   781 .nf

   782 .ft CW

   783 $ ./github_commits akheron jansson

   784 1581f26a Merge branch \(aq2.3\(aq

   785 aabfd493 load: Change buffer_pos to be a size_t

   786 bd72efbd load: Avoid unexpected behaviour in macro expansion

   787 e8fd3e30 Document and tweak json_load_callback()

   788 873eddaf Merge pull request #60 from rogerz/contrib

   789 bd2c0c73 Ignore the binary test_load_callback

   790 17a51a4b Merge branch \(aq2.3\(aq

   791 09c39adc Add json_load_callback to the list of exported symbols

   792 cbb80baf Merge pull request #57 from rogerz/contrib

   793 040bd7b0 Add json_load_callback()

   794 2637faa4 Make test stripping locale independent

   795 <...>

   796 .ft R

   797 .fi

   798 .UNINDENT

   799 .UNINDENT

   800 .SS Conclusion

   801 .sp

   802 In this tutorial, we implemented a program that fetches the latest

   803 commits of a GitHub repository using the GitHub Repo Commits API.

   804 Jansson was used to decode the JSON response and to extract the commit

   805 data.

   806 .sp

   807 This tutorial only covered a small part of Jansson. For example, we

   808 did not create or manipulate JSON values at all. Proceed to

   809 \fIapiref\fP to explore all features of Jansson.

   810 .SS RFC Conformance

   811 .sp

   812 JSON is specified in \fI\%RFC 4627\fP, \fI"The application/json Media Type

   813 for JavaScript Object Notation (JSON)"\fP\&.

   814 .SS Character Encoding

   815 .sp

   816 Jansson only supports UTF\-8 encoded JSON texts. It does not support or

   817 auto\-detect any of the other encodings mentioned in the RFC, namely

   818 UTF\-16LE, UTF\-16BE, UTF\-32LE or UTF\-32BE. Pure ASCII is supported, as

   819 it\(aqs a subset of UTF\-8.

   820 .SS Strings

   821 .sp

   822 JSON strings are mapped to C\-style null\-terminated character arrays,

   823 and UTF\-8 encoding is used internally.

   824 .sp

   825 All Unicode codepoints U+0000 through U+10FFFF are allowed in string

   826 values. However, U+0000 is not allowed in object keys because of API

   827 restrictions.

   828 .sp

   829 Unicode normalization or any other transformation is never performed

   830 on any strings (string values or object keys). When checking for

   831 equivalence of strings or object keys, the comparison is performed

   832 byte by byte between the original UTF\-8 representations of the

   833 strings.

   834 .SS Numbers

   835 .SS Real vs. Integer

   836 .sp

   837 JSON makes no distinction between real and integer numbers; Jansson

   838 does. Real numbers are mapped to the \fBdouble\fP type and integers to

   839 the \fBjson_int_t\fP type, which is a typedef of \fBlong long\fP or

   840 \fBlong\fP, depending on whether \fBlong long\fP is supported by your

   841 compiler or not.

   842 .sp

   843 A JSON number is considered to be a real number if its lexical

   844 representation includes one of \fBe\fP, \fBE\fP, or \fB\&.\fP; regardless if

   845 its actual numeric value is a true integer (e.g., all of \fB1E6\fP,

   846 \fB3.0\fP, \fB400E\-2\fP, and \fB3.14E3\fP are mathematical integers, but

   847 will be treated as real values). With the \fBJSON_DECODE_INT_AS_REAL\fP

   848 decoder flag set all numbers are interpreted as real.

   849 .sp

   850 All other JSON numbers are considered integers.

   851 .sp

   852 When encoding to JSON, real values are always represented

   853 with a fractional part; e.g., the \fBdouble\fP value 3.0 will be

   854 represented in JSON as \fB3.0\fP, not \fB3\fP\&.

   855 .SS Overflow, Underflow & Precision

   856 .sp

   857 Real numbers whose absolute values are too small to be represented in

   858 a C \fBdouble\fP will be silently estimated with 0.0. Thus, depending on

   859 platform, JSON numbers very close to zero such as 1E\-999 may result in

   860 0.0.

   861 .sp

   862 Real numbers whose absolute values are too large to be represented in

   863 a C \fBdouble\fP will result in an overflow error (a JSON decoding

   864 error). Thus, depending on platform, JSON numbers like 1E+999 or

   865 \-1E+999 may result in a parsing error.

   866 .sp

   867 Likewise, integer numbers whose absolute values are too large to be

   868 represented in the \fBjson_int_t\fP type (see above) will result in an

   869 overflow error (a JSON decoding error). Thus, depending on platform,

   870 JSON numbers like 1000000000000000 may result in parsing error.

   871 .sp

   872 Parsing JSON real numbers may result in a loss of precision. As long

   873 as overflow does not occur (i.e. a total loss of precision), the

   874 rounded approximate value is silently used. Thus the JSON number

   875 1.000000000000000005 may, depending on platform, result in the

   876 \fBdouble\fP value 1.0.

   877 .SS Signed zeros

   878 .sp

   879 JSON makes no statement about what a number means; however Javascript

   880 (ECMAscript) does state that +0.0 and \-0.0 must be treated as being

   881 distinct values, i.e. \-0.0 ≠ 0.0. Jansson relies on the

   882 underlying floating point library in the C environment in which it is

   883 compiled. Therefore it is platform\-dependent whether 0.0 and \-0.0 will

   884 be distinct values. Most platforms that use the IEEE 754

   885 floating\-point standard will support signed zeros.

   886 .sp

   887 Note that this only applies to floating\-point; neither JSON, C, or

   888 IEEE support the concept of signed integer zeros.

   889 .SS Types

   890 .sp

   891 No support is provided in Jansson for any C numeric types other than

   892 \fBjson_int_t\fP and \fBdouble\fP\&. This excludes things such as unsigned

   893 types, \fBlong double\fP, etc. Obviously, shorter types like \fBshort\fP,

   894 \fBint\fP, \fBlong\fP (if \fBjson_int_t\fP is \fBlong long\fP) and \fBfloat\fP

   895 are implicitly handled via the ordinary C type coercion rules (subject

   896 to overflow semantics). Also, no support or hooks are provided for any

   897 supplemental "bignum" type add\-on packages.

   898 .SS Portability

   899 .SS Thread safety

   900 .sp

   901 Jansson is thread safe and has no mutable global state. The only

   902 exceptions are the hash function seed and memory allocation functions,

   903 see below.

   904 .sp

   905 There\(aqs no locking performed inside Jansson\(aqs code, so a multithreaded

   906 program must perform its own locking if JSON values are shared by

   907 multiple threads. Jansson\(aqs reference counting semantics may make this

   908 a bit harder than it seems, as it\(aqs possible to have a reference to a

   909 value that\(aqs also stored inside a list or object. Modifying the

   910 container (adding or removing values) may trigger concurrent access to

   911 such values, as containers manage the reference count of their

   912 contained values. Bugs involving concurrent incrementing or

   913 decrementing of deference counts may be hard to track.

   914 .sp

   915 The encoding functions (\fBjson_dumps()\fP and friends) track

   916 reference loops by modifying the internal state of objects and arrays.

   917 For this reason, encoding functions must not be run on the same JSON

   918 values in two separate threads at the same time. As already noted

   919 above, be especially careful if two arrays or objects share their

   920 contained values with another array or object.

   921 .sp

   922 If you want to make sure that two JSON value hierarchies do not

   923 contain shared values, use \fBjson_deep_copy()\fP to make copies.

   924 .SS Hash function seed

   925 .sp

   926 To prevent an attacker from intentionally causing large JSON objects

   927 with specially crafted keys to perform very slow, the hash function

   928 used by Jansson is randomized using a seed value. The seed is

   929 automatically generated on the first explicit or implicit call to

   930 \fBjson_object()\fP, if \fBjson_object_seed()\fP has not been

   931 called beforehand.

   932 .sp

   933 The seed is generated by using operating system\(aqs entropy sources if

   934 they are available (\fB/dev/urandom\fP, \fBCryptGenRandom()\fP). The

   935 initialization is done in as thread safe manner as possible, by using

   936 architecture specific lockless operations if provided by the platform

   937 or the compiler.

   938 .sp

   939 If you\(aqre using threads, it\(aqs recommended to autoseed the hashtable

   940 explicitly before spawning any threads by calling

   941 \fBjson_object_seed(0)\fP , especially if you\(aqre unsure whether the

   942 initialization is thread safe on your platform.

   943 .SS Memory allocation functions

   944 .sp

   945 Memory allocation functions should be set at most once, and only on

   946 program startup. See \fIapiref\-custom\-memory\-allocation\fP\&.

   947 .SS Locale

   948 .sp

   949 Jansson works fine under any locale.

   950 .sp

   951 However, if the host program is multithreaded and uses \fBsetlocale()\fP

   952 to switch the locale in one thread while Jansson is currently encoding

   953 or decoding JSON data in another thread, the result may be wrong or

   954 the program may even crash.

   955 .sp

   956 Jansson uses locale specific functions for certain string conversions

   957 in the encoder and decoder, and then converts the locale specific

   958 values to/from the JSON representation. This fails if the locale

   959 changes between the string conversion and the locale\-to\-JSON

   960 conversion. This can only happen in multithreaded programs that use

   961 \fBsetlocale()\fP, because \fBsetlocale()\fP switches the locale for all

   962 running threads, not only the thread that calls \fBsetlocale()\fP\&.

   963 .sp

   964 If your program uses \fBsetlocale()\fP as described above, consider

   965 using the thread\-safe \fBuselocale()\fP instead.

   966 .SS API Reference

   967 .SS Preliminaries

   968 .sp

   969 All declarations are in \fBjansson.h\fP, so it\(aqs enough to

   970 .INDENT 0.0

   971 .INDENT 3.5

   972 .sp

   973 .nf

   974 .ft CW

   975 #include <jansson.h>

   976 .ft R

   977 .fi

   978 .UNINDENT

   979 .UNINDENT

   980 .sp

   981 in each source file.

   982 .sp

   983 All constants are prefixed with \fBJSON_\fP (except for those describing

   984 the library version, prefixed with \fBJANSSON_\fP). Other identifiers

   985 are prefixed with \fBjson_\fP\&. Type names are suffixed with \fB_t\fP and

   986 \fBtypedef\fP\(aqd so that the \fBstruct\fP keyword need not be used.

   987 .SS Library Version

   988 .sp

   989 The Jansson version is of the form \fIA.B.C\fP, where \fIA\fP is the major

   990 version, \fIB\fP is the minor version and \fIC\fP is the micro version. If the

   991 micro version is zero, it\(aqs omitted from the version string, i.e. the

   992 version string is just \fIA.B\fP\&.

   993 .sp

   994 When a new release only fixes bugs and doesn\(aqt add new features or

   995 functionality, the micro version is incremented. When new features are

   996 added in a backwards compatible way, the minor version is incremented

   997 and the micro version is set to zero. When there are backwards

   998 incompatible changes, the major version is incremented and others are

   999 set to zero.

  1000 .sp

  1001 The following preprocessor constants specify the current version of

  1002 the library:

  1003 .INDENT 0.0

  1004 .TP

  1005 .B \fBJANSSON_MAJOR_VERSION\fP, \fBJANSSON_MINOR_VERSION\fP, \fBJANSSON_MICRO_VERSION\fP

  1006 Integers specifying the major, minor and micro versions,

  1007 respectively.

  1008 .TP

  1009 .B \fBJANSSON_VERSION\fP

  1010 A string representation of the current version, e.g. \fB"1.2.1"\fP or

  1011 \fB"1.3"\fP\&.

  1012 .TP

  1013 .B \fBJANSSON_VERSION_HEX\fP

  1014 A 3\-byte hexadecimal representation of the version, e.g.

  1015 \fB0x010201\fP for version 1.2.1 and \fB0x010300\fP for version 1.3.

  1016 This is useful in numeric comparisions, e.g.:

  1017 .INDENT 7.0

  1018 .INDENT 3.5

  1019 .sp

  1020 .nf

  1021 .ft CW

  1022 #if JANSSON_VERSION_HEX >= 0x010300

  1023 /* Code specific to version 1.3 and above */

  1024 #endif

  1025 .ft R

  1026 .fi

  1027 .UNINDENT

  1028 .UNINDENT

  1029 .UNINDENT

  1030 .SS Value Representation

  1031 .sp

  1032 The JSON specification (\fI\%RFC 4627\fP) defines the following data types:

  1033 \fIobject\fP, \fIarray\fP, \fIstring\fP, \fInumber\fP, \fIboolean\fP, and \fInull\fP\&. JSON

  1034 types are used dynamically; arrays and objects can hold any other data

  1035 type, including themselves. For this reason, Jansson\(aqs type system is

  1036 also dynamic in nature. There\(aqs one C type to represent all JSON

  1037 values, and this structure knows the type of the JSON value it holds.

  1038 .INDENT 0.0

  1039 .TP

  1040 .B json_t

  1041 This data structure is used throughout the library to represent all

  1042 JSON values. It always contains the type of the JSON value it holds

  1043 and the value\(aqs reference count. The rest depends on the type of the

  1044 value.

  1045 .UNINDENT

  1046 .sp

  1047 Objects of \fBjson_t\fP are always used through a pointer. There

  1048 are APIs for querying the type, manipulating the reference count, and

  1049 for constructing and manipulating values of different types.

  1050 .sp

  1051 Unless noted otherwise, all API functions return an error value if an

  1052 error occurs. Depending on the function\(aqs signature, the error value

  1053 is either \fINULL\fP or \-1. Invalid arguments or invalid input are

  1054 apparent sources for errors. Memory allocation and I/O operations may

  1055 also cause errors.

  1056 .SS Type

  1057 .sp

  1058 The type of a JSON value is queried and tested using the following

  1059 functions:

  1060 .INDENT 0.0

  1061 .TP

  1062 .B enum json_type

  1063 The type of a JSON value. The following members are defined:

  1064 .TS

  1065 center;

  1066 |l|.

  1067 _

  1068 T{

  1069 \fBJSON_OBJECT\fP

  1070 T}

  1071 _

  1072 T{

  1073 \fBJSON_ARRAY\fP

  1074 T}

  1075 _

  1076 T{

  1077 \fBJSON_STRING\fP

  1078 T}

  1079 _

  1080 T{

  1081 \fBJSON_INTEGER\fP

  1082 T}

  1083 _

  1084 T{

  1085 \fBJSON_REAL\fP

  1086 T}

  1087 _

  1088 T{

  1089 \fBJSON_TRUE\fP

  1090 T}

  1091 _

  1092 T{

  1093 \fBJSON_FALSE\fP

  1094 T}

  1095 _

  1096 T{

  1097 \fBJSON_NULL\fP

  1098 T}

  1099 _

  1100 .TE

  1101 .sp

  1102 These correspond to JSON object, array, string, number, boolean and

  1103 null. A number is represented by either a value of the type

  1104 \fBJSON_INTEGER\fP or of the type \fBJSON_REAL\fP\&. A true boolean value

  1105 is represented by a value of the type \fBJSON_TRUE\fP and false by a

  1106 value of the type \fBJSON_FALSE\fP\&.

  1107 .UNINDENT

  1108 .INDENT 0.0

  1109 .TP

  1110 .B int json_typeof(const json_t\fI\ *json\fP)

  1111 Return the type of the JSON value (a \fBjson_type\fP cast to

  1112 \fBint\fP). \fIjson\fP MUST NOT be \fINULL\fP\&. This function is actually

  1113 implemented as a macro for speed.

  1114 .UNINDENT

  1115 .INDENT 0.0

  1116 .TP

  1117 .B json_is_object(const json_t\fI\ *json\fP)

  1118 .TP

  1119 .B json_is_array(const json_t\fI\ *json\fP)

  1120 .TP

  1121 .B json_is_string(const json_t\fI\ *json\fP)

  1122 .TP

  1123 .B json_is_integer(const json_t\fI\ *json\fP)

  1124 .TP

  1125 .B json_is_real(const json_t\fI\ *json\fP)

  1126 .TP

  1127 .B json_is_true(const json_t\fI\ *json\fP)

  1128 .TP

  1129 .B json_is_false(const json_t\fI\ *json\fP)

  1130 .TP

  1131 .B json_is_null(const json_t\fI\ *json\fP)

  1132 These functions (actually macros) return true (non\-zero) for values

  1133 of the given type, and false (zero) for values of other types and

  1134 for \fINULL\fP\&.

  1135 .UNINDENT