}
+Error reporting
+===============
+
+Jansson uses a single struct type to pass error information to the
+user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
+:ref:`apiref-unpack` for functions that pass error information using
+this struct.
+
+.. type:: json_error_t
+
+ .. member:: char text[]
+
+ The error message (in UTF-8), or an empty string if a message is
+ not available.
+
+ .. member:: char source[]
+
+ Source of the error. This can be (a part of) the file name or a
+ special identifier in angle brackers (e.g. ``<string>``).
+
+ .. member:: int line
+
+ The line number on which the error occurred.
+
+ .. member:: int column
+
+ The column on which the error occurred. Note that this is the
+ *character column*, not the byte column, i.e. a multibyte UTF-8
+ character counts as one column.
+
+ .. member:: size_t position
+
+ The position in bytes from the start of the input. This is
+ useful for debugging Unicode encoding problems.
+
+The normal use of :type:`json_error_t` is to allocate it on the stack,
+and pass a pointer to a function. Example::
+
+ int main() {
+ json_t *json;
+ json_error_t error;
+
+ json = json_load_file("/path/to/file.json", 0, &error);
+ if(!json) {
+ /* the error variable contains error information */
+ }
+ ...
+ }
+
+Also note that if the call succeeded (``json != NULL`` in the above
+example), the contents of ``error`` are unspecified.
+
+All functions also accept *NULL* as the :type:`json_error_t` pointer,
+in which case no error information is returned to the caller.
+
+
Encoding
========
above. Returns 0 on success and -1 on error.
+.. _apiref-decoding:
+
Decoding
========
Decodes the JSON string *input* and returns the array or object it
contains, or *NULL* on error, in which case *error* is filled with
- information about the error. See above for discussion on the
- *error* parameter. *flags* is currently unused, and should be set
- to 0.
+ information about the error. *flags* is currently unused, and
+ should be set to 0.
.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
Decodes the JSON text in stream *input* and returns the array or
object it contains, or *NULL* on error, in which case *error* is
- filled with information about the error. See above for discussion
- on the *error* parameter. *flags* is currently unused, and should
- be set to 0.
+ filled with information about the error. *flags* is currently
+ unused, and should be set to 0.
.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
Decodes the JSON text in file *path* and returns the array or
object it contains, or *NULL* on error, in which case *error* is
- filled with information about the error. See above for discussion
- on the *error* parameter. *flags* is currently unused, and should
- be set to 0.
-
-.. type:: json_error_t
-
- This data structure is used to return information on decoding
- errors from the decoding functions.
-
- .. member:: const char *text
-
- The error message (in UTF-8), or an empty string if a message is
- not available.
-
- .. member:: int line
-
- The line number on which the error occurred, or -1 if this
- information is not available.
-
- .. member:: int column
-
- The character column on which the error occurred, or -1 if this
- information is not available.
-
- .. member:: const char *source
-
- Source of the error. This is (a part of) the file name when
- using :func:`json_load_file()`, or a special identifier in angle
- brackets otherwise (e.g. ``<string>``).
-
- The normal use of :type:`json_error_t` is to allocate it on the
- stack, and pass a pointer to a decoding function. Example::
-
- int main() {
- json_t *json;
- json_error_t error;
+ filled with information about the error. *flags* is currently
+ unused, and should be set to 0.
- json = json_load_file("/path/to/file.json", 0, &error);
- if(!json) {
- /* the error variable contains error information */
- }
- ...
- }
- Also note that if the decoding succeeded (``json != NULL`` in the
- above example), the contents of ``error`` are unspecified.
-
- All decoding functions also accept *NULL* as the
- :type:`json_error_t` pointer, in which case no error information
- is returned to the caller.
-
-
-.. _apiref-building-values:
+.. _apiref-pack:
Building values
===============
``O`` (any value) [json_t \*]
Like ``o``, but the argument's reference count is incremented.
- This is useful if you pack and array an array or object and want
- to keep the reference for the JSON value consumed by ``O`` to
+ This is useful if you pack into an array or object and want to
+ keep the reference for the JSON value consumed by ``O`` to
yourself.
``[fmt]`` (array)
json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
+.. _apiref-unpack:
+
Parsing and validating values
=============================
This sectinon describes functions that help to validate complex values
and extract, or *unpack*, data from them. Like :ref:`building values
-<apiref-building-values>`, this is also based on format strings.
+<apiref-pack>`, this is also based on format strings.
While a JSON value is unpacked, the type specified in the format
string is checked to match that of the JSON value. This is the
.. refcounting:: new
Returns a deep copy of *value*, or *NULL* on error.
+
+
+Custom memory allocation
+========================
+
+By default, Jansson uses :func:`malloc()` and :func:`free()` for
+memory allocation. These functions can be overridden if custom
+behavior is needed.
+
+.. type:: json_malloc_t
+
+ A typedef for a function pointer with :func:`malloc()`'s
+ signature::
+
+ typedef void *(*json_malloc_t)(size_t);
+
+.. type:: json_free_t
+
+ A typedef for a function pointer with :func:`free()`'s
+ signature::
+
+ typedef void (*json_free_t)(void *);
+
+.. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)
+
+ Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead
+ of :func:`free()`. This function has to be called before any other
+ Jansson's API functions to ensure that all memory operations use
+ the same functions.
+
+Examples:
+
+Use the `Boehm's conservative garbage collector`_ for memory
+operations::
+
+ json_set_alloc_funcs(GC_malloc, GC_free);
+
+.. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
+
+Allow storing sensitive data (e.g. passwords or encryption keys) in
+JSON structures by zeroing all memory when freed::
+
+ static void *secure_malloc(size_t size)
+ {
+ /* Store the memory area size in the beginning of the block */
+ void *ptr = malloc(size + 8);
+ *((size_t *)ptr) = size;
+ return ptr + 8;
+ }
+
+ static void secure_free(void *ptr)
+ {
+ size_t size;
+
+ ptr -= 8;
+ size = *((size_t *)ptr);
+
+ guaranteed_memset(ptr, 0, size);
+ free(ptr);
+ }
+
+ int main()
+ {
+ json_set_alloc_funcs(secure_malloc, secure_free);
+ /* ... */
+ }
+
+For more information about the issues of storing sensitive data in
+memory, see
+http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
+The page also examplains the :func:`guaranteed_memset()` function used
+in the example and gives a sample implementation for it.