locale.h — Locale settings

The locale.h header file contains declarations for the localdtconv() and localeconv() library functions, which retrieve values from the current locale, and for the setlocale() function, used to query or change locale settings for internationalized applications.

The locale.h file declares the lconv structure. Table 1 below shows the elements of the lconv structure and the defaults for the C locale.

Table 1. Elements of lconv Structure
Element Purpose of Element Default
char *decimal_point Decimal-point character used to format non-monetary quantities. "."
char *thousands_sep Character used to separate groups of digits to the left of the decimal-point character in formatted non-monetary quantities. ""
char *grouping String indicating the size of each group of digits in formatted non-monetary quantities. The value of each character in the string determines the number of digits in a group. A value of CHAR_MAX indicates that there are no further groupings. 0 indicates that the previous element is to be used for the remainder of the digits. ""
char *int_curr_symbol International currency symbol for the current locale. The first three characters contain the alphabetic international currency symbol. The fourth character (usually a space) is the character used to separate the international currency symbol from the monetary quantity. ""
char *currency_symbol Local currency symbol of the current locale. ""
char *mon_decimal_point Decimal-point character used to format monetary quantities. "."
char *mon_thousands_sep Separator for digits in formatted monetary quantities. ""
char *mon_grouping String indicating the size of each group of digits in formatted monetary quantities. The value of each character in the string determines the number of digits in a group. A value of CHAR_MAX indicates that there are no further groupings. 0 indicates that the previous element is to be used for the remainder of the digits. ""
char *positive_sign String indicating the positive sign used in monetary quantities. ""
char *negative_sign String indicating the negative sign used in monetary quantities. ""
char int_frac_digits The number of displayed digits to the right of the decimal place for internationally formatted monetary quantities. UCHAR_MAX
char frac_digits Number of digits to the right of the decimal place in monetary quantities. UCHAR_MAX
char p_cs_precedes Value indicating the placement of the currency symbol in a nonnegative, formatted monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char p_sep_by_space Value indicating the use of white space in a nonnegative, formatted monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char n_cs_precedes Value indicating the placement of the currency symbol in a negative, formatted monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char n_sep_by_space Value indicating the use of white space in a negative, formatted monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char p_sign_posn Value indicating the position of the positive_sign for a nonnegative formatted monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char n_sign_posn Value indicating the position of the negative_sign for a negative formatted monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char *left_parenthesis Negative-valued monetary symbol.
Note: This element is an IBM-specific extension.
 ""
char *right_parenthesis Negative-valued monetary symbol.
Note: This element is an IBM-specific extension.
 ""
char *debit_sign Debit_sign character string.
Note: This element is an IBM-specific extension.
 ""
char *credit_sign Credit_sign character string.
Note: This element is an IBM-specific extension.
 ""
char int_p_cs_precedes For international formatting, value indicating the placement of the currency symbol in a nonnegative, monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char int_n_cs_precedes For international formatting, value indicating the placement of the currency symbol in a negative, monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char int_p_sep_by_space For international formatting, value indicating the use of white space in a nonnegative, monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char int_n_sep_by_space For international formatting, value indicating the use of white space in a negative, monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char int_p_sign_posn For international formatting, value indicating the position of the positive sign for a nonnegative monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
char int_n_sign_posn For international formatting, value indicating the position of the negative sign for a negative monetary quantity. For a list of valid values, see Table 2. UCHAR_MAX
For a list of valid values, see Table 2.
Table 2. Monetary Formatting Values
Element Values
cs_precedes 0 The currency_symbol succeeds the value for the formatted monetary quantity;
1 The currency_symbol precedes the value for the formatted monetary quantity
sep_by_space 0

No space separates the currency_symbol from the formatted monetary quantity;

1

If currency_symbol and sign string are adjacent, a space separates them from the value. Otherwise, the currency symbol and value are separated by a space.
2

If currency_symbol and sign string are adjacent, a space separates them from each other. Otherwise, the sign string and value are separated by a space.
sign_posn 0

Parentheses surround the quantity and currency_symbol;

1

The sign string precedes the quantity and currency_symbol;
2

The sign string succeeds the quantity and currency_symbol;

3

The sign string immediately precedes currency_symbol;
4

The sign string immediately succeeds currency_symbol;
5
Substitute debit_sign or credit_sign for negative_sign or positive_sign, respectively.
Note: This value is an IBM-specific extension.
The locale.h file declares the dtconv structure: 
struct dtconv {
        char *abbrev_month_names[12];   /* Abbreviated month names      */
        char *month_names[12];          /* full month names             */
        char *abbrev_day_names[7];      /* Abbreviated day names        */
        char *day_names[7];             /* full day names               */
        char *date_time_format;         /* date and time format         */
        char *date_format;              /* date format                  */
        char *time_format;              /* time format                  */
        char *am_string;                /* AM string                    */
        char *pm_string;                /* PM string                    */
        char *time_format_ampm;         /* long date format             */
        char *iso_std8601_2000;         /* ISO 8601:2000 std date format*/
};
Note: This structure is an IBM-specific extension.

The locale.h file also contains macro definitions for use with the setlocale() function:

The aspects of a program related to national language or to cultural characteristics (such as time zone, currency symbols, and sorting order of characters) can be customized at run time using different locales, to suit users' requirements at those locales. See the internationalization topic in z/OS XL C/C++ Programming Guide.