You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by sw...@apache.org on 2023/08/16 02:08:16 UTC
[logging-log4cxx] branch master updated: Update the Unicode support FAQ documentation (#256)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new d4822588 Update the Unicode support FAQ documentation (#256)
d4822588 is described below
commit d4822588edba569e7cb7ebd02596c98b008190ab
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Wed Aug 16 12:08:10 2023 +1000
Update the Unicode support FAQ documentation (#256)
* Clarify when ConsoleAppender uses locale
* Document ConsoleAppender behaviour
* Silence SonarCloud
---
src/main/cpp/charsetdecoder.cpp | 2 +-
src/main/include/log4cxx/consoleappender.h | 10 +++++--
src/main/include/log4cxx/net/telnetappender.h | 10 +++++++
src/site/markdown/faq.md | 43 ++++++++++++++++-----------
4 files changed, 44 insertions(+), 21 deletions(-)
diff --git a/src/main/cpp/charsetdecoder.cpp b/src/main/cpp/charsetdecoder.cpp
index b3c8539b..3ee18a6f 100644
--- a/src/main/cpp/charsetdecoder.cpp
+++ b/src/main/cpp/charsetdecoder.cpp
@@ -450,7 +450,7 @@ class LocaleCharsetDecoder : public CharsetDecoder
// Decode characters that may be represented by multiple bytes
while (0 < remain)
{
- wchar_t ch;
+ wchar_t ch = 0;
size_t n = std::mbrtowc(&ch, p, remain, &this->state);
if (0 == n) // NULL encountered?
{
diff --git a/src/main/include/log4cxx/consoleappender.h b/src/main/include/log4cxx/consoleappender.h
index f7fd4454..9b89a5db 100644
--- a/src/main/include/log4cxx/consoleappender.h
+++ b/src/main/include/log4cxx/consoleappender.h
@@ -25,8 +25,14 @@ namespace log4cxx
/**
* ConsoleAppender appends log events to <code>stdout</code> or
-* <code>stderr</code> using a layout specified by the user. The
-* default target is <code>stdout</code>.
+* <code>stderr</code> using a layout specified by the user.
+*
+* The default target is <code>stdout</code>.
+*
+* You can use <a href="https://en.cppreference.com/w/c/io/fwide">fwide(stdout, 1)</a> in your configuration code
+* or use the cmake directive `LOG4CXX_FORCE_WIDE_CONSOLE=ON` when building Log4cxx
+* to force Log4cxx to use <a href="https://en.cppreference.com/w/c/io/fputws">fputws</a>.
+* If doing this ensure the cmake directive `LOG4CXX_WCHAR_T` is also enabled.
*/
class LOG4CXX_EXPORT ConsoleAppender : public WriterAppender
{
diff --git a/src/main/include/log4cxx/net/telnetappender.h b/src/main/include/log4cxx/net/telnetappender.h
index 504c65c6..aea75da2 100644
--- a/src/main/include/log4cxx/net/telnetappender.h
+++ b/src/main/include/log4cxx/net/telnetappender.h
@@ -87,7 +87,17 @@ class LOG4CXX_EXPORT TelnetAppender : public AppenderSkeleton
return true;
}
+ /**
+ The current encoding value.
+
+ \sa setOption
+ */
LogString getEncoding() const;
+ /**
+ Set the encoding to \c value.
+
+ \sa setOption
+ */
void setEncoding(const LogString& value);
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index b23ce38a..0ce87d63 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -47,14 +47,32 @@ DLL" with release builds of Log4cxx and "Multithread DLL Debug" with debug build
Yes. Apache Log4cxx exposes API methods in multiple string flavors supporting differently encoded
textual content, like `char*`, `std::string`, `wchar_t*`, `std::wstring`, `CFStringRef` et al. All
provided texts will be converted to the `LogString` type before further processing, which is one of
-several supported Unicode representations selected by the `LOG4CXX_CHAR` cmake option. If methods are
+several supported internal representations and is selected by the `LOG4CXX_CHAR` cmake option. If methods are
used that take `LogString` as arguments, the macro `LOG4CXX_STR()` can be used to convert literals
-to the current `LogString` type. FileAppenders support an encoding property as well, which should be
-explicitly specified to `UTF-8` or `UTF-16` for e.g. XML files. The important point is to get the
-chain of input, internal processing and output correct and that might need some additional setup in
-the app using Log4cxx:
+to the current `LogString` type.
-According to the [libc documentation](https://www.gnu.org/software/libc/manual/html_node/Setting-the-Locale.html),
+The default external representation is controlled by the `LOG4CXX_CHARSET` cmake option.
+This default is used to encode a multi-byte characters
+unless an `Encoding` property is explicitly configured
+for the log4cxx::FileAppender specialization you use.
+Note you should use `UTF-8` or `UTF-16` encoding when writing XML or JSON layouts.
+Log4cxx also implements character set encodings for `US-ASCII` (`ISO646-US` or `ANSI_X3.4-1968`)
+and `ISO-8859-1` (`ISO-LATIN-1` or `CP1252`).
+You are highly encouraged to stick to `UTF-8` for the best support from tools and operating systems.
+
+The `locale` character set encoding provides support beyond the above internally implemented options.
+It allows you to use any multi-byte encoding provided by the standard library.
+If using the `locale` character set encoding or
+you use `fwide` to make `stdout` or `stderr` wide-oriented (log4cxx::ConsoleAppender then uses `fputws`)
+you will need to explicitly configure the system locale at startup,
+for example by using:
+
+```
+std::setlocale( LC_ALL, "" ); /* Set user-preferred locale for C functions */
+std::locale::global(std::locale("")); /* Set user-preferred locale for C++ functions */
+```
+
+This is necessary because, according to the [libc documentation](https://www.gnu.org/software/libc/manual/html_node/Setting-the-Locale.html),
all programs start in the `C` locale by default, which is the [same as ANSI_X3.4-1968](https://stackoverflow.com/questions/48743106/whats-ansi-x3-4-1968-encoding)
and what's commonly known as the encoding `US-ASCII`. That encoding supports a very limited set of
characters only, so inputting Unicode with that encoding in effect to output characters can't work
@@ -70,15 +88,4 @@ loggername - ?????????? ???? ??????????????
```
The important thing to understand is that this is some always applied, backwards compatible default
-behaviour and even the case when the current environment sets a locale like `en_US.UTF-8`. One might
-need to explicitly tell the app at startup to use the locale of the environment and make things
-compatible with Unicode this way. See also [some SO post](https://stackoverflow.com/questions/571359/how-do-i-set-the-proper-initial-locale-for-a-c-program-on-windows)
-on setting the default locale in C++.
-
-```
-std::setlocale( LC_ALL, "" ); /* Set locale for C functions */
-std::locale::global(std::locale("")); /* set locale for C++ functions */
-```
-
-See [LOGCXX-483](https://issues.apache.org/jira/browse/LOGCXX-483) or [GHPR #31](https://github.com/apache/logging-log4cxx/pull/31#issuecomment-668870727)
-for additional details.
+behaviour and even the case when the current environment sets a locale like `en_US.UTF-8`.