}
+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;
-
- 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.
+ filled with information about the error. *flags* is currently
+ unused, and should be set to 0.
-.. _apiref-building-values:
+.. _apiref-pack:
Building values
===============
fourth, etc. format character represent a value. Any value may be
an object or array, i.e. recursive value building is supported.
+The following functions compose the value building API:
.. function:: json_t *json_pack(const char *fmt, ...)
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
-validation part of the process. By default, the unpacking functions
-also check that all items of arrays and objects are unpacked. This
-check be disabled with the format character ``*`` or by using the flag
-``JSON_UNPACK_ONLY``.
+validation part of the process. In addition to this, the unpacking
+functions can also check that all items of arrays and objects are
+unpacked. This check be enabled with the format character ``!`` or by
+using the flag ``JSON_STRICT``. See below for details.
Here's the full list of format characters. The type in parentheses
denotes the JSON type, and the type in brackets (if any) denotes the C
``fmt`` may contain objects and arrays as values, i.e. recursive
value extraction is supporetd.
-``*``
- This special format character is used to disable the check that
- all object and array items are accessed on a per-value basis. It
+``!``
+ This special format character is used to enable the check that
+ all object and array items are accessed, on a per-value basis. It
must appear inside an array or object as the last format character
- before the closing bracket or brace.
+ before the closing bracket or brace. To enable the check globally,
+ use the ``JSON_STRICT`` unpacking flag.
+``*``
+ This special format character is the opposite of ``!``. If the
+ ``JSON_STRICT`` flag is used, ``*`` can be used to disable the
+ strict check on a per-value basis. It must appear inside an array
+ or object as the last format character before the closing bracket
+ or brace.
+
+The following functions compose the parsing and validation API:
.. function:: int json_unpack(json_t *root, const char *fmt, ...)
The following unpacking flags are available:
-``JSON_UNPACK_ONLY``
- Disable the validation step checking that all object and array
- items are unpacked. This is equivalent to appending the format
- character ``*`` to the end of every array and object in the format
- string.
+``JSON_STRICT``
+ Enable the extra validation step checking that all object and
+ array items are unpacked. This is equivalent to appending the
+ format character ``!`` to the end of every array and object in the
+ format string.
``JSON_VALIDATE_ONLY``
Don't extract any data, just validate the JSON value against the
/* returns 0 for validation success, nothing is extracted */
/* root is the JSON array [1, 2, 3, 4, 5] */
- int myint1, myint2, ret;
- ret = json_unpack(root, "[ii*]", &myint1, &myint2);
- assert(ret == 0 && myint1 == 1 && myint2 == 2);
+ int myint1, myint2;
+ json_unpack(root, "[ii!]", &myint1, &myint2);
+ /* returns -1 for failed validation */
Equality
.. 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.
projects / jansson.git / blobdiff