setlocale()

change or query current locale 

Function


SYNOPSIS

#include <locale.h>

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


DESCRIPTION

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

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. The most prevalent example of this is for the LC_MESSAGES category, which is not supported by Windows, and hence is not supported by native Windows commands. The NuTCRACKER Platform supports 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 "C" or "POSIX" 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. To allow NuTCRACKER Platform applications to recognize the UNIX-style locale names, a locale-alias database is provided in the file:

$ROOTDIR/etc/locale/localias.txt

This file consists of mappings from UNIX locale name to Windows locale name, for example:

en_US.iso8859-1	English_United States.1252

which maps the UNIX-standard specification for English as used in the United States to the Windows locale name for the same setting.

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

If the environment variable NUT_UTF8_LOCALE is set, the NuTCRACKER Platform overrides the locale codepage for conversions and forces the UTF-8 encoding to be used instead. UTF-8 mode can also be enabled or disabled using the _NutConf() function.

The return value of setlocale() is not altered when UTF-8 mode is on.


AVAILABILITY

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


SEE ALSO

Functions:
fprintf(), fscanf(), isalnum(), isalpha(), iscntrl(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), iswalnum(), iswalpha(), iswcntrl(), iswgraph(), iswlower(), iswprint(), iswpunct(), iswspace(), iswupper(), localeconv(), mblen(), mbstowcs(), nl_langinfo(), printf(), scanf(), snprintf(), sprintf(), sscanf(), strcoll(), strerror(), strftime(), strtod(), strxfrm(), tolower(), toupper(), towlower(), towupper(), vfprintf(), vfscanf(), vprintf(), vscanf(), vsnprintf(), vsprintf(), vsscanf(), wcscoll(), wcsftime(), wcstod(), wcstombs(), wcsxfrm(), wctomb()


PTC MKS Toolkit 9.6 Documentation Build 9.