<locale.h>

Include the standard header <locale.h> to alter or access properties of the current locale -- a collection of culture-specific information. An implementation can define additional macros in this standard header with names that begin with LC_. You can use any of these macro names as the locale category argument (which selects a cohesive subset of a locale) to setlocale.

#define LC_ALL <integer constant expression>
#define LC_COLLATE <integer constant expression>
#define LC_CTYPE <integer constant expression>
#define LC_MONETARY <integer constant expression>
#define LC_NUMERIC <integer constant expression>
#define LC_TIME <integer constant expression>
#define NULL <either 0, 0L, or (void *)0> [0 in C++]

struct lconv;

struct lconv *localeconv(void);
char *setlocale(int category, const char *locname);

LC_ALL

#define LC_ALL <integer constant expression>

The macro yields the locale category argument value that affects all locale categories.

LC_COLLATE

#define LC_COLLATE <integer constant expression>

The macro yields the locale category argument value that affects the collation functions strcoll and strxfrm.

LC_CTYPE

#define LC_CTYPE <integer constant expression>

The macro yields the locale category argument value that affects character classification functions, wide-character classification functions, and various multibyte conversion functions.

LC_MONETARY

#define LC_MONETARY <integer constant expression>

The macro yields the locale category argument value that affects monetary information returned by localeconv.

LC_NUMERIC

#define LC_NUMERIC <integer constant expression>

The macro yields the locale category argument value that affects numeric information returned by localeconv, including the decimal point used by numeric conversion, read, and write functions.

LC_TIME

#define LC_TIME <integer constant expression>

The macro yields the locale category argument value that affects the time conversion function strftime.

lconv

struct lconv {
    ELEMENT                   "C" LOCALE   LOCALE CATEGORY
    char *decimal_point;      "."          LC_NUMERIC
    char *grouping;           ""           LC_NUMERIC
    char *thousands_sep;      ""           LC_NUMERIC

    char *mon_decimal_point;  ""           LC_MONETARY
    char *mon_grouping;       ""           LC_MONETARY
    char *mon_thousands_sep;  ""           LC_MONETARY

    char *negative_sign;      ""           LC_MONETARY
    char *positive_sign;      ""           LC_MONETARY

    char *currency_symbol;    ""           LC_MONETARY
    char frac_digits;         CHAR_MAX     LC_MONETARY
    char n_cs_precedes;       CHAR_MAX     LC_MONETARY
    char n_sep_by_space;      CHAR_MAX     LC_MONETARY
    char n_sign_posn;         CHAR_MAX     LC_MONETARY
    char p_cs_precedes;       CHAR_MAX     LC_MONETARY
    char p_sep_by_space;      CHAR_MAX     LC_MONETARY
    char p_sign_posn;         CHAR_MAX     LC_MONETARY

    char *int_curr_symbol;    ""           LC_MONETARY
    char int_frac_digits;     CHAR_MAX     LC_MONETARY
    char int_n_cs_precedes;   CHAR_MAX     LC_MONETARY
    char int_n_sep_by_space;  CHAR_MAX     LC_MONETARY
    char int_n_sign_posn;     CHAR_MAX     LC_MONETARY
    char int_p_cs_precedes;   CHAR_MAX     LC_MONETARY
    char int_p_sep_by_space;  CHAR_MAX     LC_MONETARY
    char int_p_sign_posn;     CHAR_MAX     LC_MONETARY
    };

struct lconv contains members that describe how to format numeric and monetary values. Functions in the Standard C library use only the field decimal_point. The information is otherwise advisory:

• Members of type pointer to char all designate C strings.
• Members of type char have nonnegative values.
• A char value of CHAR_MAX indicates that a meaningful value is not available in the current locale.

The members shown above can occur in arbitrary order and can be interspersed with additional members. The comment following each member shows its value for the "C" locale, the locale in effect at program startup, followed by the locale category that can affect its value.

A description of each member follows, with an example in parentheses that would be suitable for a USA locale.

currency_symbol -- the local currency symbol ("$")

decimal_point -- the decimal point for non-monetary values (".")

grouping -- the sizes of digit groups for non-monetary values. Successive elements of the string describe groups going away from the decimal point:

• An element value of zero (the terminating null character) calls for the previous element value to be repeated indefinitely.
• An element value of CHAR_MAX ends any further grouping (and hence ends the string).

Thus, the array {3, 2, CHAR_MAX} calls for a group of three digits, then two, then whatever remains, as in 9876,54,321, while "\3" calls for repeated groups of three digits, as in 987,654,321. ("\3")

int_curr_symbol -- the international currency symbol specified by ISO 4217 ("USD ")

mon_decimal_point -- the decimal point for monetary values (".")

mon_grouping -- the sizes of digit groups for monetary values. Successive elements of the string describe groups going away from the decimal point. The encoding is the same as for grouping.

mon_thousands_sep -- the separator for digit groups to the left of the decimal point for monetary values (",")

negative_sign -- the negative sign for monetary values ("-")

positive_sign -- the positive sign for monetary values ("+")

thousands_sep -- the separator for digit groups to the left of the decimal point for non-monetary values (",")

frac_digits -- the number of digits to display to the right of the decimal point for monetary values (2)

int_frac_digits -- the number of digits to display to the right of the decimal point for international monetary values (2)

int_n_cs_precedes -- whether the international currency symbol precedes or follows the value for negative monetary values:

• A value of 0 indicates that the symbol follows the value.
• A value of 1 indicates that the symbol precedes the value. (1)

int_n_sep_by_space -- whether the international currency symbol is separated by a space (defined by int_curr_symbol[3]) or by no space from the value for negative monetary values:

• A value of 0 indicates that no space separates symbol and value.
• A value of 1 indicates that a space separates symbol and value. (0)

int_n_sign_posn -- the format for negative international monetary values:

• A value of 0 indicates that parentheses surround the value and the currency symbol.
• A value of 1 indicates that the negative sign precedes the value and the currency symbol.
• A value of 2 indicates that the negative sign follows the value and the currency_symbol.
• A value of 3 indicates that the negative sign immediately precedes the currency symbol.
• A value of 4 indicates that the negative sign immediately follows the currency_symbol. (4)

int_p_cs_precedes -- whether the international currency symbol precedes or follows the value for positive monetary values:

• A value of 0 indicates that the symbol follows the value.
• A value of 1 indicates that the symbol precedes the value. (1)

int_p_sep_by_space -- whether the international currency symbol is separated by a space (defined by int_curr_symbol[3]) or by no space from the value for positive monetary values:

• A value of 0 indicates that no space separates symbol and value.
• A value of 1 indicates that a space separates symbol and value. (0)

int_p_sign_posn -- the format for positive international monetary values:

• A value of 0 indicates that parentheses surround the value and the currency symbol.
• A value of 1 indicates that the negative sign precedes the value and the currency symbol.
• A value of 2 indicates that the negative sign follows the value and the currency symbol.
• A value of 3 indicates that the negative sign immediately precedes the currency symbol.
• A value of 4 indicates that the negative sign immediately follows the currency symbol. (4)

n_cs_precedes -- whether the currency symbol precedes or follows the value for negative monetary values:

• A value of 0 indicates that the symbol follows the value.
• A value of 1 indicates that the symbol precedes the value. (1)

n_sep_by_space -- whether the currency symbol is separated by a space or by no space from the value for negative monetary values:

• A value of 0 indicates that no space separates symbol and value.
• A value of 1 indicates that a space separates symbol and value. (0)

n_sign_posn -- the format for negative monetary values:

• A value of 0 indicates that parentheses surround the value and the currency symbol.
• A value of 1 indicates that the negative sign precedes the value and the currency symbol.
• A value of 2 indicates that the negative sign follows the value and the currency_symbol.
• A value of 3 indicates that the negative sign immediately precedes the currency symbol.
• A value of 4 indicates that the negative sign immediately follows the currency_symbol. (4)

p_cs_precedes -- whether the currency symbol precedes or follows the value for positive monetary values:

• A value of 0 indicates that the symbol follows the value.
• A value of 1 indicates that the symbol precedes the value. (1)

p_sep_by_space -- whether the currency symbol is separated by a space or by no space from the value for positive monetary values:

• A value of 0 indicates that no space separates symbol and value.
• A value of 1 indicates that a space separates symbol and value. (0)

p_sign_posn -- the format for positive monetary values:

• A value of 0 indicates that parentheses surround the value and the currency symbol.
• A value of 1 indicates that the negative sign precedes the value and the currency symbol.
• A value of 2 indicates that the negative sign follows the value and the currency symbol.
• A value of 3 indicates that the negative sign immediately precedes the currency symbol.
• A value of 4 indicates that the negative sign immediately follows the currency symbol. (4)

localeconv

struct lconv *localeconv(void);

The function returns a pointer to a static-duration structure containing numeric formatting information for the current locale. You cannot alter values stored in the static-duration structure. The stored values can change on later calls to localeconv or on calls to setlocale that alter any of the categories LC_ALL, LC_MONETARY, or LC_NUMERIC.

NULL

#define NULL <either 0, 0L, or (void *)0> [0 in C++]

The macro yields a null pointer constant that is usable as an address constant expression.

setlocale

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

The function either returns a pointer to a static-duration string describing a new locale or returns a null pointer (if the new locale cannot be selected). The value of category selects one or more locale categories, each of which must match the value of one of the macros defined in this standard header with names that begin with LC_.

If locname is a null pointer, the locale remains unchanged. If locname designates the string "C", the new locale is the "C" locale for the locale category specified. If locname designates the string "", the new locale is the native locale (a default locale presumably tailored for the local culture) for the locale category specified. locname can also designate a string returned on an earlier call to setlocale or to other strings that the implementation can define.

At program startup, the target environment calls setlocale( LC_ALL, "C") before it calls main.

See also the Table of Contents and the Index.

Copyright © 1989-2002 by P.J. Plauger and Jim Brodie. All rights reserved.