setlocale
=========

POSIX specification:
 https://pubs.opengroup.org/onlinepubs/9699919799/functions/setlocale.html

Gnulib module: setlocale, setlocale-null

Portability problems fixed by Gnulib module setlocale:

  * On Windows platforms (excluding Cygwin), setlocale(CATEGORY,NULL) ignores the environment variables LC_ALL, CATEGORY, and LANG.

  * On Windows platforms (excluding Cygwin) and Cygwin 1.5.x, setlocale(LC_ALL,NAME) succeeds and sets the LC_CTYPE category to C when it does not support the encoding, instead of failing.

  * On Windows platforms (excluding Cygwin), setlocale understands different locale names, that are not based on ISO 639 language names and ISO 3166 country names.

  * On Android < 5.0, which doesn't have locales, the setlocale function always fails.  The replacement, however, supports only the locale names "C" and "POSIX".

Portability problems fixed by Gnulib module setlocale or setlocale-null:

  * Invocations of setlocale (..., NULL) are not multithread-safe on some platforms: musl libc, macOS, FreeBSD, NetBSD, OpenBSD, AIX, Haiku, Cygwin. To make these invocations multithread-safe, you need the Gnulib module setlocale, or you need to change the code to invoke setlocale_null or setlocale_null_r instead.

Portability problems not fixed by Gnulib:

  * On Cygwin 1.5.x, which doesn't have locales, setlocale(LC_ALL,NULL) always returns "C".

  * On Cygwin 1.7.0, only the charset portion of a locale designation is honored.

  * On OpenBSD, setlocale(LC_ALL,"") will only update categories that are deemed appropriate for the LC_ALL environment value, even if there are other categories set to different values in the environment. In addition any value is accepted for LC_CTYPE, and so NULL is never returned to indicate a failure to set locale. To verify category values, each category must be set individually with setlocale(LC_COLLATE,"") etc.

  * On Android 5.0 and newer, the default locale (i.e. the locale in use when setlocale was not called) is the "C.UTF-8" locale, not the "C" locale.  Additionally, a setlocale call that is meant to set the "C" or "POSIX" locale actually sets an equivalent of the "C.UTF-8" locale.