12 All declarations are in :file:`jansson.h`, so it's enough to
20 All constants are prefixed with ``JSON_`` (except for those describing
21 the library version, prefixed with ``JANSSON_``). Other identifiers
22 are prefixed with ``json_``. Type names are suffixed with ``_t`` and
23 ``typedef``\ 'd so that the ``struct`` keyword need not be used.
29 The Jansson version is of the form *A.B.C*, where *A* is the major
30 version, *B* is the minor version and *C* is the micro version. If the
31 micro version is zero, it's omitted from the version string, i.e. the
32 version string is just *A.B*.
34 When a new release only fixes bugs and doesn't add new features or
35 functionality, the micro version is incremented. When new features are
36 added in a backwards compatible way, the minor version is incremented
37 and the micro version is set to zero. When there are backwards
38 incompatible changes, the major version is incremented and others are
41 The following preprocessor constants specify the current version of
44 ``JANSSON_MAJOR_VERSION``, ``JANSSON_MINOR_VERSION``, ``JANSSON_MICRO_VERSION``
45 Integers specifying the major, minor and micro versions,
49 A string representation of the current version, e.g. ``"1.2.1"`` or
52 ``JANSSON_VERSION_HEX``
53 A 3-byte hexadecimal representation of the version, e.g.
54 ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3.
55 This is useful in numeric comparisions, e.g.::
57 #if JANSSON_VERSION_HEX >= 0x010300
58 /* Code specific to version 1.3 and above */
65 The JSON specification (:rfc:`4627`) defines the following data types:
66 *object*, *array*, *string*, *number*, *boolean*, and *null*. JSON
67 types are used dynamically; arrays and objects can hold any other data
68 type, including themselves. For this reason, Jansson's type system is
69 also dynamic in nature. There's one C type to represent all JSON
70 values, and this structure knows the type of the JSON value it holds.
74 This data structure is used throughout the library to represent all
75 JSON values. It always contains the type of the JSON value it holds
76 and the value's reference count. The rest depends on the type of the
79 Objects of :type:`json_t` are always used through a pointer. There
80 are APIs for querying the type, manipulating the reference count, and
81 for constructing and manipulating values of different types.
83 Unless noted otherwise, all API functions return an error value if an
84 error occurs. Depending on the function's signature, the error value
85 is either *NULL* or -1. Invalid arguments or invalid input are
86 apparent sources for errors. Memory allocation and I/O operations may
93 The type of a JSON value is queried and tested using the following
96 .. type:: enum json_type
98 The type of a JSON value. The following members are defined:
100 +--------------------+
102 +--------------------+
104 +--------------------+
106 +--------------------+
108 +--------------------+
110 +--------------------+
112 +--------------------+
114 +--------------------+
116 +--------------------+
118 These correspond to JSON object, array, string, number, boolean and
119 null. A number is represented by either a value of the type
120 ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value
121 is represented by a value of the type ``JSON_TRUE`` and false by a
122 value of the type ``JSON_FALSE``.
124 .. function:: int json_typeof(const json_t *json)
126 Return the type of the JSON value (a :type:`json_type` cast to
127 :type:`int`). *json* MUST NOT be *NULL*. This function is actually
128 implemented as a macro for speed.
130 .. function:: json_is_object(const json_t *json)
131 json_is_array(const json_t *json)
132 json_is_string(const json_t *json)
133 json_is_integer(const json_t *json)
134 json_is_real(const json_t *json)
135 json_is_true(const json_t *json)
136 json_is_false(const json_t *json)
137 json_is_null(const json_t *json)
139 These functions (actually macros) return true (non-zero) for values
140 of the given type, and false (zero) for values of other types and
143 .. function:: json_is_number(const json_t *json)
145 Returns true for values of types ``JSON_INTEGER`` and
146 ``JSON_REAL``, and false for other types and for *NULL*.
148 .. function:: json_is_boolean(const json_t *json)
150 Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
151 for values of other types and for *NULL*.
154 .. _apiref-reference-count:
159 The reference count is used to track whether a value is still in use
160 or not. When a value is created, it's reference count is set to 1. If
161 a reference to a value is kept (e.g. a value is stored somewhere for
162 later use), its reference count is incremented, and when the value is
163 no longer needed, the reference count is decremented. When the
164 reference count drops to zero, there are no references left, and the
165 value can be destroyed.
167 The following functions are used to manipulate the reference count.
169 .. function:: json_t *json_incref(json_t *json)
171 Increment the reference count of *json* if it's not non-*NULL*.
174 .. function:: void json_decref(json_t *json)
176 Decrement the reference count of *json*. As soon as a call to
177 :func:`json_decref()` drops the reference count to zero, the value
178 is destroyed and it can no longer be used.
180 Functions creating new JSON values set the reference count to 1. These
181 functions are said to return a **new reference**. Other functions
182 returning (existing) JSON values do not normally increase the
183 reference count. These functions are said to return a **borrowed
184 reference**. So, if the user will hold a reference to a value returned
185 as a borrowed reference, he must call :func:`json_incref`. As soon as
186 the value is no longer needed, :func:`json_decref` should be called
187 to release the reference.
189 Normally, all functions accepting a JSON value as an argument will
190 manage the reference, i.e. increase and decrease the reference count
191 as needed. However, some functions **steal** the reference, i.e. they
192 have the same result as if the user called :func:`json_decref()` on
193 the argument right after calling the function. These functions are
194 suffixed with ``_new`` or have ``_new_`` somewhere in their name.
196 For example, the following code creates a new JSON array and appends
199 json_t *array, *integer;
201 array = json_array();
202 integer = json_integer(42);
204 json_array_append(array, integer);
205 json_decref(integer);
207 Note how the caller has to release the reference to the integer value
208 by calling :func:`json_decref()`. By using a reference stealing
209 function :func:`json_array_append_new()` instead of
210 :func:`json_array_append()`, the code becomes much simpler::
212 json_t *array = json_array();
213 json_array_append_new(array, json_integer(42));
215 In this case, the user doesn't have to explicitly release the
216 reference to the integer value, as :func:`json_array_append_new()`
217 steals the reference when appending the value to the array.
219 In the following sections it is clearly documented whether a function
220 will return a new or borrowed reference or steal a reference to its
227 A circular reference is created when an object or an array is,
228 directly or indirectly, inserted inside itself. The direct case is
231 json_t *obj = json_object();
232 json_object_set(obj, "foo", obj);
234 Jansson will refuse to do this, and :func:`json_object_set()` (and
235 all the other such functions for objects and arrays) will return with
236 an error status. The indirect case is the dangerous one::
238 json_t *arr1 = json_array(), *arr2 = json_array();
239 json_array_append(arr1, arr2);
240 json_array_append(arr2, arr1);
242 In this example, the array ``arr2`` is contained in the array
243 ``arr1``, and vice versa. Jansson cannot check for this kind of
244 indirect circular references without a performance hit, so it's up to
245 the user to avoid them.
247 If a circular reference is created, the memory consumed by the values
248 cannot be freed by :func:`json_decref()`. The reference counts never
249 drops to zero because the values are keeping the references to each
250 other. Moreover, trying to encode the values with any of the encoding
251 functions will fail. The encoder detects circular references and
252 returns an error status.
258 These three values are implemented as singletons, so the returned
259 pointers won't change between invocations of these functions.
261 .. function:: json_t *json_true(void)
265 Returns the JSON true value.
267 .. function:: json_t *json_false(void)
271 Returns the JSON false value.
273 .. function:: json_t *json_boolean(val)
277 Returns JSON false if ``val`` is zero, and JSON true otherwise.
278 This is a macro, and equivalent to ``val ? json_true() :
281 .. versionadded:: 2.4
284 .. function:: json_t *json_null(void)
288 Returns the JSON null value.
294 Jansson uses UTF-8 as the character encoding. All JSON strings must be
295 valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null
296 terminated C strings are used, so JSON strings may not contain
297 embedded null characters. All other Unicode codepoints U+0001 through
298 U+10FFFF are allowed.
300 .. function:: json_t *json_string(const char *value)
304 Returns a new JSON string, or *NULL* on error. *value* must be a
305 valid UTF-8 encoded Unicode string.
307 .. function:: json_t *json_string_nocheck(const char *value)
311 Like :func:`json_string`, but doesn't check that *value* is valid
312 UTF-8. Use this function only if you are certain that this really
313 is the case (e.g. you have already checked it by other means).
315 .. function:: const char *json_string_value(const json_t *string)
317 Returns the associated value of *string* as a null terminated UTF-8
318 encoded string, or *NULL* if *string* is not a JSON string.
320 The retuned value is read-only and must not be modified or freed by
321 the user. It is valid as long as *string* exists, i.e. as long as
322 its reference count has not dropped to zero.
324 .. function:: int json_string_set(const json_t *string, const char *value)
326 Sets the associated value of *string* to *value*. *value* must be a
327 valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
330 .. function:: int json_string_set_nocheck(const json_t *string, const char *value)
332 Like :func:`json_string_set`, but doesn't check that *value* is
333 valid UTF-8. Use this function only if you are certain that this
334 really is the case (e.g. you have already checked it by other
341 The JSON specification only contains one numeric type, "number". The C
342 programming language has distinct types for integer and floating-point
343 numbers, so for practical reasons Jansson also has distinct types for
344 the two. They are called "integer" and "real", respectively. For more
345 information, see :ref:`rfc-conformance`.
349 This is the C type that is used to store JSON integer values. It
350 represents the widest integer type available on your system. In
351 practice it's just a typedef of ``long long`` if your compiler
352 supports it, otherwise ``long``.
354 Usually, you can safely use plain ``int`` in place of
355 ``json_int_t``, and the implicit C integer conversion handles the
356 rest. Only when you know that you need the full 64-bit range, you
357 should use ``json_int_t`` explicitly.
359 ``JSON_INTEGER_IS_LONG_LONG``
361 This is a preprocessor variable that holds the value 1 if
362 :type:`json_int_t` is ``long long``, and 0 if it's ``long``. It
363 can be used as follows::
365 #if JSON_INTEGER_IS_LONG_LONG
366 /* Code specific for long long */
368 /* Code specific for long */
371 ``JSON_INTEGER_FORMAT``
373 This is a macro that expands to a :func:`printf()` conversion
374 specifier that corresponds to :type:`json_int_t`, without the
375 leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
376 is required because the actual type of :type:`json_int_t` can be
377 either ``long`` or ``long long``, and :func:`printf()` reuiqres
378 different length modifiers for the two.
382 json_int_t x = 123123123;
383 printf("x is %" JSON_INTEGER_FORMAT "\n", x);
386 .. function:: json_t *json_integer(json_int_t value)
390 Returns a new JSON integer, or *NULL* on error.
392 .. function:: json_int_t json_integer_value(const json_t *integer)
394 Returns the associated value of *integer*, or 0 if *json* is not a
397 .. function:: int json_integer_set(const json_t *integer, json_int_t value)
399 Sets the associated value of *integer* to *value*. Returns 0 on
400 success and -1 if *integer* is not a JSON integer.
402 .. function:: json_t *json_real(double value)
406 Returns a new JSON real, or *NULL* on error.
408 .. function:: double json_real_value(const json_t *real)
410 Returns the associated value of *real*, or 0.0 if *real* is not a
413 .. function:: int json_real_set(const json_t *real, double value)
415 Sets the associated value of *real* to *value*. Returns 0 on
416 success and -1 if *real* is not a JSON real.
418 In addition to the functions above, there's a common query function
419 for integers and reals:
421 .. function:: double json_number_value(const json_t *json)
423 Returns the associated value of the JSON integer or JSON real
424 *json*, cast to double regardless of the actual type. If *json* is
425 neither JSON real nor JSON integer, 0.0 is returned.
431 A JSON array is an ordered collection of other JSON values.
433 .. function:: json_t *json_array(void)
437 Returns a new JSON array, or *NULL* on error. Initially, the array
440 .. function:: size_t json_array_size(const json_t *array)
442 Returns the number of elements in *array*, or 0 if *array* is NULL
445 .. function:: json_t *json_array_get(const json_t *array, size_t index)
447 .. refcounting:: borrow
449 Returns the element in *array* at position *index*. The valid range
450 for *index* is from 0 to the return value of
451 :func:`json_array_size()` minus 1. If *array* is not a JSON array,
452 if *array* is *NULL*, or if *index* is out of range, *NULL* is
455 .. function:: int json_array_set(json_t *array, size_t index, json_t *value)
457 Replaces the element in *array* at position *index* with *value*.
458 The valid range for *index* is from 0 to the return value of
459 :func:`json_array_size()` minus 1. Returns 0 on success and -1 on
462 .. function:: int json_array_set_new(json_t *array, size_t index, json_t *value)
464 Like :func:`json_array_set()` but steals the reference to *value*.
465 This is useful when *value* is newly created and not used after
468 .. function:: int json_array_append(json_t *array, json_t *value)
470 Appends *value* to the end of *array*, growing the size of *array*
471 by 1. Returns 0 on success and -1 on error.
473 .. function:: int json_array_append_new(json_t *array, json_t *value)
475 Like :func:`json_array_append()` but steals the reference to
476 *value*. This is useful when *value* is newly created and not used
479 .. function:: int json_array_insert(json_t *array, size_t index, json_t *value)
481 Inserts *value* to *array* at position *index*, shifting the
482 elements at *index* and after it one position towards the end of
483 the array. Returns 0 on success and -1 on error.
485 .. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
487 Like :func:`json_array_insert()` but steals the reference to
488 *value*. This is useful when *value* is newly created and not used
491 .. function:: int json_array_remove(json_t *array, size_t index)
493 Removes the element in *array* at position *index*, shifting the
494 elements after *index* one position towards the start of the array.
495 Returns 0 on success and -1 on error. The reference count of the
496 removed value is decremented.
498 .. function:: int json_array_clear(json_t *array)
500 Removes all elements from *array*. Returns 0 on sucess and -1 on
501 error. The reference count of all removed values are decremented.
503 .. function:: int json_array_extend(json_t *array, json_t *other_array)
505 Appends all elements in *other_array* to the end of *array*.
506 Returns 0 on success and -1 on error.
512 A JSON object is a dictionary of key-value pairs, where the key is a
513 Unicode string and the value is any JSON value.
515 .. function:: json_t *json_object(void)
519 Returns a new JSON object, or *NULL* on error. Initially, the
522 .. function:: size_t json_object_size(const json_t *object)
524 Returns the number of elements in *object*, or 0 if *object* is not
527 .. function:: json_t *json_object_get(const json_t *object, const char *key)
529 .. refcounting:: borrow
531 Get a value corresponding to *key* from *object*. Returns *NULL* if
532 *key* is not found and on error.
534 .. function:: int json_object_set(json_t *object, const char *key, json_t *value)
536 Set the value of *key* to *value* in *object*. *key* must be a
537 valid null terminated UTF-8 encoded Unicode string. If there
538 already is a value for *key*, it is replaced by the new value.
539 Returns 0 on success and -1 on error.
541 .. function:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
543 Like :func:`json_object_set`, but doesn't check that *key* is
544 valid UTF-8. Use this function only if you are certain that this
545 really is the case (e.g. you have already checked it by other
548 .. function:: int json_object_set_new(json_t *object, const char *key, json_t *value)
550 Like :func:`json_object_set()` but steals the reference to
551 *value*. This is useful when *value* is newly created and not used
554 .. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
556 Like :func:`json_object_set_new`, but doesn't check that *key* is
557 valid UTF-8. Use this function only if you are certain that this
558 really is the case (e.g. you have already checked it by other
561 .. function:: int json_object_del(json_t *object, const char *key)
563 Delete *key* from *object* if it exists. Returns 0 on success, or
564 -1 if *key* was not found. The reference count of the removed value
567 .. function:: int json_object_clear(json_t *object)
569 Remove all elements from *object*. Returns 0 on success and -1 if
570 *object* is not a JSON object. The reference count of all removed
571 values are decremented.
573 .. function:: int json_object_update(json_t *object, json_t *other)
575 Update *object* with the key-value pairs from *other*, overwriting
576 existing keys. Returns 0 on success or -1 on error.
578 .. function:: int json_object_update_existing(json_t *object, json_t *other)
580 Like :func:`json_object_update()`, but only the values of existing
581 keys are updated. No new keys are created. Returns 0 on success or
584 .. versionadded:: 2.3
586 .. function:: int json_object_update_missing(json_t *object, json_t *other)
588 Like :func:`json_object_update()`, but only new keys are created.
589 The value of any existing key is not changed. Returns 0 on success
592 .. versionadded:: 2.3
594 The following macro can be used to iterate through all key-value pairs
597 .. function:: json_object_foreach(object, key, value)
599 Iterate over every key-value pair of ``object``, running the block
600 of code that follows each time with the proper values set to
601 variables ``key`` and ``value``, of types :type:`const char *` and
602 :type:`json_t *` respectively. Example::
604 /* obj is a JSON object */
608 json_object_foreach(obj, key, value) {
609 /* block of code that uses key and value */
612 The items are not returned in any particular order.
614 This macro expands to an ordinary ``for`` statement upon
615 preprocessing, so its performance is equivalent to that of
616 hand-written iteration code using the object iteration protocol
617 (see below). The main advantage of this macro is that it abstracts
618 away the complexity behind iteration, and makes for shorter, more
621 .. versionadded:: 2.3
624 The following functions implement an iteration protocol for objects,
625 allowing to iterate through all key-value pairs in an object. The
626 items are not returned in any particular order, as this would require
627 sorting due to the internal hashtable implementation.
629 .. function:: void *json_object_iter(json_t *object)
631 Returns an opaque iterator which can be used to iterate over all
632 key-value pairs in *object*, or *NULL* if *object* is empty.
634 .. function:: void *json_object_iter_at(json_t *object, const char *key)
636 Like :func:`json_object_iter()`, but returns an iterator to the
637 key-value pair in *object* whose key is equal to *key*, or NULL if
638 *key* is not found in *object*. Iterating forward to the end of
639 *object* only yields all key-value pairs of the object if *key*
640 happens to be the first key in the underlying hash table.
642 .. function:: void *json_object_iter_next(json_t *object, void *iter)
644 Returns an iterator pointing to the next key-value pair in *object*
645 after *iter*, or *NULL* if the whole object has been iterated
648 .. function:: const char *json_object_iter_key(void *iter)
650 Extract the associated key from *iter*.
652 .. function:: json_t *json_object_iter_value(void *iter)
654 .. refcounting:: borrow
656 Extract the associated value from *iter*.
658 .. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value)
660 Set the value of the key-value pair in *object*, that is pointed to
661 by *iter*, to *value*.
663 .. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
665 Like :func:`json_object_iter_set()`, but steals the reference to
666 *value*. This is useful when *value* is newly created and not used
669 .. function:: void *json_object_key_to_iter(const char *key)
671 Like :func:`json_object_iter_at()`, but much faster. Only works for
672 values returned by :func:`json_object_iter_key()`. Using other keys
673 will lead to segfaults. This function is used internally to
674 implement :func:`json_object_foreach`.
676 .. versionadded:: 2.3
678 The iteration protocol can be used for example as follows::
680 /* obj is a JSON object */
684 void *iter = json_object_iter(obj);
687 key = json_object_iter_key(iter);
688 value = json_object_iter_value(iter);
689 /* use key and value ... */
690 iter = json_object_iter_next(obj, iter);
697 Jansson uses a single struct type to pass error information to the
698 user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
699 :ref:`apiref-unpack` for functions that pass error information using
702 .. type:: json_error_t
704 .. member:: char text[]
706 The error message (in UTF-8), or an empty string if a message is
709 .. member:: char source[]
711 Source of the error. This can be (a part of) the file name or a
712 special identifier in angle brackers (e.g. ``<string>``).
716 The line number on which the error occurred.
718 .. member:: int column
720 The column on which the error occurred. Note that this is the
721 *character column*, not the byte column, i.e. a multibyte UTF-8
722 character counts as one column.
724 .. member:: size_t position
726 The position in bytes from the start of the input. This is
727 useful for debugging Unicode encoding problems.
729 The normal use of :type:`json_error_t` is to allocate it on the stack,
730 and pass a pointer to a function. Example::
736 json = json_load_file("/path/to/file.json", 0, &error);
738 /* the error variable contains error information */
743 Also note that if the call succeeded (``json != NULL`` in the above
744 example), the contents of ``error`` are generally left unspecified.
745 The decoding functions write to the ``position`` member also on
746 success. See :ref:`apiref-decoding` for more info.
748 All functions also accept *NULL* as the :type:`json_error_t` pointer,
749 in which case no error information is returned to the caller.
755 This sections describes the functions that can be used to encode
756 values to JSON. By default, only objects and arrays can be encoded
757 directly, since they are the only valid *root* values of a JSON text.
758 To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
761 By default, the output has no newlines, and spaces are used between
762 array and object elements for a readable output. This behavior can be
763 altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
764 described below. A newline is never appended to the end of the encoded
767 Each function takes a *flags* parameter that controls some aspects of
768 how the data is encoded. Its default value is 0. The following macros
769 can be ORed together to obtain *flags*.
772 Pretty-print the result, using newlines between array and object
773 items, and indenting with *n* spaces. The valid range for *n* is
774 between 0 and 31 (inclusive), other values result in an undefined
775 output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are
776 inserted between array and object items.
779 This flag enables a compact representation, i.e. sets the separator
780 between array and object items to ``","`` and between object keys
781 and values to ``":"``. Without this flag, the corresponding
782 separators are ``", "`` and ``": "`` for more readable output.
784 ``JSON_ENSURE_ASCII``
785 If this flag is used, the output is guaranteed to consist only of
786 ASCII characters. This is achived by escaping all Unicode
787 characters outside the ASCII range.
790 If this flag is used, all the objects in output are sorted by key.
791 This is useful e.g. if two JSON texts are diffed or visually
794 ``JSON_PRESERVE_ORDER``
795 If this flag is used, object keys in the output are sorted into the
796 same order in which they were first inserted to the object. For
797 example, decoding a JSON text and then encoding with this flag
798 preserves the order of object keys.
801 Specifying this flag makes it possible to encode any JSON value on
802 its own. Without it, only objects and arrays can be passed as the
803 *root* value to the encoding functions.
805 **Note:** Encoding any value may be useful in some scenarios, but
806 it's generally discouraged as it violates strict compatiblity with
807 :rfc:`4627`. If you use this flag, don't expect interoperatibility
808 with other JSON systems.
810 .. versionadded:: 2.1
812 ``JSON_ESCAPE_SLASH``
813 Escape the ``/`` characters in strings with ``\/``.
815 .. versionadded:: 2.4
817 The following functions perform the actual JSON encoding. The result
820 .. function:: char *json_dumps(const json_t *root, size_t flags)
822 Returns the JSON representation of *root* as a string, or *NULL* on
823 error. *flags* is described above. The return value must be freed
824 by the caller using :func:`free()`.
826 .. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
828 Write the JSON representation of *root* to the stream *output*.
829 *flags* is described above. Returns 0 on success and -1 on error.
830 If an error occurs, something may have already been written to
831 *output*. In this case, the output is undefined and most likely not
834 .. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
836 Write the JSON representation of *root* to the file *path*. If
837 *path* already exists, it is overwritten. *flags* is described
838 above. Returns 0 on success and -1 on error.
840 .. type:: json_dump_callback_t
842 A typedef for a function that's called by
843 :func:`json_dump_callback()`::
845 typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data);
847 *buffer* points to a buffer containing a chunk of output, *size* is
848 the length of the buffer, and *data* is the corresponding
849 :func:`json_dump_callback()` argument passed through.
851 On error, the function should return -1 to stop the encoding
852 process. On success, it should return 0.
854 .. versionadded:: 2.2
856 .. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags)
858 Call *callback* repeatedly, passing a chunk of the JSON
859 representation of *root* each time. *flags* is described above.
860 Returns 0 on success and -1 on error.
862 .. versionadded:: 2.2
870 This sections describes the functions that can be used to decode JSON
871 text to the Jansson representation of JSON data. The JSON
872 specification requires that a JSON text is either a serialized array
873 or object, and this requirement is also enforced with the following
874 functions. In other words, the top level value in the JSON text being
875 decoded must be either array or object. To decode any JSON value, use
876 the ``JSON_DECODE_ANY`` flag (see below).
878 See :ref:`rfc-conformance` for a discussion on Jansson's conformance
879 to the JSON specification. It explains many design decisions that
880 affect especially the behavior of the decoder.
882 Each function takes a *flags* parameter that can be used to control
883 the behavior of the decoder. Its default value is 0. The following
884 macros can be ORed together to obtain *flags*.
886 ``JSON_REJECT_DUPLICATES``
887 Issue a decoding error if any JSON object in the input text
888 contains duplicate keys. Without this flag, the value of the last
889 occurence of each key ends up in the result. Key equivalence is
890 checked byte-by-byte, without special Unicode comparison
893 .. versionadded:: 2.1
896 By default, the decoder expects an array or object as the input.
897 With this flag enabled, the decoder accepts any valid JSON value.
899 **Note:** Decoding any value may be useful in some scenarios, but
900 it's generally discouraged as it violates strict compatiblity with
901 :rfc:`4627`. If you use this flag, don't expect interoperatibility
902 with other JSON systems.
904 .. versionadded:: 2.3
906 ``JSON_DISABLE_EOF_CHECK``
907 By default, the decoder expects that its whole input constitutes a
908 valid JSON text, and issues an error if there's extra data after
909 the otherwise valid JSON input. With this flag enabled, the decoder
910 stops after decoding a valid JSON array or object, and thus allows
911 extra data after the JSON text.
913 Normally, reading will stop when the last ``]`` or ``}`` in the
914 JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and
915 ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra
916 UTF-8 code unit (up to 4 bytes of input). For example, decoding
917 ``4true`` correctly decodes the integer 4, but also reads the
918 ``t``. For this reason, if reading multiple consecutive values that
919 are not arrays or objects, they should be separated by at least one
920 whitespace character.
922 .. versionadded:: 2.1
924 Each function also takes an optional :type:`json_error_t` parameter
925 that is filled with error information if decoding fails. It's also
926 updated on success; the number of bytes of input read is written to
927 its ``position`` field. This is especially useful when using
928 ``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts.
930 .. versionadded:: 2.3
931 Number of bytes of input read is written to the ``position`` field
932 of the :type:`json_error_t` structure.
934 If no error or position information is needed, you can pass *NULL*.
936 The following functions perform the actual JSON decoding.
938 .. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
942 Decodes the JSON string *input* and returns the array or object it
943 contains, or *NULL* on error, in which case *error* is filled with
944 information about the error. *flags* is described above.
946 .. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
950 Decodes the JSON string *buffer*, whose length is *buflen*, and
951 returns the array or object it contains, or *NULL* on error, in
952 which case *error* is filled with information about the error. This
953 is similar to :func:`json_loads()` except that the string doesn't
954 need to be null-terminated. *flags* is described above.
956 .. versionadded:: 2.1
958 .. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
962 Decodes the JSON text in stream *input* and returns the array or
963 object it contains, or *NULL* on error, in which case *error* is
964 filled with information about the error. *flags* is described
967 This function will start reading the input from whatever position
968 the input file was, without attempting to seek first. If an error
969 occurs, the file position will be left indeterminate. On success,
970 the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
971 flag was used. In this case, the file position will be at the first
972 character after the last ``]`` or ``}`` in the JSON input. This
973 allows calling :func:`json_loadf()` on the same ``FILE`` object
974 multiple times, if the input consists of consecutive JSON texts,
975 possibly separated by whitespace.
977 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
981 Decodes the JSON text in file *path* and returns the array or
982 object it contains, or *NULL* on error, in which case *error* is
983 filled with information about the error. *flags* is described
986 .. type:: json_load_callback_t
988 A typedef for a function that's called by
989 :func:`json_load_callback()` to read a chunk of input data::
991 typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data);
993 *buffer* points to a buffer of *buflen* bytes, and *data* is the
994 corresponding :func:`json_load_callback()` argument passed through.
996 On error, the function should return ``(size_t)-1`` to abort the
997 decoding process. When there's no data left, it should return 0 to
998 report that the end of input has been reached.
1000 .. versionadded:: 2.4
1002 .. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)
1004 .. refcounting:: new
1006 Decodes the JSON text produced by repeated calls to *callback*, and
1007 returns the array or object it contains, or *NULL* on error, in
1008 which case *error* is filled with information about the error.
1009 *data* is passed through to *callback* on each call. *flags* is
1012 .. versionadded:: 2.4
1020 This section describes functions that help to create, or *pack*,
1021 complex JSON values, especially nested objects and arrays. Value
1022 building is based on a *format string* that is used to tell the
1023 functions about the expected arguments.
1025 For example, the format string ``"i"`` specifies a single integer
1026 value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s,
1027 b]"`` specifies an array value with two strings and a boolean as its
1030 /* Create the JSON integer 42 */
1033 /* Create the JSON array ["foo", "bar", true] */
1034 json_pack("[ssb]", "foo", "bar", 1);
1036 Here's the full list of format characters. The type in parentheses
1037 denotes the resulting JSON type, and the type in brackets (if any)
1038 denotes the C type that is expected as the corresponding argument.
1040 ``s`` (string) [const char \*]
1041 Convert a NULL terminated UTF-8 string to a JSON string.
1044 Output a JSON null value. No argument is consumed.
1046 ``b`` (boolean) [int]
1047 Convert a C :type:`int` to JSON boolean value. Zero is converted
1048 to ``false`` and non-zero to ``true``.
1050 ``i`` (integer) [int]
1051 Convert a C :type:`int` to JSON integer.
1053 ``I`` (integer) [json_int_t]
1054 Convert a C :type:`json_int_t` to JSON integer.
1056 ``f`` (real) [double]
1057 Convert a C :type:`double` to JSON real.
1059 ``o`` (any value) [json_t \*]
1060 Output any given JSON value as-is. If the value is added to an
1061 array or object, the reference to the value passed to ``o`` is
1062 stolen by the container.
1064 ``O`` (any value) [json_t \*]
1065 Like ``o``, but the argument's reference count is incremented.
1066 This is useful if you pack into an array or object and want to
1067 keep the reference for the JSON value consumed by ``O`` to
1071 Build an array with contents from the inner format string. ``fmt``
1072 may contain objects and arrays, i.e. recursive value building is
1076 Build an object with contents from the inner format string
1077 ``fmt``. The first, third, etc. format character represent a key,
1078 and must be ``s`` (as object keys are always strings). The second,
1079 fourth, etc. format character represent a value. Any value may be
1080 an object or array, i.e. recursive value building is supported.
1082 Whitespace, ``:`` and ``,`` are ignored.
1084 The following functions compose the value building API:
1086 .. function:: json_t *json_pack(const char *fmt, ...)
1088 .. refcounting:: new
1090 Build a new JSON value according to the format string *fmt*. For
1091 each format character (except for ``{}[]n``), one argument is
1092 consumed and used to build the corresponding value. Returns *NULL*
1095 .. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...)
1096 json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap)
1098 .. refcounting:: new
1100 Like :func:`json_pack()`, but an in the case of an error, an error
1101 message is written to *error*, if it's not *NULL*. The *flags*
1102 parameter is currently unused and should be set to 0.
1104 As only the errors in format string (and out-of-memory errors) can
1105 be caught by the packer, these two functions are most likely only
1106 useful for debugging format strings.
1110 /* Build an empty JSON object */
1113 /* Build the JSON object {"foo": 42, "bar": 7} */
1114 json_pack("{sisi}", "foo", 42, "bar", 7);
1116 /* Like above, ':', ',' and whitespace are ignored */
1117 json_pack("{s:i, s:i}", "foo", 42, "bar", 7);
1119 /* Build the JSON array [[1, 2], {"cool": true}] */
1120 json_pack("[[i,i],{s:b}]", 1, 2, "cool", 1);
1125 Parsing and Validating Values
1126 =============================
1128 This sectinon describes functions that help to validate complex values
1129 and extract, or *unpack*, data from them. Like :ref:`building values
1130 <apiref-pack>`, this is also based on format strings.
1132 While a JSON value is unpacked, the type specified in the format
1133 string is checked to match that of the JSON value. This is the
1134 validation part of the process. In addition to this, the unpacking
1135 functions can also check that all items of arrays and objects are
1136 unpacked. This check be enabled with the format character ``!`` or by
1137 using the flag ``JSON_STRICT``. See below for details.
1139 Here's the full list of format characters. The type in parentheses
1140 denotes the JSON type, and the type in brackets (if any) denotes the C
1141 type whose address should be passed.
1143 ``s`` (string) [const char \*]
1144 Convert a JSON string to a pointer to a NULL terminated UTF-8
1145 string. The resulting string is extracted by using
1146 :func:`json_string_value()` internally, so it exists as long as
1147 there are still references to the corresponding JSON string.
1150 Expect a JSON null value. Nothing is extracted.
1152 ``b`` (boolean) [int]
1153 Convert a JSON boolean value to a C :type:`int`, so that ``true``
1154 is converted to 1 and ``false`` to 0.
1156 ``i`` (integer) [int]
1157 Convert a JSON integer to C :type:`int`.
1159 ``I`` (integer) [json_int_t]
1160 Convert a JSON integer to C :type:`json_int_t`.
1162 ``f`` (real) [double]
1163 Convert a JSON real to C :type:`double`.
1165 ``F`` (integer or real) [double]
1166 Convert a JSON number (integer or real) to C :type:`double`.
1168 ``o`` (any value) [json_t \*]
1169 Store a JSON value with no conversion to a :type:`json_t` pointer.
1171 ``O`` (any value) [json_t \*]
1172 Like ``O``, but the JSON value's reference count is incremented.
1175 Convert each item in the JSON array according to the inner format
1176 string. ``fmt`` may contain objects and arrays, i.e. recursive
1177 value extraction is supporetd.
1180 Convert each item in the JSON object according to the inner format
1181 string ``fmt``. The first, third, etc. format character represent
1182 a key, and must be ``s``. The corresponding argument to unpack
1183 functions is read as the object key. The second fourth, etc.
1184 format character represent a value and is written to the address
1185 given as the corresponding argument. **Note** that every other
1186 argument is read from and every other is written to.
1188 ``fmt`` may contain objects and arrays as values, i.e. recursive
1189 value extraction is supporetd.
1191 .. versionadded:: 2.3
1192 Any ``s`` representing a key may be suffixed with a ``?`` to
1193 make the key optional. If the key is not found, nothing is
1194 extracted. See below for an example.
1197 This special format character is used to enable the check that
1198 all object and array items are accessed, on a per-value basis. It
1199 must appear inside an array or object as the last format character
1200 before the closing bracket or brace. To enable the check globally,
1201 use the ``JSON_STRICT`` unpacking flag.
1204 This special format character is the opposite of ``!``. If the
1205 ``JSON_STRICT`` flag is used, ``*`` can be used to disable the
1206 strict check on a per-value basis. It must appear inside an array
1207 or object as the last format character before the closing bracket
1210 Whitespace, ``:`` and ``,`` are ignored.
1212 The following functions compose the parsing and validation API:
1214 .. function:: int json_unpack(json_t *root, const char *fmt, ...)
1216 Validate and unpack the JSON value *root* according to the format
1217 string *fmt*. Returns 0 on success and -1 on failure.
1219 .. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...)
1220 int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap)
1222 Validate and unpack the JSON value *root* according to the format
1223 string *fmt*. If an error occurs and *error* is not *NULL*, write
1224 error information to *error*. *flags* can be used to control the
1225 behaviour of the unpacker, see below for the flags. Returns 0 on
1226 success and -1 on failure.
1230 The first argument of all unpack functions is ``json_t *root``
1231 instead of ``const json_t *root``, because the use of ``O`` format
1232 character causes the reference count of ``root``, or some value
1233 reachable from ``root``, to be increased. Furthermore, the ``o``
1234 format character may be used to extract a value as-is, which allows
1235 modifying the structure or contents of a value reachable from
1238 If the ``O`` and ``o`` format characters are not used, it's
1239 perfectly safe to cast a ``const json_t *`` variable to plain
1240 ``json_t *`` when used with these functions.
1242 The following unpacking flags are available:
1245 Enable the extra validation step checking that all object and
1246 array items are unpacked. This is equivalent to appending the
1247 format character ``!`` to the end of every array and object in the
1250 ``JSON_VALIDATE_ONLY``
1251 Don't extract any data, just validate the JSON value against the
1252 given format string. Note that object keys must still be specified
1253 after the format string.
1257 /* root is the JSON integer 42 */
1259 json_unpack(root, "i", &myint);
1260 assert(myint == 42);
1262 /* root is the JSON object {"foo": "bar", "quux": true} */
1265 json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean);
1266 assert(strcmp(str, "bar") == 0 && boolean == 1);
1268 /* root is the JSON array [[1, 2], {"baz": null} */
1270 json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz");
1271 /* returns 0 for validation success, nothing is extracted */
1273 /* root is the JSON array [1, 2, 3, 4, 5] */
1275 json_unpack(root, "[ii!]", &myint1, &myint2);
1276 /* returns -1 for failed validation */
1278 /* root is an empty JSON object */
1279 int myint = 0, myint2 = 0;
1280 json_unpack(root, "{s?i, s?[ii]}",
1282 "bar", &myint2, &myint3);
1283 /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */
1289 Testing for equality of two JSON values cannot, in general, be
1290 achieved using the ``==`` operator. Equality in the terms of the
1291 ``==`` operator states that the two :type:`json_t` pointers point to
1292 exactly the same JSON value. However, two JSON values can be equal not
1293 only if they are exactly the same value, but also if they have equal
1296 * Two integer or real values are equal if their contained numeric
1297 values are equal. An integer value is never equal to a real value,
1300 * Two strings are equal if their contained UTF-8 strings are equal,
1301 byte by byte. Unicode comparison algorithms are not implemented.
1303 * Two arrays are equal if they have the same number of elements and
1304 each element in the first array is equal to the corresponding
1305 element in the second array.
1307 * Two objects are equal if they have exactly the same keys and the
1308 value for each key in the first object is equal to the value of the
1309 corresponding key in the second object.
1311 * Two true, false or null values have no "contents", so they are equal
1312 if their types are equal. (Because these values are singletons,
1313 their equality can actually be tested with ``==``.)
1315 The following function can be used to test whether two JSON values are
1318 .. function:: int json_equal(json_t *value1, json_t *value2)
1320 Returns 1 if *value1* and *value2* are equal, as defined above.
1321 Returns 0 if they are inequal or one or both of the pointers are
1328 Because of reference counting, passing JSON values around doesn't
1329 require copying them. But sometimes a fresh copy of a JSON value is
1330 needed. For example, if you need to modify an array, but still want to
1331 use the original afterwards, you should take a copy of it first.
1333 Jansson supports two kinds of copying: shallow and deep. There is a
1334 difference between these methods only for arrays and objects. Shallow
1335 copying only copies the first level value (array or object) and uses
1336 the same child values in the copied value. Deep copying makes a fresh
1337 copy of the child values, too. Moreover, all the child values are deep
1338 copied in a recursive fashion.
1340 .. function:: json_t *json_copy(json_t *value)
1342 .. refcounting:: new
1344 Returns a shallow copy of *value*, or *NULL* on error.
1346 .. function:: json_t *json_deep_copy(json_t *value)
1348 .. refcounting:: new
1350 Returns a deep copy of *value*, or *NULL* on error.
1353 .. _apiref-custom-memory-allocation:
1355 Custom Memory Allocation
1356 ========================
1358 By default, Jansson uses :func:`malloc()` and :func:`free()` for
1359 memory allocation. These functions can be overridden if custom
1362 .. type:: json_malloc_t
1364 A typedef for a function pointer with :func:`malloc()`'s
1367 typedef void *(*json_malloc_t)(size_t);
1369 .. type:: json_free_t
1371 A typedef for a function pointer with :func:`free()`'s
1374 typedef void (*json_free_t)(void *);
1376 .. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)
1378 Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead
1379 of :func:`free()`. This function has to be called before any other
1380 Jansson's API functions to ensure that all memory operations use
1385 Use the `Boehm's conservative garbage collector`_ for memory
1388 json_set_alloc_funcs(GC_malloc, GC_free);
1390 .. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
1392 Allow storing sensitive data (e.g. passwords or encryption keys) in
1393 JSON structures by zeroing all memory when freed::
1395 static void *secure_malloc(size_t size)
1397 /* Store the memory area size in the beginning of the block */
1398 void *ptr = malloc(size + 8);
1399 *((size_t *)ptr) = size;
1403 static void secure_free(void *ptr)
1408 size = *((size_t *)ptr);
1410 guaranteed_memset(ptr, 0, size);
1416 json_set_alloc_funcs(secure_malloc, secure_free);
1420 For more information about the issues of storing sensitive data in
1422 http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
1423 The page also explains the :func:`guaranteed_memset()` function used
1424 in the example and gives a sample implementation for it.