@Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.
Œ

ˆ‰SEC321Št�”›Locales and Internationalization

@�”˜Different countries and cultures have varying conventions for how to communicate. These conventions range from very simple ones, such as the format for representing dates and times, to very complex ones, such as the language spoken.
‰IDX1565Š‰IDX1566ŠB�”˜Internationalization@ of software means programming it to be able to adapt to the user's favorite conventions. In ISO C, internationalization works by means of Blocales@. Each locale specifies a collection of conventions, one convention for each purpose. The user chooses a set of conventions by specifying a locale (via environment variables).
All programs inherit the chosen locale as part of their environment. Provided the programs are written to obey the choice of locale, they will follow the conventions preferred by the user.
ˆ‰SEC322Št�”›What Effects a Locale Has

@�”˜Each locale specifies conventions for several purposes, including the following: þÂ
• What multibyte character sequences are valid, and how they are interpreted (see section ‰ŠP�”›Extended Characters@�”˜).
• Classification of which characters in the local character set are considered alphabetic, and upper- and lower-case conversion conventions (see section ‰ŠP�”›Character Handling@�”˜).
• The collating sequence for the local language and character set (see section ‰ŠP�”›Collation Functions@�”˜).
• Formatting of numbers and currency amounts (see section ‰ŠP�”›Numeric Formatting@�”˜).
• Formatting of dates and times (see section ‰ŠP�”›Formatting Date and Time@�”˜).
• What language to use for output, including error messages. (The C library doesn't yet help you implement this.)
• What language to use for user answers to yes-or-no questions.
• What language to use for more complex user input. (The C library doesn't yet help you implement this.)Àð
Some aspects of adapting to the specified locale are handled automatically by the library subroutines. For example, all your program needs to do in order to use the collating sequence of the chosen locale is to use Hstrcoll@ or Hstrxfrm@ to compare strings.
Other aspects of locales are beyond the comprehension of the library. For example, the library can't automatically translate your program's output messages into other languages. The only way you can support output in the user's favorite language is to program this more or less by hand. (Eventually, we hope to provide facilities to make this easier.)
This chapter discusses the mechanism by which you can modify the current locale. The effects of the current locale on specific library functions are discussed in more detail in the descriptions of those functions.
ˆ‰SEC323Št�”›Choosing a Locale

@�”˜The simplest way for the user to choose a locale is to set the environment variable HLANG@. This specifies a single locale to use for all purposes. For example, a user could specify a hypothetical locale named H`espana-castellano'@ to use the standard conventions of most of Spain.
The set of locales supported depends on the operating system you are using, and so do their names. We can't make any promises about what locales will exist, except for one standard locale called H`C'@ or H`POSIX'@.
‰IDX1567Š@�”˜A user also has the option of specifying different locales for different purposes--in effect, choosing a mixture of multiple locales.
For example, the user might specify the locale H`espana-castellano'@ for most purposes, but specify the locale H`usa-english'@ for currency formatting. This might make sense if the user is a Spanish-speaking American, working in Spanish, but representing monetary amounts in US dollars.
Note that both locales H`espana-castellano'@ and H`usa-english'@, like all locales, would include conventions for all of the purposes to which locales apply. However, the user can choose to use each locale for a particular subset of those purposes.
ˆ‰SEC324Št�”›Categories of Activities that Locales Affect

‰IDX1568Š‰IDX1569Š
@�”˜The purposes that locales serve are grouped into Bcategories@, so that a user or a program can choose the locale for each category independently. Here is a table of categories; each name is both an environment variable that a user can set, and a macro name that you can use as an argument to Hsetlocale@.
HLC_COLLATE
Â‰IDX1570Š@�”˜This category applies to collation of strings (functions Hstrcoll@ and Hstrxfrm@); see section ‰ŠP�”›Collation Functions@�”˜.
ÀHLC_CTYPE
Â‰IDX1571Š@�”˜This category applies to classification and conversion of characters, and to multibyte and wide characters; see section ‰ŠP�”›Character Handling@�”˜ and section ‰ŠP�”›Extended Characters@�”˜.
ÀHLC_MONETARY
Â‰IDX1572Š@�”˜This category applies to formatting monetary values; see section ‰ŠP�”›Numeric Formatting@�”˜.
ÀHLC_NUMERIC
Â‰IDX1573Š@�”˜This category applies to formatting numeric values that are not monetary; see section ‰ŠP�”›Numeric Formatting@�”˜.
ÀHLC_TIME
Â‰IDX1574Š@�”˜This category applies to formatting date and time values; see section ‰ŠP�”›Formatting Date and Time@�”˜.
ÀHLC_MESSAGES
Â‰IDX1575Š@�”˜This category applies to selecting the language used in the user interface for message translation.
ÀHLC_ALL
Â‰IDX1576Š@�”˜This is not an environment variable; it is only a macro that you can use with Hsetlocale@ to set a single locale for all purposes.
ÀHLANG
Â‰IDX1577Š@�”˜If this environment variable is defined, its value specifies the locale to use for all purposes except as overridden by the variables above.À

ˆ‰SEC325Št�”›How Programs Set the Locale

@�”˜A C program inherits its locale environment variables when it starts up. This happens automatically. However, these variables do not automatically control the locale used by the library functions, because ISO C says that all programs start by default in the standard H`C'@ locale. To use the locales specified by the environment, you must call Hsetlocale@. Call it as follows: setlocale (LC_ALL, "");
to select a locale based on the appropriate environment variables.
‰IDX1578Š‰IDX1579Š@�”˜You can also use Hsetlocale@ to specify a particular locale, for general use or for a specific category.
‰IDX1580Š@�”˜The symbols in this section are defined in the header file H`locale.h'@.

AFunction:@ char * Dsetlocale@ B(int Bcategory@, const char *Blocale@)
Â‰IDX1581Š@�”˜The function Hsetlocale@ sets the current locale for category Bcategory@ to Blocale@.
If Bcategory@ is HLC_ALL@, this specifies the locale for all purposes. The other possible values of Bcategory@ specify an individual purpose (see section ‰ŠP�”›Categories of Activities that Locales Affect@�”˜).
You can also use this function to find out the current locale by passing a null pointer as the Blocale@ argument. In this case, Hsetlocale@ returns a string that is the name of the locale currently selected for category Bcategory@.
The string returned by Hsetlocale@ can be overwritten by subsequent calls, so you should make a copy of the string (see section ‰ŠP�”›Copying and Concatenation@�”˜) if you want to save it past any further calls to Hsetlocale@. (The standard library is guaranteed never to call Hsetlocale@ itself.)
You should not modify the string returned by Hsetlocale@. It might be the same string that was passed as an argument in a previous call to Hsetlocale@.
When you read the current locale for category HLC_ALL@, the value encodes the entire combination of selected locales for all categories. In this case, the value is not just a single locale name. In fact, we don't make any promises about what it looks like. But if you specify the same "locale name" with HLC_ALL@ in a subsequent call to Hsetlocale@, it restores the same combination of locale selections.
When the Blocale@ argument is not a null pointer, the string returned by Hsetlocale@ reflects the newly modified locale.
If you specify an empty string for Blocale@, this means to read the appropriate environment variable and use its value to select the locale for Bcategory@.
If you specify an invalid locale name, Hsetlocale@ returns a null pointer and leaves the current locale unchanged.À

Here is an example showing how you might use Hsetlocale@ to temporarily switch to a new locale. #include <stddef.h>
#include <locale.h>
#include <stdlib.h>
#include <string.h>

void
with_other_locale (char *new_locale,
void (*subroutine) (int),
int argument)
{
char *old_locale, *saved_locale;

/* Get the name of the current locale. */
old_locale = setlocale (LC_ALL, NULL);

/* Copy the name so it won't be clobbered by Hsetlocale@. */
saved_locale = strdup (old_locale);
if (old_locale == NULL)
fatal ("Out of memory");

/* Now change the locale and do some stuff with it. */
setlocale (LC_ALL, new_locale);
(*subroutine) (argument);

/* Restore the original locale. */
setlocale (LC_ALL, saved_locale);
free (saved_locale);
}
DPortability Note:@ Some ISO C systems may define additional locale categories. For portability, assume that any symbol beginning with H`LC_'@ might be defined in H`locale.h'@.
ˆ‰SEC326Št�”›Standard Locales

@�”˜The only locale names you can count on finding on all operating systems are these three standard ones:
H"C"
Â@This is the standard C locale. The attributes and behavior it provides are specified in the ISO C standard. When your program starts up, it initially uses this locale by default.
ÀH"POSIX"
Â@This is the standard POSIX locale. Currently, it is an alias for the standard C locale.
ÀH""
Â@The empty name says to select a locale based on environment variables. See section ‰ŠP�”›Categories of Activities that Locales Affect@�”˜.À

Defining and installing named locales is normally a responsibility of the system administrator at your site (or the person who installed the GNU C library). Some systems may allow users to create locales, but we don't discuss that here.
If your program needs to use something other than the H`C'@ locale, it will be more portable if you use whatever locale the user specifies with the environment, rather than trying to specify some non-standard locale explicitly by name. Remember, different machines might have different sets of locales installed.
ˆ‰SEC327Št�”›Numeric Formatting

@�”˜When you want to format a number or a currency amount using the conventions of the current locale, you can use the function Hlocaleconv@ to get the data on how to do it. The function Hlocaleconv@ is declared in the header file H`locale.h'@. ‰IDX1582Š‰IDX1583Š‰IDX1584Š

A�”˜Function:@ struct lconv * Dlocaleconv@ B(void)
Â‰IDX1585Š@�”˜The Hlocaleconv@ function returns a pointer to a structure whose components contain information about how numeric and monetary values should be formatted in the current locale.
You shouldn't modify the structure or its contents. The structure might be overwritten by subsequent calls to Hlocaleconv@, or by calls to Hsetlocale@, but no other function in the library overwrites this value.À

AData Type:@ Dstruct lconv
Â‰IDX1586Š@�”˜This is the data type of the value returned by Hlocaleconv@.À

If a member of the structure Hstruct lconv@ has type Hchar@, and the value is HCHAR_MAX@, it means that the current locale has no value for that parameter.
ˆ‰SEC328ŠT�”›Generic Numeric Formatting Parameters

@�”˜These are the standard members of Hstruct lconv@; there may be others.
Hchar *decimal_point
Â
ÀHchar *mon_decimal_point
Â@These are the decimal-point separators used in formatting non-monetary and monetary quantities, respectively. In the H`C'@ locale, the value of Hdecimal_point@ is H"."@, and the value of Hmon_decimal_point@ is H""@. ‰IDX1587Š
ÀH�”˜char *thousands_sep
Â
ÀHchar *mon_thousands_sep
Â@These are the separators used to delimit groups of digits to the left of the decimal point in formatting non-monetary and monetary quantities, respectively. In the H`C'@ locale, both members have a value of H""@ (the empty string).
ÀHchar *grouping
Â
ÀHchar *mon_grouping
Â@These are strings that specify how to group the digits to the left of the decimal point. Hgrouping@ applies to non-monetary quantities and Hmon_grouping@ applies to monetary quantities. Use either Hthousands_sep@ or Hmon_thousands_sep@ to separate the digit groups. ‰IDX1588Š@�”˜Each string is made up of decimal numbers separated by semicolons. Successive numbers (from left to right) give the sizes of successive groups (from right to left, starting at the decimal point). The last number in the string is used over and over for all the remaining groups. If the last integer is H-1@, it means that there is no more grouping--or, put another way, any remaining digits form one large group without separators. For example, if Hgrouping@ is H"4;3;2"@, the correct grouping for the number H123456787654321@ is H`12'@, H`34'@, H`56'@, H`78'@, H`765'@, H`4321'@. This uses a group of 4 digits at the end, preceded by a group of 3 digits, preceded by groups of 2 digits (as many as needed). With a separator of H`,'@, the number would be printed as H`12,34,56,78,765,4321'@. A value of H"3"@ indicates repeated groups of three digits, as normally used in the U.S. In the standard H`C'@ locale, both Hgrouping@ and Hmon_grouping@ have a value of H""@. This value specifies no grouping at all.
ÀHchar int_frac_digits
Â
ÀHchar frac_digits
Â@These are small integers indicating how many fractional digits (to the right of the decimal point) should be displayed in a monetary value in international and local formats, respectively. (Most often, both members have the same value.) In the standard H`C'@ locale, both of these members have the value HCHAR_MAX@, meaning "unspecified". The ISO standard doesn't say what to do when you find this the value; we recommend printing no fractional digits. (This locale also specifies the empty string for Hmon_decimal_point@, so printing any fractional digits would be confusing!)À

ˆ‰SEC329ŠT�”›Printing the Currency Symbol

‰IDX1589Š
@�”˜These members of the Hstruct lconv@ structure specify how to print the symbol to identify a monetary value--the international analog of H`$'@ for US dollars.
Each country has two standard currency symbols. The Blocal currency symbol@ is used commonly within the country, while the Binternational currency symbol@ is used internationally to refer to that country's currency when it is necessary to indicate the country unambiguously.
For example, many countries use the dollar as their monetary unit, and when dealing with international currencies it's important to specify that one is dealing with (say) Canadian dollars instead of U.S. dollars or Australian dollars. But when the context is known to be Canada, there is no need to make this explicit--dollar amounts are implicitly assumed to be in Canadian dollars.
Hchar *currency_symbol
Â@The local currency symbol for the selected locale. In the standard H`C'@ locale, this member has a value of H""@ (the empty string), meaning "unspecified". The ISO standard doesn't say what to do when you find this value; we recommend you simply print the empty string as you would print any other string found in the appropriate member.
ÀHchar *int_curr_symbol
Â@The international currency symbol for the selected locale. The value of Hint_curr_symbol@ should normally consist of a three-letter abbreviation determined by the international standard BISO 4217 Codes for the Representation of Currency and Funds@, followed by a one-character separator (often a space). In the standard H`C'@ locale, this member has a value of H""@ (the empty string), meaning "unspecified". We recommend you simply print the empty string as you would print any other string found in the appropriate member.
ÀHchar p_cs_precedes
Â
ÀHchar n_cs_precedes
Â@These members are H1@ if the Hcurrency_symbol@ string should precede the value of a monetary amount, or H0@ if the string should follow the value. The Hp_cs_precedes@ member applies to positive amounts (or zero), and the Hn_cs_precedes@ member applies to negative amounts. In the standard H`C'@ locale, both of these members have a value of HCHAR_MAX@, meaning "unspecified". The ISO standard doesn't say what to do when you find this value, but we recommend printing the currency symbol before the amount. That's right for most countries. In other words, treat all nonzero values alike in these members. The POSIX standard says that these two members apply to the Hint_curr_symbol@ as well as the Hcurrency_symbol@. The ISO C standard seems to imply that they should apply only to the Hcurrency_symbol@---so the Hint_curr_symbol@ should always precede the amount. We can only guess which of these (if either) matches the usual conventions for printing international currency symbols. Our guess is that they should always precede the amount. If we find out a reliable answer, we will put it here.
ÀHchar p_sep_by_space
Â
ÀHchar n_sep_by_space
Â@These members are H1@ if a space should appear between the Hcurrency_symbol@ string and the amount, or H0@ if no space should appear. The Hp_sep_by_space@ member applies to positive amounts (or zero), and the Hn_sep_by_space@ member applies to negative amounts. In the standard H`C'@ locale, both of these members have a value of HCHAR_MAX@, meaning "unspecified". The ISO standard doesn't say what you should do when you find this value; we suggest you treat it as one (print a space). In other words, treat all nonzero values alike in these members. These members apply only to Hcurrency_symbol@. When you use Hint_curr_symbol@, you never print an additional space, because Hint_curr_symbol@ itself contains the appropriate separator. The POSIX standard says that these two members apply to the Hint_curr_symbol@ as well as the Hcurrency_symbol@. But an example in the ISO C standard clearly implies that they should apply only to the Hcurrency_symbol@---that the Hint_curr_symbol@ contains any appropriate separator, so you should never print an additional space. Based on what we know now, we recommend you ignore these members when printing international currency symbols, and print no extra space.À

ˆ‰SEC330ŠT�”›Printing the Sign of an Amount of Money

@�”˜These members of the Hstruct lconv@ structure specify how to print the sign (if any) in a monetary value.
Hchar *positive_sign
Â
ÀHchar *negative_sign
Â@These are strings used to indicate positive (or zero) and negative (respectively) monetary quantities. In the standard H`C'@ locale, both of these members have a value of H""@ (the empty string), meaning "unspecified". The ISO standard doesn't say what to do when you find this value; we recommend printing Hpositive_sign@ as you find it, even if it is empty. For a negative value, print Hnegative_sign@ as you find it unless both it and Hpositive_sign@ are empty, in which case print H`-'@ instead. (Failing to indicate the sign at all seems rather unreasonable.)
ÀHchar p_sign_posn
Â
ÀHchar n_sign_posn
Â@These members have values that are small integers indicating how to position the sign for nonnegative and negative monetary quantities, respectively. (The string used by the sign is what was specified with Hpositive_sign@ or Hnegative_sign@.) The possible values are as follows:
H0
Ä@The currency symbol and quantity should be surrounded by parentheses.
ÂH1
Ä@Print the sign string before the quantity and currency symbol.
ÂH2
Ä@Print the sign string after the quantity and currency symbol.
ÂH3
Ä@Print the sign string right before the currency symbol.
ÂH4
Ä@Print the sign string right after the currency symbol.
ÂHCHAR_MAX
Ä@"Unspecified". Both members have this value in the standard H`C'@ locale.Â
The ISO standard doesn't say what you should do when the value is HCHAR_MAX@. We recommend you print the sign after the currency symbol.À

It is not clear whether you should let these members apply to the international currency format or not. POSIX says you should, but intuition plus the examples in the ISO C standard suggest you should not. We hope that someone who knows well the conventions for formatting monetary quantities will tell us what we should recommend.
Œ
Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.