diff --git a/doc/html/README_8md.html b/doc/html/README_8md.html new file mode 100644 index 0000000..13b65bf --- /dev/null +++ b/doc/html/README_8md.html @@ -0,0 +1,51 @@ + + +
+ + + + +|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
| Carray_list | |
| Cjson_object_iter | |
| Cjson_object_iterator | |
| Cjson_patch_error | |
| Cjson_pointer_get_result | |
| Cjson_tokener | |
| Cjson_tokener_srec | |
| Clh_entry | |
| Clh_table | |
| Cprintbuf |
|
+ json-c 0.19
+
+ |
+
Internal methods for working with json_type_array objects. Although this is exposed by the json_object_get_array() method, it is not recommended for direct use. +More...
++Data Structures | |
| struct | array_list |
+Macros | |
| #define | ARRAY_LIST_DEFAULT_SIZE 32 |
+Typedefs | |
| typedef void() | array_list_free_fn(void *data) |
| typedef struct array_list | array_list |
+Functions | |
| struct array_list * | array_list_new (array_list_free_fn *free_fn) |
| struct array_list * | array_list_new2 (array_list_free_fn *free_fn, int initial_size) |
| void | array_list_free (struct array_list *al) |
| void * | array_list_get_idx (struct array_list *al, size_t i) |
| int | array_list_insert_idx (struct array_list *al, size_t i, void *data) |
| int | array_list_put_idx (struct array_list *al, size_t i, void *data) |
| int | array_list_add (struct array_list *al, void *data) |
| int | array_list_set_idx (struct array_list *al, size_t i, void *data) |
| size_t | array_list_length (struct array_list *al) |
| void | array_list_sort (struct array_list *arr, int(*compar)(const void *, const void *)) |
| void * | array_list_bsearch (const void **key, struct array_list *arr, int(*compar)(const void *, const void *)) |
| int | array_list_del_idx (struct array_list *arr, size_t idx, size_t count) |
| int | array_list_shrink (struct array_list *arr, size_t empty_slots) |
Internal methods for working with json_type_array objects. Although this is exposed by the json_object_get_array() method, it is not recommended for direct use.
+| #define ARRAY_LIST_DEFAULT_SIZE 32 | +
| typedef struct array_list array_list | +
| typedef void() array_list_free_fn(void *data) | +
+
|
+ +extern | +
+
|
+ +extern | +
+
|
+ +extern | +
+
|
+ +extern | +
+
|
+ +extern | +
+
|
+ +extern | +
+
|
+ +extern | +
+
|
+ +extern | +
Allocate an array_list of the default size (32).
+
|
+ +extern | +
Allocate an array_list of the desired size.
+If possible, the size should be chosen to closely match the actual number of elements expected to be used. If the exact size is unknown, there are tradeoffs to be made:
+
|
+ +extern | +
+
|
+ +extern | +
Set the value at index i. Caller is responsible for freeing the previous value. To automatically free the existing value, use array_list_put_idx() instead.
+ +
+
|
+ +extern | +
Shrink the array list to just enough to fit the number of elements in it, plus empty_slots.
+ +
+
|
+ +extern | +
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
+Files | |
| json.h | |
| A convenience header that may be included instead of other individual ones. | |
|
+ json-c 0.19
+
+ |
+
| ▼ distcheck | |
| json.h | A convenience header that may be included instead of other individual ones |
| arraylist.h | Internal methods for working with json_type_array objects. Although this is exposed by the json_object_get_array() method, it is not recommended for direct use |
| json_c_version.h | Methods for retrieving the json-c version |
| json_inttypes.h | Do not use, json-c internal, may be changed or removed at any time |
| json_object.h | Core json-c API. Start here, or with json_tokener.h |
| json_object_iterator.h | 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_patch.h | JSON Patch (RFC 6902) implementation for manipulating JSON objects |
| json_pointer.h | JSON Pointer (RFC 6901) implementation for retrieving objects from a json-c object tree |
| json_pointer_private.h | Do not use, json-c internal, may be changed or removed at any time |
| json_tokener.h | Methods to parse an input string into a tree of json_object objects |
| json_types.h | Basic types used in a few places in json-c, but you should include "json_object.h" instead |
| json_util.h | Miscllaneous utility functions and macros |
| json_visit.h | Methods for walking a tree of objects |
| linkhash.h | Internal methods for working with json_type_object objects. Although this is exposed by the json_object_get_object() function and within the json_object_iter type, it is not recommended for direct use |
| printbuf.h | Internal string buffer handling. Unless you're writing a json_object_to_json_string_fn implementation for use with json_object_set_serializer() direct use of this is not recommended |
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
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 RFC 8259.
+Skip down to Using json-c or check out the API docs, if you already have json-c installed and ready to use.
+Home page for json-c: https://github.com/json-c/json-c/wiki
+ +If you have questions about using json-c, please start a thread on our forums at: https://groups.google.com/forum/#!forum/json-c
+If you believe you've discovered a bug, report it at (https://github.com/json-c/json-c/issues). Please be sure to include the version of json-c you're using, the OS you're running on, and any other relevant details. Fully reproducible test cases and/or patches to fix problems are greatly appreciated.
+Fixes for bugs, or small new features can be directly submitted as a pull request. For major new features or large changes of any kind, please first start a discussion on the forums.
+ +If you already have json-c installed, see Linking to `libjson-c` for how to build and link your program against it.
+Build Status
+Test Status
gcc, clang, or another C compilercmake>=2.8, >=3.16 recommended, cmake=>3.1 for testsTo generate docs you'll also need:
doxygen>=1.8.13If you are on a relatively modern system, you'll likely be able to install the prerequisites using your OS's packaging system.
+sudo apt install git +sudo apt install cmake +sudo apt install doxygen # optional +sudo apt install valgrind # optional ++
json-c GitHub repo: https://github.com/json-c/json-c
$ 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 +
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, make distcheck)
Then:
+$ make +$ make test +$ make USE_VALGRIND=0 test # optionally skip using valgrind +$ sudo make install # it could be necessary to execute make install +
The library documentation can be generated directly from the source code using Doxygen tool:
+# in build directory +make doc +google-chrome doc/html/index.html ++
The json-c library is built with CMake, which can take a few options.
+| Variable | Type | Description |
|---|---|---|
| CMAKE_INSTALL_PREFIX | String | The install location. |
| CMAKE_BUILD_TYPE | String | Defaults to "debug". |
| BUILD_SHARED_LIBS | Bool | The default build generates a dynamic (dll/so) library. Set this to OFF to create a static library only. |
| BUILD_STATIC_LIBS | Bool | The default build generates a static (lib/a) library. Set this to OFF to create a shared library only. |
| DISABLE_STATIC_FPIC | Bool | The default builds position independent code. Set this to OFF to create a shared library only. |
| DISABLE_BSYMBOLIC | Bool | Disable use of -Bsymbolic-functions. |
| DISABLE_THREAD_LOCAL_STORAGE | Bool | Disable use of Thread-Local Storage (HAVE___THREAD). |
| DISABLE_WERROR | Bool | Disable use of -Werror. |
| DISABLE_EXTRA_LIBS | Bool | Disable use of extra libraries, libbsd |
| DISABLE_JSON_POINTER | Bool | Omit json_pointer support from the build. |
| ENABLE_RDRAND | Bool | Enable RDRAND Hardware RNG Hash Seed. |
| ENABLE_THREADING | Bool | Enable partial threading support. |
| OVERRIDE_GET_RANDOM_SEED | String | 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. |
Pass these options as -D on CMake's command-line.
# build a static library only +cmake -DBUILD_SHARED_LIBS=OFF .. +
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 json_object_get() and json_object_put().
+Since this may have a performance impact, of at least 3x slower according to https://stackoverflow.com/a/11609063, it is disabled by default. You may turn it on by adjusting your cmake command with: -DENABLE_THREADING=ON
+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.
+For those familiar with the old autoconf/autogen.sh/configure method, there is a cmake-configure wrapper script to ease the transition to cmake.
mkdir build +cd build +../cmake-configure --prefix=/some/install/path +make +
cmake-configure can take a few options.
+| options | Description |
|---|---|
| prefix=PREFIX | install architecture-independent files in PREFIX |
| enable-threading | Enable code to support partly multi-threaded use |
| enable-rdrand | Enable RDRAND Hardware RNG Hash Seed generation on supported x86/x64 platforms. |
| enable-shared | build shared libraries [default=yes] |
| enable-static | build static libraries [default=yes] |
| disable-Bsymbolic | Avoid linking with -Bsymbolic-function |
| disable-werror | Avoid treating compiler warnings as fatal errors |
By default, if valgrind is available running tests uses it. That can slow the tests down considerably, so to disable it use:
export USE_VALGRIND=0 +
To run tests a separate build directory is recommended:
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 +
If a test fails, check Testing/Temporary/LastTest.log, tests/testSubDir/${testname}/${testname}.vg.out, and other similar files. If there is insufficient output try:
VERBOSE=1 CTEST_OUTPUT_ON_FAILURE=1 make test +
or
JSONC_TEST_TRACE=1 make test +
and check the log files again.
+ +You can download and install JSON-C using the vcpkg dependency manager:
git clone https://github.com/Microsoft/vcpkg.git +cd vcpkg +./bootstrap-vcpkg.sh +./vcpkg integrate install +vcpkg install json-c +
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 create an issue or pull request on the vcpkg repository.
+ +Building on Android is now particularly well supported, but there have been some reports of success using https://developer.android.com/ndk/guides/cmake
+mkdir json-c-build +cd json-c-build/ +export NDK_HOME=~/Library/Android/sdk/ndk/22.1.7171670/ +cmake \ + --toolchain=$NDK_HOME/build/cmake/android.toolchain.cmake \ + -DANDROID_STL=none \ + -DANDROID_ABI=arm64-v8a \ + -DANDROID_PLATFORM=android-29 \ + -DANDROID_LD=lld \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + -DCMAKE_INSTALL_PREFIX=<install prefix> \ + -DENABLE_THREADING=true \ + .. +make install ++
Building for Commodore Amiga is supported for both Motorola 68k (AmigaOS 3) and PowerPC (AmigaOS 4) architectures. MorphOS on compatible PowerPC hardware is also supported. You can set up a cross compiler locally, however it is much easier to use the already preconfigured Amiga development environment wtthin a Docker container.
+Install Docker on your machine if you don't already have it. You can download Docker Desktop for Windows/macOS/Linux here.
+mkdir build
+docker run --rm \
+ -v ${PWD}:/work \
+ -e USER=$( id -u ) -e GROUP=$( id -g ) \
+ -it sacredbanana/amiga-compiler:m68k-amigaos bash
+cd build
+cmake -DM68K_CRT=newlib ..
+make
+libjson-c.a will get created in the build directory.
+You can change newlib to nix20, nix13, ixemul or clib2 if you would like to build the library suited for libnix or clib2 instead. Newlib is default.
+mkdir build
+docker run --rm \
+ -v ${PWD}:/work \
+ -e USER=$( id -u ) -e GROUP=$( id -g ) \
+ -it sacredbanana/amiga-compiler:ppc-amigaos bash
+cd build
+cmake ..
+make
+libjson-c.a will get created in the build directory.
+mkdir build
+docker run --rm \
+ -v ${PWD}:/work \
+ -e USER=$( id -u ) -e GROUP=$( id -g ) \
+ -it sacredbanana/amiga-compiler:ppc-morphos bash
+cd build
+cmake -DNOIXEMUL=1 ..
+make
+If you are making an application that absolutely requires ixemul, then remove the -DNOIXEMUL=1.
libjson-c.a will get created in the build directory.
+ +If your system has pkgconfig, then you can just add this to your makefile:
CFLAGS += $(shell pkg-config --cflags json-c) +LDFLAGS += $(shell pkg-config --libs json-c) +
Without pkgconfig, you might do something like this:
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 +
If your project uses cmake:
+find_package(json-c CONFIG)
+target_link_libraries(${PROJECT_NAME} PRIVATE json-c::json-c)
+cd build +cmake -DCMAKE_PREFIX_PATH=/path/to/json_c/install/lib64/cmake .. ++
To use json-c you can either include json.h, or preferably, one of the following more specific header files:
+json_object_object_foreach() in json_object.h)For a full list of headers see files.html
+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 json_tokener (i.e. json_tokener_parse_ex()), or by creating (with json_object_new_object(), json_object_new_int(), etc...) and adding (with json_object_object_add(), json_object_array_add(), 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 json_object_put() on just the root object to free it, which recurses down through any child objects calling json_object_put() on each one of those in turn.
You can get a reference to a single child (json_object_object_get() or json_object_array_get_idx()) 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 (json_object_get()) to allow it to survive the parent being freed or it being removed from its parent (json_object_object_del() or json_object_array_del_idx())
When parsing text, the json_tokener object is independent from the json_object that it returns. It can be allocated (json_tokener_new()) used one or multiple times (json_tokener_parse_ex(), and freed (json_tokener_free()) while the json_object objects live on.
A json_object tree can be serialized back into a string with json_object_to_json_string_ext(). 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.
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+
|
+ json-c 0.19
+
+ |
+