1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>json-c: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">json-c
 <span id="projectnumber">0.16</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">json-c Documentation</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><code>json-c</code></h1>
<ol type="1">
<li><a href="#overview">Overview and Build Status</a></li>
<li><a href="#buildunix">Building on Unix</a><ul>
<li><a href="#installprereq">Prerequisites</a></li>
<li><a href="#buildcmds">Build commands</a></li>
</ul>
</li>
<li><a href="#CMake">CMake options</a></li>
<li><a href="#testing">Testing</a></li>
<li><a href="#buildvcpkg">Building with `vcpkg`</a></li>
<li><a href="#linking">Linking to libjson-c</a></li>
<li><a href="#using">Using json-c</a></li>
</ol>
<h2>JSON-C - A JSON implementation in C <a class="anchor" id="overview"></a></h2>
<p>JSON-C implements a reference counting object model that allows you to easily construct JSON objects in C, output them as JSON formatted strings and parse JSON formatted strings back into the C representation of JSON objects. It aims to conform to <a href="https://tools.ietf.org/html/rfc7159">RFC 7159</a>.</p>
<p>Skip down to <a href="#using">Using json-c</a> or check out the <a href="https://json-c.github.io/json-c/">API docs</a>, if you already have json-c installed and ready to use.</p>
<p>Home page for json-c: <a href="https://github.com/json-c/json-c/wiki">https://github.com/json-c/json-c/wiki</a></p>
<p>Build Status</p>
<ul>
<li><a href="https://ci.appveyor.com/project/hawicz/json-c">AppVeyor Build</a> <div class="image">
<img src="https://ci.appveyor.com/api/projects/status/github/json-c/json-c?branch=master&svg=true" alt="AppVeyor Build Status"/>
</div>
</li>
<li><a href="https://travis-ci.org/json-c/json-c">Travis Build</a> <div class="image">
<img src="https://travis-ci.org/json-c/json-c.svg?branch=master" alt="Travis Build Status"/>
</div>
</li>
</ul>
<p>Test Status</p>
<ul>
<li><a href="https://coveralls.io/github/json-c/json-c?branch=master">Coveralls</a> <a href="https://coveralls.io/github/json-c/json-c?branch=master"></a></li>
</ul>
<h2>Building on Unix with <code>git</code>, <code>gcc</code> and <code>cmake</code> <a class="anchor" id="buildunix"></a></h2>
<p>If you already have json-c installed, see <a href="#linking">Linking to `libjson-c`</a> for how to build and link your program against it.</p>
<h3>Prerequisites: <a class="anchor" id="installprereq"></a></h3>
<ul>
<li><code>gcc</code>, <code>clang</code>, or another C compiler</li>
</ul>
<ul>
<li><code>cmake>=2.8</code>, <code>>=3.16</code> recommended, <code>cmake=>3.1</code> for tests</li>
</ul>
<p>To generate docs you'll also need:</p>
<ul>
<li><code>doxygen>=1.8.13</code></li>
</ul>
<p>If you are on a relatively modern system, you'll likely be able to install the prerequisites using your OS's packaging system.</p>
<h3>Install using apt (e.g. Ubuntu 16.04.2 LTS)</h3>
<pre class="fragment">sudo apt install git
sudo apt install cmake
sudo apt install doxygen # optional
sudo apt install valgrind # optional
</pre><h3>Build instructions: <a class="anchor" id="buildcmds"></a></h3>
<p><code>json-c</code> GitHub repo: <a href="https://github.com/json-c/json-c">https://github.com/json-c/json-c</a> </p>
<pre class="fragment">$ git clone https://github.com/json-c/json-c.git
$ mkdir json-c-build
$ cd json-c-build
$ cmake ../json-c # See CMake section below for custom arguments
</pre><p>Note: it's also possible to put your build directory inside the json-c source directory, or even not use a separate build directory at all, but certain things might not work quite right (notably, <code>make distcheck</code>)</p>
<p>Then: </p>
<pre class="fragment">$ make
$ make test
$ make USE_VALGRIND=0 test # optionally skip using valgrind
$ make install
</pre><h3>Generating documentation with Doxygen:</h3>
<p>The library documentation can be generated directly from the source code using Doxygen tool: </p>
<pre class="fragment"># in build directory
make doc
google-chrome doc/html/index.html
</pre><h2>CMake Options <a class="anchor" id="CMake"></a></h2>
<p>The json-c library is built with <a href="https://cmake.org/cmake-tutorial/">CMake</a>, which can take a few options.</p>
<table class="doxtable">
<tr>
<th>Variable </th><th>Type </th><th>Description</th></tr>
<tr>
<td>CMAKE_INSTALL_PREFIX </td><td>String </td><td>The install location. </td></tr>
<tr>
<td>CMAKE_BUILD_TYPE </td><td>String </td><td>Defaults to "debug". </td></tr>
<tr>
<td>BUILD_SHARED_LIBS </td><td>Bool </td><td>The default build generates a dynamic (dll/so) library. Set this to OFF to create a static library only. </td></tr>
<tr>
<td>BUILD_STATIC_LIBS </td><td>Bool </td><td>The default build generates a static (lib/a) library. Set this to OFF to create a shared library only. </td></tr>
<tr>
<td>DISABLE_STATIC_FPIC </td><td>Bool </td><td>The default builds position independent code. Set this to OFF to create a shared library only. </td></tr>
<tr>
<td>DISABLE_BSYMBOLIC </td><td>Bool </td><td>Disable use of -Bsymbolic-functions. </td></tr>
<tr>
<td>DISABLE_THREAD_LOCAL_STORAGE </td><td>Bool </td><td>Disable use of Thread-Local Storage (HAVE___THREAD). </td></tr>
<tr>
<td>DISABLE_WERROR </td><td>Bool </td><td>Disable use of -Werror. </td></tr>
<tr>
<td>ENABLE_RDRAND </td><td>Bool </td><td>Enable RDRAND Hardware RNG Hash Seed. </td></tr>
<tr>
<td>ENABLE_THREADING </td><td>Bool </td><td>Enable partial threading support. </td></tr>
<tr>
<td>OVERRIDE_GET_RANDOM_SEED </td><td>String </td><td>A block of code to use instead of the default implementation of json_c_get_random_seed(), e.g. on embedded platforms where not even the fallback to time() works. Must be a single line. </td></tr>
</table>
<p>Pass these options as <code>-D</code> on CMake's command-line. </p>
<pre class="fragment"># build a static library only
cmake -DBUILD_SHARED_LIBS=OFF ..
</pre><h3>Building with partial threading support</h3>
<p>Although json-c does not support fully multi-threaded access to object trees, it has some code to help make its use in threaded programs a bit safer. Currently, this is limited to using atomic operations for <a class="el" href="json__object_8h.html#a675aa3a9cced685dbfd1c1a770a0c3e4">json_object_get()</a> and <a class="el" href="json__object_8h.html#afabf61f932cd64a4122ca8092452eed5">json_object_put()</a>.</p>
<p>Since this may have a performance impact, of at least 3x slower according to <a href="https://stackoverflow.com/a/11609063,">https://stackoverflow.com/a/11609063,</a> it is disabled by default. You may turn it on by adjusting your cmake command with: -DENABLE_THREADING=ON</p>
<p>Separately, the default hash function used for object field keys, lh_char_hash, uses a compare-and-swap operation to ensure the random seed is only generated once. Because this is a one-time operation, it is always compiled in when the compare-and-swap operation is available.</p>
<h3>cmake-configure wrapper script</h3>
<p>For those familiar with the old autoconf/autogen.sh/configure method, there is a <code>cmake-configure</code> wrapper script to ease the transition to cmake. </p>
<pre class="fragment">mkdir build
cd build
../cmake-configure --prefix=/some/install/path
make
</pre><p>cmake-configure can take a few options.</p>
<table class="doxtable">
<tr>
<th>options </th><th>Description</th></tr>
<tr>
<td>prefix=PREFIX </td><td>install architecture-independent files in PREFIX </td></tr>
<tr>
<td>enable-threading </td><td>Enable code to support partly multi-threaded use </td></tr>
<tr>
<td>enable-rdrand </td><td>Enable RDRAND Hardware RNG Hash Seed generation on supported x86/x64 platforms. </td></tr>
<tr>
<td>enable-shared </td><td>build shared libraries [default=yes] </td></tr>
<tr>
<td>enable-static </td><td>build static libraries [default=yes] </td></tr>
<tr>
<td>disable-Bsymbolic </td><td>Avoid linking with -Bsymbolic-function </td></tr>
<tr>
<td>disable-werror </td><td>Avoid treating compiler warnings as fatal errors </td></tr>
</table>
<h2>Testing: <a class="anchor" id="testing"></a></h2>
<p>By default, if valgrind is available running tests uses it. That can slow the tests down considerably, so to disable it use: </p>
<pre class="fragment">export USE_VALGRIND=0
</pre><p>To run tests a separate build directory is recommended: </p>
<pre class="fragment">mkdir build-test
cd build-test
# VALGRIND=1 causes -DVALGRIND=1 to be passed when compiling code
# which uses slightly slower, but valgrind-safe code.
VALGRIND=1 cmake ..
make
make test
# By default, if valgrind is available running tests uses it.
make USE_VALGRIND=0 test # optionally skip using valgrind
</pre><p>If a test fails, check <code>Testing/Temporary/LastTest.log</code>, <code>tests/testSubDir/${testname}/${testname}.vg.out</code>, and other similar files. If there is insufficient output try: </p>
<pre class="fragment">VERBOSE=1 CTEST_OUTPUT_ON_FAILURE=1 make test
</pre><p>or </p>
<pre class="fragment">JSONC_TEST_TRACE=1 make test
</pre><p>and check the log files again.</p>
<h2>Building on Unix and Windows with <code>vcpkg</code> <a class="anchor" id="buildvcpkg"></a></h2>
<p>You can download and install JSON-C using the <a href="https://github.com/Microsoft/vcpkg/">vcpkg</a> dependency manager: </p>
<pre class="fragment">git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install json-c
</pre><p>The JSON-C port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please <a href="https://github.com/Microsoft/vcpkg">create an issue or pull request</a> on the vcpkg repository.</p>
<h2>Linking to <code>libjson-c</code> <a class="anchor" id="linking"></a></h2>
<p>If your system has <code>pkgconfig</code>, then you can just add this to your <code>makefile</code>: </p>
<pre class="fragment">CFLAGS += $(shell pkg-config --cflags json-c)
LDFLAGS += $(shell pkg-config --libs json-c)
</pre><p>Without <code>pkgconfig</code>, you might do something like this: </p>
<pre class="fragment">JSON_C_DIR=/path/to/json_c/install
CFLAGS += -I$(JSON_C_DIR)/include/json-c
# Or to use lines like: #include <json-c/json_object.h>
#CFLAGS += -I$(JSON_C_DIR)/include
LDFLAGS+= -L$(JSON_C_DIR)/lib -ljson-c
</pre><p>If your project uses cmake:</p>
<ul>
<li><p class="startli">Add to your CMakeLists.txt file:</p>
<p class="startli">find_package(json-c CONFIG) target_link_libraries(${PROJECT_NAME} PRIVATE json-c::json-c)</p>
</li>
</ul>
<ul>
<li><p class="startli">Then you might run in your project:</p>
<p class="startli">cd build cmake -DCMAKE_PREFIX_PATH=/path/to/json_c/install/lib64/cmake ..</p>
</li>
</ul>
<h2>Using json-c <a class="anchor" id="using"></a></h2>
<p>To use json-c you can either include <a class="el" href="json_8h.html" title="A convenience header that may be included instead of other individual ones.">json.h</a>, or preferably, one of the following more specific header files:</p>
<ul>
<li><a class="el" href="json__object_8h.html" title="Core json-c API. Start here, or with json_tokener.h.">json_object.h</a> - Core types and methods.</li>
<li><a class="el" href="json__tokener_8h.html" title="Methods to parse an input string into a tree of json_object objects.">json_tokener.h</a> - Methods for parsing and serializing json-c object trees.</li>
<li><a class="el" href="json__pointer_8h.html" title="JSON Pointer (RFC 6901) implementation for retrieving objects from a json-c object tree...">json_pointer.h</a> - JSON Pointer (RFC 6901) implementation for retrieving objects from a json-c object tree.</li>
<li><a class="el" href="json__object__iterator_8h.html" title="An API for iterating over json_type_object objects, styled to be familiar to C++ programmers. Unlike json_object_object_foreach() and json_object_object_foreachC(), this avoids the need to expose json-c internals like lh_entry.">json_object_iterator.h</a> - Methods for iterating over single json_object instances. (See also <code><a class="el" href="json__object_8h.html#acf5f514a9e0061c10fc08055762639ee">json_object_object_foreach()</a></code> in <a class="el" href="json__object_8h.html" title="Core json-c API. Start here, or with json_tokener.h.">json_object.h</a>)</li>
<li><a class="el" href="json__visit_8h.html" title="Methods for walking a tree of objects.">json_visit.h</a> - Methods for walking a tree of json-c objects.</li>
<li><a class="el" href="json__util_8h.html" title="Miscllaneous utility functions and macros.">json_util.h</a> - Miscellaneous utility functions.</li>
</ul>
<p>For a full list of headers see <a href="https://json-c.github.io/json-c/json-c-current-release/doc/html/files.html">files.html</a></p>
<p>The primary type in json-c is json_object. It describes a reference counted tree of json objects which are created by either parsing text with a <a class="el" href="structjson__tokener.html">json_tokener</a> (i.e. <code><a class="el" href="json__tokener_8h.html#a61679f178111963a9ffa3c8179553f7a">json_tokener_parse_ex()</a></code>), or by creating (with <code><a class="el" href="json__object_8h.html#a68c383f54544fca19b5f2425be397600">json_object_new_object()</a></code>, <code><a class="el" href="json__object_8h.html#ae92f0770fb4b3c884ce35de52d3d7de8">json_object_new_int()</a></code>, etc...) and adding (with <code><a class="el" href="json__object_8h.html#a27bd808a022251059a43f1f6370441cd">json_object_object_add()</a></code>, <code><a class="el" href="json__object_8h.html#a18cdd9a7455e09f36cdf6e5756b7f586">json_object_array_add()</a></code>, etc...) them individually. Typically, every object in the tree will have one reference, from its parent. When you are done with the tree of objects, you call <a class="el" href="json__object_8h.html#afabf61f932cd64a4122ca8092452eed5">json_object_put()</a> on just the root object to free it, which recurses down through any child objects calling <a class="el" href="json__object_8h.html#afabf61f932cd64a4122ca8092452eed5">json_object_put()</a> on each one of those in turn.</p>
<p>You can get a reference to a single child (<code><a class="el" href="json__object_8h.html#a1a097805abb53b4c8a60d573730a8939">json_object_object_get()</a></code> or <code><a class="el" href="json__object_8h.html#a676711a76545d4ec65cc75f100f5fd19">json_object_array_get_idx()</a></code>) and use that object as long as its parent is valid. If you need a child object to live longer than its parent, you can increment the child's refcount (<code><a class="el" href="json__object_8h.html#a675aa3a9cced685dbfd1c1a770a0c3e4">json_object_get()</a></code>) to allow it to survive the parent being freed or it being removed from its parent (<code><a class="el" href="json__object_8h.html#ac6605fdafca20bd5d33c84f4f80a3bda">json_object_object_del()</a></code> or <code><a class="el" href="json__object_8h.html#a722eca9f578704d3af38b97549242c1f">json_object_array_del_idx()</a></code>)</p>
<p>When parsing text, the <a class="el" href="structjson__tokener.html">json_tokener</a> object is independent from the json_object that it returns. It can be allocated (<code><a class="el" href="json__tokener_8h.html#a5ac7e2c350bc592cf2fa7b9935b00ef5">json_tokener_new()</a></code>) used one or multiple times (<code><a class="el" href="json__tokener_8h.html#a61679f178111963a9ffa3c8179553f7a">json_tokener_parse_ex()</a></code>, and freed (<code><a class="el" href="json__tokener_8h.html#a887c4661906fc6b36cc366304e522534">json_tokener_free()</a></code>) while the json_object objects live on.</p>
<p>A json_object tree can be serialized back into a string with <code><a class="el" href="json__object_8h.html#a9db613127bd4ef7db42307e43a85fc1b">json_object_to_json_string_ext()</a></code>. The string that is returned is only valid until the next "to_json_string" call on that same object. Also, it is freed when the json_object is freed. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu Apr 14 2022 01:11:24 for json-c by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.2
</small></address>
</body>
</html>
|
