setlocale() -- change or query current locale

SYNOPSIS

#include <locale.h>

char *setlocale(int category, const char *locale);

The setlocale() function selects the appropriate piece of the program's locale, as specified by the specified category and locale name, and may be used to change or query the program's entire locale or portions thereof. The category value LC_ALL names the program's entire locale; other category values name only a part of the program's locale, as follows:

LC_COLLATE: affects the behavior of regular expressions and the collation functions.
LC_CTYPE: affects the behavior of regular expressions, character classification, and wide character functions.
LC_MESSAGES: affects what strings are expected by commands and utilities as affirmative or negative responses, what strings are given by commands and utilities as affirmative or negative responses, and the content of messages.
LC_MONETARY: affects the behavior of functions that handle monetary values.
LC_NUMERIC: affects the radix character for the formatted input/output functions and the string conversion functions.
LC_TIME: affects the behavior of time conversion functions.

If the locale name is a NULL pointer, the current locale setting is being queried. Otherwise, the specified locale name should be in the following format:

language[_territory][.codeset]

The territory field is usually a country name. In addition to the above format, the following special locale names are recognized:

"POSIX"

Specifies a minimal environment for C-language translation called POSIX locale. If setlocale() is not invoked by the program, the program behaves as if setlocale() had been invoked with this locale name.

"C"

Same as "POSIX".

""

Specifies that the locale name is determined by querying the process's environment for the following variables, in this order:

LC_ALL: If set to a non-empty string, specifies the locale name to be used for all categories.
LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME: If set to a non-empty string, and LC_ALL is not set, specifies the locale name to be used when setlocale() is invoked for the corresponding category.
LANG: If set to a non-empty string, and neither LC_ALL nor the category-specific environment variable is set, specifies the locale name to be used.

If none of these environment variables is set to a non-empty string, the user's currently-configured system Regional Settings as the locale.

The locale state is common to all threads within a process.

PARAMETERS

category: Indicates the locale settings to query or change. It can be one of the values listed in the DESCRIPTION section.
locale: Points to a string indicating country and language to choose for the locale. A null pointer for locale returns the current value used for the given category.

RETURN VALUES

If successful, a pointer to the string for the locale associated with the given category is returned. On failure, a NULL is returned.

The string returned is such that a subsequent call with the same category value and this string as the locale setting with restore that part of the program's locale. The string returned must not be modified by the program, but may be overwritten by a subsequent call to setlocale().

CONFORMANCE

UNIX 98, with exceptions

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

Before setlocale() is called, the NuTCRACKER Platform defaults a "C" locale.

NuTCRACKER Platform locale information is built from the native Windows locale databases. As such, the NuTCRACKER Platform cannot support more locale information that is provided by Windows. LC_MESSAGES is read from "yes/no" strings in the Windows language files if they are installed. It also has the ability to read UNIX locale files from disk. However the tools needed to produce these files and a sample set of files are not delivered as of this release. The NuTCRACKER Platform allows setting and querying the LC_MESSAGES category, and supports its use in the NLSPATH environment variable used by catopen(). This enables NuTCRACKER Platform applications to localize the message usage.

In addition, if the locale is set to an empty string, and none of the environment variables defined above are specified, the NuTCRACKER Platform uses the system-configured Regional Settings to define the locale. On most UNIX platforms, the locale settings would default to the reading from /etc/locale

Windows locale names and UNIX locale names are usually quite different. Windows uses full language and country names, with code page values for the codeset. UNIX systems usually use two-letter abbreviations for language and country names (from ISO specifications 639 and 3166, respectively), and ISO codeset names. NuTCRACKER Platform accepts both forms without the need to use $ROOTDIR/etc/locale/locale.alias.

For example setlocale() (and newlocale()) will accept both

en_US.iso8859-1

and

English_United States.1252

and UNIX long format

en_US.ISO8859-1/C/fr_FR.UTF-8/ja_JP.sjis/ru_RU.ISO8859-5/C

and the Windows long format

LC_COLLATE=English_United States.1252;LC_CTYPE=C;LC_MONETARY=French_France.65001;LC_NUMERIC=Japanese_Japan.932;LC_TIME=Russian_Russia.1251;LC_MESSAGES=C

Previous versions of NuTCRACKER Platform used a $ROOTDIR/etc/locale/locali.txt file for these now automatic mappings.

NuTCRACKER Platform reads $ROOTDIR/etc/locale/locale.alias, and provides a default to suppliment and enhance the default Windows to UNIX mappings. applications to recognize the UNIX-style locale names, a locale-alias database is provided in the file:

$ROOTDIR/etc/locale/locale.alias

This file consists of mappings that allow alternative names for either the Windows or UNIX locale names.

The values returned by setlocale() are always in canonical UNIX format.

printf("%s\n", setlocale(LC_ALL, "en_US.ISO8859-1")) displays "en_US.ISO8859-1"

while

printf("%s\n", setlocale(LC_ALL, "en_US.ISO8859-1/C/fr_FR.UTF-8/ja_JP.sjis/ru_RU.ISO8859-5/C")) displays "en_US.ISO8859-1/C/fr_FR.UTF-8/ja_JP.sjis/ru_RU.ISO8859-5/C"

and the function output may be set for backward compatibility

_NutConf(_NC_SET_LOCALE_FORMAT, 1);
printf("%s\n", setlocale(LC_ALL, "en_US.ISO8859-1/C/fr_FR.UTF-8/ja_JP.sjis/ru_RU.ISO8859-5/C")) displays "LC_COLLATE=English_United States.1252;LC_CTYPE=C;LC_MONETARY=French_France.65001;LC_NUMERIC=Japanese_Japan.932;LC_TIME=Russian_Russia.1251;LC_MESSAGES=C"

Calling

setlocale(LC_ALL, NULL);

is the same as calling

querylocale(LC_GLOBAL_LOCALE, LC_ALL);

Previous versions of NuTCRACKER Platform used the environment variable NUT_UTF8_LOCALE to indicate to override the console code page for console writes. This environement variable is no longer interrogated as a locale like en_US.UTF-8 (note the dash in UTF-8) do the same thing. In fact the charset part of the locale name is used to convert multi-byte to Unicode for console display.

The environment variable NUT_USE_WINDOWS_LOCALE_FORMAT causes the NuTCRACKER Platform to call _NutConf(_NC_SET_LOCALE_FORMAT, 1) during startup and so affects the return value from setlocale() to be the same as previous versions. The environment variable NUT_USE_UNIX_LOCALE_FORMAT causes the NuTCRACKER Platform to call _NutConf(_NC_SET_LOCALE_FORMAT, 0) during startup and so affects the return value from setlocale() to be in UNIX format.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

setlocale()
change or query current locale

Function