Skip to contentSkip to conversation

kernel-shark-qt: Add Json-C as a third party dependency.

PATCH Superseded Yordan Karadzhov (VMware) 2 participants 8 messages Aug 7, 2018 – Aug 8, 2018

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 kernel-shark-qt: Add Json-C as a third party dependency.

This patch prepares the Cmake build infrastructure for the introduction of a Json I/O for filter configurations. The Json I/O will be added to the C API of KernelShark in the following patch.

---
 kernel-shark-qt/CMakeLists.txt        |  2 ++
 kernel-shark-qt/README                |  4 +--
 kernel-shark-qt/build/FindJSONC.cmake | 38 +++++++++++++++++++++++++++
 kernel-shark-qt/src/CMakeLists.txt    |  1 +
 4 files changed, 43 insertions(+), 2 deletions(-)
 create mode 100644 kernel-shark-qt/build/FindJSONC.cmake
kernel-shark-qt/CMakeLists.txt +2 -0
index 7a802cd..3516caa 100644
@@ -13,6 +13,7 @@ message("\n project: Kernel Shark: (version: ${KS_VERSION_STRING})\n")
 set(KS_DIR ${CMAKE_SOURCE_DIR})
 
 include(${KS_DIR}/build/FindTraceCmd.cmake)
+include(${KS_DIR}/build/FindJSONC.cmake)
 
 find_package(Doxygen)
 
@@ -24,6 +25,7 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -std=c++11 -pthread")
 
 include_directories(${KS_DIR}/src/
                     ${KS_DIR}/build/src/
+                    ${JSONC_INCLUDE_DIR}
                     ${TRACECMD_INCLUDE_DIR}
                     ${TRACEEVENT_INCLUDE_DIR})
 
kernel-shark-qt/README +2 -2
index 6ff77a5..e6818fc 100644
@@ -6,14 +6,14 @@ Third Party Software:
 ------------------------------------------------------------
 The external dependencies:
 1. In order to install the packages on Ubuntu do the following:
-    sudo apt-get install build-essential git cmake -y
+    sudo apt-get install build-essential git cmake libjson-c-dev -y
 
 1.1 I you want to be able to generate Doxygen documentation:
     sudo apt-get install graphviz doxygen-gui -y
 
 
 2. In order to install the packages on Fedora, as root do the following:
-    dnf install gcc gcc-c++ git cmake -y
+    dnf install gcc gcc-c++ git cmake json-c-devel -y
 
 2.1 I you want to be able to generate Doxygen documentation:
     dnf install graphviz doxygen -y
kernel-shark-qt/build/FindJSONC.cmake new file +38 -0
new file mode 100644
index 0000000..3bae20f
@@ -0,0 +1,38 @@
+# - Try to find json-c
+# https://cmake.org/Wiki/CMake:How_To_Find_Libraries
+# Once done this will define
+#  JSONC_FOUND - System has json-c
+#  JSONC_INCLUDE_DIRS - The json-c include directories
+#  JSONC_LIBRARIES - The libraries needed to use json-c
+#  JSONC_DEFINITIONS - Compiler switches required for using json-c
+
+find_package(PkgConfig)
+pkg_check_modules(PC_JSONC QUIET json-c)
+set(JSONC_DEFINITIONS ${PC_JSONC_CFLAGS_OTHER})
+
+find_path(JSONC_INCLUDE_DIR json.h
+          HINTS ${PC_JSONC_INCLUDEDIR} ${PC_JSONC_INCLUDE_DIRS}
+          PATH_SUFFIXES json-c)
+
+find_library(JSONC_LIBRARY NAMES json-c libjson-c
+             HINTS ${PC_JSONC_LIBDIR} ${PC_JSONC_LIBRARY_DIRS})
+
+find_library(JSONC_LIBRARY NAMES json-c libjson-c
+             HINTS ${PC_JSON-C_LIBDIR} ${PC_JSON-C_LIBRARY_DIRS})
+
+include(FindPackageHandleStandardArgs)
+# handle the QUIETLY and REQUIRED arguments and set JSONC_FOUND to TRUE
+# if all listed variables are TRUE
+find_package_handle_standard_args(JSONC DEFAULT_MSG
+                                  JSONC_LIBRARY JSONC_INCLUDE_DIR)
+
+if (NOT JSONC_FOUND)
+
+  message(FATAL_ERROR "Json-C is Required!\n")
+
+endif (NOT JSONC_FOUND)
+
+mark_as_advanced(JSONC_INCLUDE_DIR JSONC_LIBRARY)
+
+set(JSONC_LIBRARIES    ${JSONC_LIBRARY})
+set(JSONC_INCLUDE_DIRS ${JSONC_INCLUDE_DIR})
kernel-shark-qt/src/CMakeLists.txt +1 -0
index cd42920..ea5dbda 100644
@@ -6,6 +6,7 @@ add_library(kshark SHARED libkshark.c
                           libkshark-collection.c)
 
 target_link_libraries(kshark ${CMAKE_DL_LIBS}
+                             ${JSONC_LIBRARY}
                              ${TRACEEVENT_LIBRARY}
                              ${TRACECMD_LIBRARY})
 
Signature · 1 line
2.17.1
#1 lore raw

PATCH 2/2 kernel-shark-qt: Add Json I/O for filter configurations.

Add to the C API of KernelShark instruments for saving/loading of filter configuration to/from Json files.

---
 kernel-shark-qt/src/CMakeLists.txt   |   1 +
 kernel-shark-qt/src/libkshark-json.c | 601 +++++++++++++++++++++++++++
 kernel-shark-qt/src/libkshark.h      |  49 +++
 3 files changed, 651 insertions(+)
 create mode 100644 kernel-shark-qt/src/libkshark-json.c
kernel-shark-qt/src/CMakeLists.txt +1 -0
index ea5dbda..b3de765 100644
@@ -2,6 +2,7 @@ message("\n src ...")
 
 message(STATUS "libkshark")
 add_library(kshark SHARED libkshark.c
+                          libkshark-json.c
                           libkshark-model.c
                           libkshark-collection.c)
 
kernel-shark-qt/src/libkshark-json.c new file +601 -0

601 lines not on this page · raw message

kernel-shark-qt/src/libkshark.h +49 -0

61 lines not on this page · raw message

Signature · 1 line
2.17.1
#2 lore raw

Re: [PATCH 2/2] kernel-shark-qt: Add Json I/O for filter configurations.

Quoted 45 lines · On Tue, 7 Aug 2018 19:00:13 +0300 "Yordan Karadzhov (VMware)"…

Add to the C API of KernelShark instruments for saving/loading of filter configuration to/from Json files.

---
 kernel-shark-qt/src/CMakeLists.txt   |   1 +
 kernel-shark-qt/src/libkshark-json.c | 601 +++++++++++++++++++++++++++
 kernel-shark-qt/src/libkshark.h      |  49 +++
 3 files changed, 651 insertions(+)
 create mode 100644 kernel-shark-qt/src/libkshark-json.c
kernel-shark-qt/src/CMakeLists.txt +1 -0
index ea5dbda..b3de765 100644
@@ -2,6 +2,7 @@ message("\n src ...")
 
 message(STATUS "libkshark")
 add_library(kshark SHARED libkshark.c
+                          libkshark-json.c
                           libkshark-model.c
                           libkshark-collection.c)
 
kernel-shark-qt/src/libkshark-json.c new file +16 -0
new file mode 100644
index 0000000..d06488e
@@ -0,0 +1,601 @@
+// SPDX-License-Identifier: LGPL-2.1
+
+/*
+ * Copyright (C) 2018 VMware Inc, Yordan Karadzhov <[email protected]>
+ */
+
+ /**
+  *  @file    libkshark-json.c
+  *  @brief   Json Confoguration I/O.
+  */
+
+// C
+/** Use GNU C Library. */
+#define _GNU_SOURCE
+#include <stdio.h>
+

kernel-shark-qt/src/libkshark-json.c line 26

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+// KernelShark
+#include "libkshark.h"
+
+/**
+ * @brief Create an empty Json document and set its type description.
+ *
+ * @param type: String describing the type of the document,
+ *		e.g. "kshark.record.config" or "kshark.filter.config".
+ *
+ * @returns json_object instance. Use json_object_put() to free the object.

I wonder if we should add handlers like:

	kshark_config_free(struct json_object *jobj);

and call that instead? Perhaps even create our own object that may contain extra state that the json object does not, and return that?

Quoted 46 lines
kernel-shark-qt/src/libkshark-json.c new file +46 -0
+ */
+struct json_object *kshark_config_alloc(const char *type)
+{
+	json_object *jobj, *jtype;
+
+	jobj = json_object_new_object();
+	jtype = json_object_new_string(type);
+
+	if (!jobj || !jtype)
+		goto fail;
+
+	/* Set the type of this Json document. */
+	json_object_object_add(jobj, "type", jtype);
+
+	return jobj;
+
+ fail:
+	fprintf(stderr, "Failed to allocate memory for json_object.\n");
+	json_object_put(jobj);
+	json_object_put(jtype);
+
+	return NULL;
+}
+
+/**
+ * @brief Create an empty Record Configuration document. The type description
+ *	  is set to "kshark.record.config".
+ *
+ * @returns json_object instance. Use json_object_put() to free the object.
+ */
+struct json_object *kshark_record_config_alloc()
+{
+	return kshark_config_alloc("kshark.record.config");
+}
+
+/**
+ * @brief Create an empty Filter Configuration document. The type description
+ *	  is set to "kshark.filter.config".
+ *
+ * @returns json_object instance. Use json_object_put() to free the object.
+ */
+struct json_object *kshark_filter_config_alloc()
+{
+	return kshark_config_alloc("kshark.filter.config");;
+}
+

kernel-shark-qt/src/libkshark-json.c line 82

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+/**
+ * @brief Record the current configuration of an Event Id filter into a Json
+ *	  document.
+ *
+ * @param pevt: Input location for the Page event.
+ * @param filter: Input location for an Id filter.
+ * @param filter_name: The name of the filter to show up in the Json document.
+ * @param jobj: Input location for the json_object instance.
+ */
+void kshark_event_filter_to_json(struct pevent *pevt,

Please call "struct pevent" variables "pevent". Need to stay consistent. Ideally, we should pick a single name for types of data structures. This will be useful when we rename pevent to something else as well.

kernel-shark-qt/src/libkshark-json.c line 92

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+				 struct tracecmd_filter_id *filter,
+				 const char *filter_name,
+				 struct json_object *jobj)
+{
+	json_object *jfilter_data, *jevent, *jsystem, *jname;
+	int i, evt, *ids;
+	char *temp;
+
+	/* Get the array of Ids to be fitered. */
+	ids = tracecmd_filter_ids(filter);

ids needs to be freed. And tracecmd_filter_ids() needs documentation describing it :-/ (that's my fault, hmm Tzvetomir could fix this ;-).

It also needs to be checked for NULL.

Quoted 65 lines
kernel-shark-qt/src/libkshark-json.c new file +65 -0
+
+	/* Create a Json array and fill the Id values into it. */
+	jfilter_data = json_object_new_array();
+	if (!jfilter_data)
+		goto fail;
+
+	for (i = 0; i < filter->count; ++i) {
+		for (evt = 0; evt < pevt->nr_events; ++evt) {
+			if (pevt->events[evt]->id == ids[i]) {
+				jevent = json_object_new_object();
+
+				temp = pevt->events[evt]->system;
+				jsystem = json_object_new_string(temp);
+
+				temp = pevt->events[evt]->name;
+				jname = json_object_new_string(temp);
+
+				if (!jevent || !jsystem || !jname)
+					goto fail;
+
+				json_object_object_add(jevent, "system",
+							       jsystem);
+
+				json_object_object_add(jevent, "name",
+							       jname);
+
+				json_object_array_add(jfilter_data, jevent);
+
+				break;
+			}
+		}
+	}
+
+	/* Add the array of Ids to the filter config document. */
+	json_object_object_add(jobj, filter_name, jfilter_data);
+
+	return;
+
+ fail:
+	fprintf(stderr, "Failed to allocate memory for json_object.\n");
+	json_object_put(jfilter_data);
+	json_object_put(jevent);
+	json_object_put(jsystem);
+	json_object_put(jname);
+}
+
+/**
+ * @brief Load from Json document the configuration of an Event Id filter.
+ *
+ * @param pevt: Input location for the Page event.
+ * @param filter: Input location for an Id filter.
+ * @param filter_name: The name of the filter as showing up in the Json
+ *	               document.
+ * @param jobj: Input location for the json_object instance.
+ *
+ * @returns True, if a filter has been loaded. If the filter configuration
+ *	    document contains no data for this particular filter or in a case
+ *	    of an error, the function returns False.
+ */
+bool kshark_event_filter_from_json(struct pevent *pevt,
+				   struct tracecmd_filter_id *filter,
+				   const char *filter_name,
+				   struct json_object *jobj)
+{
+	json_object *jfilter, *jevent, *jsystem, *jname;

kernel-shark-qt/src/libkshark-json.c line 167

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+	const char *system_str, *name_str;
+	struct event_format *event;
+	int i, length;
+
+	/*
+	 * Use the name of the filter to find the array of events associated
+	 * with this filter. Notice that the filter config document may
+	 * contain no data for this particular filter.
+	 */
+	json_object_object_get_ex(jobj, filter_name, &jfilter);

Shouldn't you add a check of the return value of the above. Looking at the documentation:

http://json-c.github.io/json-c/json-c-0.12/doc/html/json__object_8h.html#af3f38b3395b1af8e9d3ac73818c3a936

You could have:

	ret = json_object_object_get_ex(jobj, filter_name, &jfilter);

	if (!ret || json_object_get_type(jfilter) != ...

kernel-shark-qt/src/libkshark-json.c line 177

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+	if (!jfilter || json_object_get_type(jfilter) != json_type_array)
+		return false;
+
+	/* Set the filter. */
+	length = json_object_array_length(jfilter);
+	for (i = 0; i < length; ++i) {
+		jevent = json_object_array_get_idx(jfilter, i);
+
+		json_object_object_get_ex(jevent, "system", &jsystem);
+		json_object_object_get_ex(jevent, "name", &jname);

Same here.

Quoted 19 lines
kernel-shark-qt/src/libkshark-json.c new file +19 -0
+		if (!jsystem || !jname)
+			goto fail;
+
+		system_str = json_object_get_string(jsystem);
+		name_str = json_object_get_string(jname);
+
+		event = pevent_find_event_by_name(pevt, system_str, name_str);
+		if (!event)
+			goto fail;
+
+		tracecmd_filter_id_add(filter, event->id);
+	}
+
+	return true;
+
+ fail:
+	fprintf(stderr, "Failed to load event filter from json_object.\n");
+	return false;
+}

kernel-shark-qt/src/libkshark-json.c line 206

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+
+static void kshark_task_filter_to_json(struct tracecmd_filter_id *filter,
+				       const char *filter_name,
+				       struct json_object *jobj)
+{
+	json_object *jfilter_data, *jpid;
+	int i, *ids;
+
+	/* Get the array of Ids to be fitered. */
+	ids = tracecmd_filter_ids(filter);

Again, ids need to be freed.

kernel-shark-qt/src/libkshark-json.c line 96

Quoted 4 lines
kernel-shark-qt/src/libkshark-json.c new file +4 -0
+
+	/* Create a Json array and fill the Id values into it. */
+	jfilter_data = json_object_new_array();
+	if (!jfilter_data)

Hmm, can json_object_put() take a NULL pointer?

Quoted 61 lines
kernel-shark-qt/src/libkshark-json.c new file +61 -0
+		goto fail;
+
+	for (i = 0; i < filter->count; ++i) {
+		jpid = json_object_new_int(ids[i]);
+		if (!jpid)
+			goto fail;
+
+		json_object_array_add(jfilter_data, jpid);
+	}
+
+	/* Add the array of Ids to the filter config document. */
+	json_object_object_add(jobj, filter_name, jfilter_data);
+
+	return;
+
+ fail:
+	fprintf(stderr, "Failed to allocate memory for json_object.\n");
+	json_object_put(jfilter_data);
+	json_object_put(jpid);
+}
+
+static bool kshark_task_filter_from_json(struct tracecmd_filter_id *filter,
+					 const char *filter_name,
+					 struct json_object *jobj)
+{
+	json_object *jfilter, *jpid;
+	int i, length;
+
+	/*
+	 * Use the name of the filter to find the array of events associated
+	 * with this filter. Notice that the filter config document may
+	 * contain no data for this particular filter.
+	 */
+	json_object_object_get_ex(jobj, filter_name, &jfilter);
+	if (!jfilter || json_object_get_type(jfilter) != json_type_array)
+		return false;
+
+	/* Set the filter. */
+	length = json_object_array_length(jfilter);
+	for (i = 0; i < length; ++i) {
+		jpid = json_object_array_get_idx(jfilter, i);
+		if (!jpid)
+			goto fail;
+
+		tracecmd_filter_id_add(filter, json_object_get_int(jpid));
+	}
+
+	return true;
+
+ fail:
+	fprintf(stderr, "Failed to load task filter from json_object.\n");
+	return false;
+}
+
+/**
+ * @brief Record the current configuration of the advanced filter into a Json
+ *	  document.
+ *
+ * @param kshark_ctx: Input location for session context pointer.
+ * @param jobj: Input location for the json_object instance.
+ */

kernel-shark-qt/src/libkshark-json.c line 281

Quoted 10 lines
kernel-shark-qt/src/libkshark-json.c new file +10 -0
+void kshark_adv_filters_to_json(struct kshark_context *kshark_ctx,
+				struct json_object *jobj)
+{
+	struct event_filter *adv_filter = kshark_ctx->advanced_event_filter;
+	json_object *jfilter_data, *jevent, *jsystem, *jname, *jfilter;
+	struct event_format **events;
+	char *str;
+	int i;
+
+	if (!kshark_ctx->advanced_event_filter->filters)

Should we also check if advanced_event_filter is NULL?

kernel-shark-qt/src/libkshark-json.c line 289

Quoted 8 lines
kernel-shark-qt/src/libkshark-json.c new file +8 -0
+		return;
+
+	/* Create a Json array and fill the Id values into it. */
+	jfilter_data = json_object_new_array();
+	if (!jfilter_data)
+		goto fail;
+
+	events = pevent_list_events(kshark_ctx->pevent, EVENT_SORT_SYSTEM);

events returned could be NULL. Need to check that.

(will review the rest tomorrow)

-- Steve

Quoted 26 lines
kernel-shark-qt/src/libkshark-json.c new file +26 -0
+
+	for (i = 0; events[i]; i++) {
+		str = pevent_filter_make_string(adv_filter,
+						events[i]->id);
+		if (!str)
+			continue;
+
+		jevent = json_object_new_object();
+		jsystem = json_object_new_string(events[i]->system);
+		jname = json_object_new_string(events[i]->name);
+		jfilter = json_object_new_string(str);
+		if (!jevent || !jsystem || !jname || !jfilter)
+			goto fail;
+
+		json_object_object_add(jevent, "system", jsystem);
+		json_object_object_add(jevent, "name", jname);
+		json_object_object_add(jevent, "condition", jfilter);
+
+		json_object_array_add(jfilter_data, jevent);
+	}
+
+	/* Add the array of advanced filters to the filter config document. */
+	json_object_object_add(jobj, "adv event filter", jfilter_data);
+
+	return;
+
#3 lore raw

Re: [PATCH 2/2] kernel-shark-qt: Add Json I/O for filter configurations.

Hi Steven,

Quoted 7 lines · Steven Rostedt
Quoted 7 lines

/**
+ * @brief Create an empty Json document and set its type description.
+ *
+ * @param type: String describing the type of the document,
+ * e.g. "kshark.record.config" or "kshark.filter.config".
+ *
+ * @returns json_object instance. Use json_object_put() to free the object.

Quoted 8 lines

I wonder if we should add handlers like:

	kshark_config_free(struct json_object *jobj);

and call that instead? Perhaps even create our own object that may contain extra state that the json object does not, and return that?

What do we gain by doing it this way?

Thanks!
Yordan

#4 lore raw

Re: [PATCH 2/2] kernel-shark-qt: Add Json I/O for filter configurations.

Quoted 12 lines · On Wed, 8 Aug 2018 14:48:10 +0300 "Yordan Karadzhov (VMware)"…

Hi Steven,

Quoted 9 lines · Steven Rostedt
Quoted 7 lines

/**
+ * @brief Create an empty Json document and set its type description.
+ *
+ * @param type: String describing the type of the document,
+ * e.g. "kshark.record.config" or "kshark.filter.config".
+ *
+ * @returns json_object instance. Use json_object_put() to free the object.

I wonder if we should add handlers like:

Quoted 9 lines
Quoted 6 lines
	kshark_config_free(struct json_object *jobj);

and call that instead? Perhaps even create our own object that may contain extra state that the json object does not, and return that?

What do we gain by doing it this way?

CONTROL!!!!! :-) :-)

But seriously, if we had our own abstraction for the json objects, we could carry extra data along with it if need be. In fact, we could abstract out completely that we use json. We could just add our own wrappers, and if some day in the future, something else comes along that's better than json, we could switch to that.

I'm not strongly committed to doing this abstraction, but I want us to think about it before we commit to anything. Like I said, forward compatibility is the difficult part. I don't know exactly how this is all going to end up being used, but I like to keep my options open.

-- Steve

#5 lore raw

Re: [PATCH 2/2] kernel-shark-qt: Add Json I/O for filter configurations.

Quoted 25 lines · Steven Rostedt
Quoted 12 lines · On Wed, 8 Aug 2018 14:48:10 +0300 "Yordan Karadzhov (VMware)"…

Hi Steven,

Quoted 9 lines · Steven Rostedt
Quoted 7 lines

/**
+ * @brief Create an empty Json document and set its type description.
+ *
+ * @param type: String describing the type of the document,
+ * e.g. "kshark.record.config" or "kshark.filter.config".
+ *
+ * @returns json_object instance. Use json_object_put() to free the object.

I wonder if we should add handlers like:

Quoted 9 lines
Quoted 6 lines
	kshark_config_free(struct json_object *jobj);

and call that instead? Perhaps even create our own object that may contain extra state that the json object does not, and return that?

What do we gain by doing it this way?

Quoted 9 lines
    CONTROL!!!!! :-) :-)

But seriously, if we had our own abstraction for the json objects, we could carry extra data along with it if need be. In fact, we could abstract out completely that we use json. We could just add our own wrappers, and if some day in the future, something else comes along that's better than json, we could switch to that.

OK will try to implement a wrapper and abstract out the use json.

Thanks!
Yordan

Quoted 7 lines

I'm not strongly committed to doing this abstraction, but I want us to think about it before we commit to anything. Like I said, forward compatibility is the difficult part. I don't know exactly how this is all going to end up being used, but I like to keep my options open.

-- Steve

#6 lore raw

Re: [PATCH 2/2] kernel-shark-qt: Add Json I/O for filter configurations.

In reply to Steven Rostedt
Quoted 6 lines · Steven Rostedt

kernel-shark-qt/src/libkshark-json.c line 96

Quoted 4 lines
kernel-shark-qt/src/libkshark-json.c new file +4 -0
+
+	/* Create a Json array and fill the Id values into it. */
+	jfilter_data = json_object_new_array();
+	if (!jfilter_data)

Hmm, can json_object_put() take a NULL pointer?

Yes, see here:

https://github.com/json-c/json-c/blob/master/json_object.c#L185

Thanks!
Yordan

#7 lore raw

Re: [PATCH 2/2] kernel-shark-qt: Add Json I/O for filter configurations.

Quoted 8 lines · On Wed, 8 Aug 2018 14:48:53 +0300 "Yordan Karadzhov (VMware)"…
Quoted 6 lines · Steven Rostedt

kernel-shark-qt/src/libkshark-json.c line 96

Quoted 4 lines
kernel-shark-qt/src/libkshark-json.c new file +4 -0
+
+	/* Create a Json array and fill the Id values into it. */
+	jfilter_data = json_object_new_array();
+	if (!jfilter_data)  

Hmm, can json_object_put() take a NULL pointer?

Quoted 4 lines

Yes, see here:

https://github.com/json-c/json-c/blob/master/json_object.c#L185

Sadly they don't appear to document this fact :-/

http://json-c.github.io/json-c/json-c-0.12/doc/html/json__object_8h.html#a1bb50e2d17832c404c3d5f13fbde5bf5

-- Steve