From 133e847f8ee42a2bf6da3f4b6a14d98a27c01be8 Mon Sep 17 00:00:00 2001 From: TW Date: Fri, 8 Sep 2017 08:31:51 +0200 Subject: [PATCH] document utf-8 locale requirement for json mode, #2273 (#3009) --- docs/internals/frontends.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst index cfe9730fb..75831c95e 100644 --- a/docs/internals/frontends.rst +++ b/docs/internals/frontends.rst @@ -11,7 +11,23 @@ but does mean that there are no release-to-release guarantees on what you might even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents. Borg does on the other hand provide an API on a command-line level. In other words, a frontend should to -(for example) create a backup archive just invoke :ref:`borg_create`. +(for example) create a backup archive just invoke :ref:`borg_create`, give commandline parameters/options +as needed and parse JSON output from borg. + +Important: JSON output is expected to be UTF-8, but currently borg depends on the locale being configured +for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8. +The same applies to any inputs read by borg, they are expected to be UTF-8 encoded also. + +We consider this a bug (see :issue:`2273`) and might fix it later, so borg will use UTF-8 independent of +the locale. + +On POSIX systems, you can usually set environment vars to choose a UTF-8 locale: + +:: + + export LANG=en_US.UTF-8 + export LC_CTYPE=en_US.UTF-8 + Logging -------