9.4. Localization

This is where the program's idea of its current locale can be controlled. The header file <locale.h> declares the setlocale and localeconv functions and a number of macros:

LC_ALL
LC_COLLATE
LC_CTYPE
LC_MONETARY
LC_NUMERIC
LC_TIME

all of which expand to integral constant expressions and are used as values of the category argument to setlocale (other names may also be defined: they will all start with LC_X where X is an upper case letter), and the type

struct lconv

which is used for storing information about the formatting of numeric values. For members of type char, CHAR_MAX is used to indicate that the value is not available in the current locale.

lconv contains at least the following members:

char *decimal_point

The character used for the decimal point in formatted non-monetary values. "." in the C locale.

char *thousands_sep

The character used for separating groups of digits to the left of the decimal point in formatted non-monetary values. "" in the C locale.

char *grouping

Defines the number of digits in each group when formatting non-monetary values. The elements are interpreted as follows: A value of CHAR_MAX indicates that no further grouping is to be performed; 0 indicates that the previous element should be repeated for the remaining digits; if any other character is used, its integer value represents the number of digits that comprise the current group (the next character in the sequence is interpreted before grouping). "" in the C locale. As an example, "\3" specifies that digits should be grouped in threes; the terminating null in the string signifies that the \3 repeats.

char *int_curr_symbol

The first three characters are used to hold the alphabetic international currency symbol for the current locale, the fourth character is used to separate the international currency symbol from the monetary quantity. "" in the C locale.

char *currency_symbol

The currency symbol for the current locale. "" in the C locale.

char *mon_decimal_point

The character used as the decimal point when formatting monetary values. "" in the C locale.

char *mon_thousands_sep

The digit group separator for formatted monetary values. "" in the C locale.

char *mon_grouping

Defines the number of digits in each group when formatting monetary values. Its elements are interpreted as those for grouping. "" in the C locale.

char *positive_sign

The string used to signify a non-negative monetary value. "" in the C locale.

char *negative_sign

The string used to signify a negative monetary value. "" in the C locale.

char int_frac_digits

The number of digits to be displayed after the decimal point in an internationally formatted monetary value. CHAR_MAX in the C locale.

char frac_digits

The number of digits to be displayed after the decimal point in a non-internationally formatted monetary value. CHAR_MAX in the C locale.

char p_cs_precedes

A value of 1 indicates that the currency_symbol should precede the value when formatting a non-negative monetary quantity; a value of 0 indicates that it should follow. CHAR_MAX in the C locale.

char p_sep_by_space

A value of 1 indicates that the currency symbol is separated by a space from the value when formatting a non-negative monetary quantity; 0 indicates no space. CHAR_MAX in the C locale.

char n_cs_precedes

As p_cs_precedes for negative monetary values. CHAR_MAX in the C locale.

char n_sep_by_space

As p_sep_by_space for negative monetary values. CHAR_MAX in the C locale.

char p_sign_posn

Indicates the position of the positive_sign for a non-negative formatted monetary value according to the following:

• parentheses surround quantity and currency_symbol
• the string precedes the quantity and currency_symbol
• the string follows the quantity and currency_symbol
• the string precedes the currency_symbol
• the string follows the currency_symbol

CHAR_MAX in the C locale.

char n_sign_posn

As p_sign_posn for negative monetary values. CHAR_MAX in the C locale.

9.4.1. The setlocale function

#include <locale.h>

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

This function allows the program's idea of its locale to be set. All or parts of the locale can be set by providing values for category as follows:

LC_ALL

Set entire locale.

LC_COLLATE

Modify behaviour of strcoll and strxfrm.

LC_CTYPE

Modify behaviour of character-handling functions.

LC_MONETARY

Modify monetary formatting information returned by localeconv.

LC_NUMERIC

Modify decimal-point character for formatted I/O and string conversion routines.

LC_TIME

Modify behaviour of strftime.

The values for locale can be:

"C"	Select the minimal environment for C translation
""	Select the implementation-defined ‘native environment’
implementation defined	Select other environments

When the program starts, it has an environment as if

setlocale(LC_ALL, "C");

has been executed.

The current string associated with a given category can be queried by passing a null pointer as the value for locale; if the selection can be performed, the string associated with the specified category for the new locale is returned. This string is such that if it is used in a subsequent call to setlocale, along with its associated category, that part of the program's locale will be restored. If the selection cannot be performed, a null pointer is returned and the locale is not changed.

9.4.2. The localeconv function

#include <locale.h>

struct lconv *localeconv(void);

The function returns a pointer to a structure of type struct lconv, set according to the current locale, which may be overwritten by subsequent calls to localeconv or setlocale. The structure must not be modified in any other way.

For example, if in the current locale monetary values should be represented as

then the monetary members of lconv would have the values: