setlocale - Set/query locale

Definition

#include <locale.h> char *setlocale(int category, const char *locale); With setlocale you can query the current locale or select a new locale. The locale may relate to some or all the locale variables of the program. The locale variables are defined in <locale.h>.

Parameters  int category

Category of locale variables to which the selected locale is to refer. category may contain the following predefined values:

LC_ALL LC_COLLATE	Locale variables of all categories. The sorting sequence affects the behavior of the strcoll and strxfrm functions.
LC_CTYPE	The character type affects the behavior of the macros for character processing is... (not isdigit or isxdigit), tolower, toupper, strlower and strupper.
LC_MONETARY	The conventions for representing monetary values affect the values returned by localeconv.
LC_NUMERIC	The conventions for representing non-monetary numerical values affect the type of decimal point for formatted input/output and for converting strings (atof, strtod), and the values returned by localeconv.
LC_TIME	The conventions for representing date and time affect the behavior of strftime.

Definition

#include <locale.h>

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

With setlocale you can query the current locale or select a new locale. The locale may relate to some or all the locale variables of the program.
The locale variables are defined in <locale.h>.

Parameters

int category

Category of locale variables to which the selected locale is to refer. category may contain the following predefined values:

LC_ALL	Locale variables of all categories.
LC_COLLATE	The sorting sequence affects the behavior of the strcoll and strxfrm functions.
LC_CTYPE	The character type affects the behavior of the macros for character processing is... (not isdigit or isxdigit), tolower, toupper, strlower and strupper.
LC_MONETARY	The conventions for representing monetary values affect the values returned by localeconv.
LC_NUMERIC	The conventions for representing non-monetary numerical values affect the type of decimal point for formatted input/output and for converting strings (atof, strtod), and the values returned by localeconv.
LC_TIME	The conventions for representing date and time affect the behavior of strftime.

const char *locale

String which selects the locale. The following predefined locales are available (a detailed description is provided in section “Predefined locale C”):

"C"	Defines the minimum environment for compiling a C program and is the default setting when the program starts (exception: see locale "V1CTYPE").
""	Standard locale. In this version it corresponds to locale “C”.
"V1CTYPE"	Locale compatible with the C runtime system C1.0. "V1CTYPE" is automatically set when the program starts if the main routine is a C V1.0 object.
"V2CTYPE"	Locale compatible with C runtime systems V2.0 and V2.1.
"GERMANY"	Country-specific locale that conforms to the national conventions.
"De.EDF04F"	Country-specific locale whose conversion tables are based on ASCII code ISO 8859-15 or EBCDIC code EDF04F, and which supports the currency “DM” in the category LC_MONETARY.
"De.EDF04F@euro"	Country-specific locale whose conversion tables are based on ASCII code ISO 8859-15 or EBCDIC code EDF04F, and which supports the currency “euro” in the category LC_MONETARY.

The strings are predefined in the include file <locale.h> as follows:

LC_C_C	"C"
LC_C_DEFAULT	""
LC_C_V1CTYPE	"V1CTYPE"
LC_C_V2CTYPE	"V2CTYPE"
LC_C_GERMANY	"GERMANY"
LC_C_De.EDF04F	"De.EDF04F"
LC_C_De.EDF04F@euro	"De.EDF04F@euro"

If a NULL pointer is passed for locale, the current locale for category is not changed.

Return val.

Pointer to a string specifying the current locale for the specified category.

This string can be used as the locale parameter in setlocale calls. The string can assume the following values:
“C”, “V1CTYPE”, “V2CTYPE”, “GERMANY”, “De.EDF04F”, “De.EDF04F@euro”.
For the LC_ALL category, the string contains the value “C”, provided this value has been set for all categories.
As soon as a locale other than “C” is set for a category, the string contains the locales for all the categories. The values for the individual categories are prefixed by a slash (/), which indicates the beginning of a new value. The sequence of locales corresponds to the above-mentioned sequence of categories (see parameter description int category).
The last (sixth) locale in the string refers to the LC_MESSAGES category which is currently not supported in the locales “C”, “GERMANY”, “VC1TYPE” and “VC2TYPE” and is set to “C” if you enter one of these locales.
If you enter the locale “De.EDF04F” or “De.EDF04F@euro” here, the corresponding value is entered in the category LC_MESSAGES.

If a string containing the locales for all categories is used as the locale parameter in a setlocale call and a category other than LC_ALL is specified, only the locale for the specified category is taken from this string (without the leading slash).

Example of the return value for LC_ALL:

"/V2CTYPE/C/GERMANY/C/GERMANY/C"

    1     2    3    4    5    6

Position	Category	Locale
1	LC_COLLATE	V2CTYPE
2	LC_CTYPE	C
3	LC_MONATARY	GERMANY
4	LC_NUMERIC	C
5	LC_TIME	GERMANY
6	LC_MESSAGES	C

NULL pointer

if the selected category cannot be recognized. The current locale remains unchanged.

Notes

The available locales are described in detail in chapter “Locale”.

User-specific locales:
In addition to the predefined locales mentioned above, you may implement your own locales and select them with setlocale (see section “User-specific locales”).

The string to which the return value of setlocale points must not be explicitly changed by the program. It may only be overwritten by setlocale calls.

If you are only querying the current locale and not changing it, a NULL pointer must be passed for locale.

See also

localeconv