Make real number encoding and decoding work under all locales

[jansson.git] / doc / conformance.rst

diff --git a/doc/conformance.rst b/doc/conformance.rst
index 1cb6f44..3446e26 100644 (file)
--- a/doc/conformance.rst
+++ b/doc/conformance.rst
@@ -1,3 +1,5 @@
+.. _rfc-conformance:
+
 ***************
 RFC Conformance
 ***************
@@ -28,6 +30,12 @@ error::
 
 All other Unicode codepoints U+0001 through U+10FFFF are allowed.
 
+Unicode normalization or any other transformation is never performed
+on any strings (string values or object keys). When checking for
+equivalence of strings or object keys, the comparison is performed
+byte by byte between the original UTF-8 representations of the
+strings.
+
 Numbers
 =======
 
@@ -102,3 +110,25 @@ types, ``long double``, etc. Obviously, shorter types like ``short``,
 are implicitly handled via the ordinary C type coercion rules (subject
 to overflow semantics). Also, no support or hooks are provided for any
 supplemental "bignum" type add-on packages.
+
+
+Locale
+======
+
+Jansson works fine under any locale.
+
+However, if the host program is multithreaded and uses ``setlocale()``
+to switch the locale in one thread while Jansson is currently encoding
+or decoding JSON data in another thread, the result may be wrong or
+the program may even crash.
+
+Jansson uses locale specific functions for certain string conversions
+in the encoder and decoder, and then converts the locale specific
+values to/from the JSON representation. This fails if the locale
+changes between the string conversion and the locale-to-JSON
+conversion. This can only happen in multithreaded programs that use
+``setlocale()``, that switches the locale for all running threads, not
+only the thread that calls ``setlocale()``.
+
+If your program uses ``setlocale()`` as described above, consider
+using the thread-safe ``uselocale()`` instead.