diff options
Diffstat (limited to 'manual/locale.texi')
| -rw-r--r-- | manual/locale.texi | 605 |
1 files changed, 605 insertions, 0 deletions
diff --git a/manual/locale.texi b/manual/locale.texi new file mode 100644 index 0000000000..d2d7557ea9 --- /dev/null +++ b/manual/locale.texi @@ -0,0 +1,605 @@ +@node Locales, Searching and Sorting, Extended Characters, Top +@chapter 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. + +@cindex internationalization +@cindex locales +@dfn{Internationalization} of software means programming it to be able +to adapt to the user's favorite conventions. In ANSI C, +internationalization works by means of @dfn{locales}. 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. + +@menu +* Effects of Locale:: Actions affected by the choice of + locale. +* Choosing Locale:: How the user specifies a locale. +* Locale Categories:: Different purposes for which you can + select a locale. +* Setting the Locale:: How a program specifies the locale + with library functions. +* Standard Locales:: Locale names available on all systems. +* Numeric Formatting:: How to format numbers according to the + chosen locale. +@end menu + +@node Effects of Locale, Choosing Locale, , Locales +@section What Effects a Locale Has + +Each locale specifies conventions for several purposes, including the +following: + +@itemize @bullet +@item +What multibyte character sequences are valid, and how they are +interpreted (@pxref{Extended Characters}). + +@item +Classification of which characters in the local character set are +considered alphabetic, and upper- and lower-case conversion conventions +(@pxref{Character Handling}). + +@item +The collating sequence for the local language and character set +(@pxref{Collation Functions}). + +@item +Formatting of numbers and currency amounts (@pxref{Numeric Formatting}). + +@item +Formatting of dates and times (@pxref{Formatting Date and Time}). + +@item +What language to use for output, including error messages. +(The C library doesn't yet help you implement this.) + +@item +What language to use for user answers to yes-or-no questions. + +@item +What language to use for more complex user input. +(The C library doesn't yet help you implement this.) +@end itemize + +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 @code{strcoll} or @code{strxfrm} 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. + +@node Choosing Locale, Locale Categories, Effects of Locale, Locales +@section Choosing a Locale + +The simplest way for the user to choose a locale is to set the +environment variable @code{LANG}. This specifies a single locale to use +for all purposes. For example, a user could specify a hypothetical +locale named @samp{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 @samp{C} or +@samp{POSIX}. + +@cindex combining locales +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 @samp{espana-castellano} +for most purposes, but specify the locale @samp{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 @samp{espana-castellano} and @samp{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. + +@node Locale Categories, Setting the Locale, Choosing Locale, Locales +@section Categories of Activities that Locales Affect +@cindex categories for locales +@cindex locale categories + +The purposes that locales serve are grouped into @dfn{categories}, 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 @code{setlocale}. + +@table @code +@comment locale.h +@comment ANSI +@item LC_COLLATE +@vindex LC_COLLATE +This category applies to collation of strings (functions @code{strcoll} +and @code{strxfrm}); see @ref{Collation Functions}. + +@comment locale.h +@comment ANSI +@item LC_CTYPE +@vindex LC_CTYPE +This category applies to classification and conversion of characters, +and to multibyte and wide characters; +see @ref{Character Handling} and @ref{Extended Characters}. + +@comment locale.h +@comment ANSI +@item LC_MONETARY +@vindex LC_MONETARY +This category applies to formatting monetary values; see @ref{Numeric +Formatting}. + +@comment locale.h +@comment ANSI +@item LC_NUMERIC +@vindex LC_NUMERIC +This category applies to formatting numeric values that are not +monetary; see @ref{Numeric Formatting}. + +@comment locale.h +@comment ANSI +@item LC_TIME +@vindex LC_TIME +This category applies to formatting date and time values; see +@ref{Formatting Date and Time}. + +@ignore This is apparently a feature that was in some early +draft of the POSIX.2 standard, but it's not listed in draft 11. Do we +still support this anyway? Is there a corresponding environment +variable? + +@comment locale.h +@comment GNU +@item LC_RESPONSE +@vindex LC_RESPONSE +This category applies to recognizing ``yes'' or ``no'' responses to +questions. +@end ignore + +@comment locale.h +@comment ANSI +@item LC_ALL +@vindex LC_ALL +This is not an environment variable; it is only a macro that you can use +with @code{setlocale} to set a single locale for all purposes. + +@comment locale.h +@comment ANSI +@item LANG +@vindex LANG +If this environment variable is defined, its value specifies the locale +to use for all purposes except as overridden by the variables above. +@end table + +@node Setting the Locale, Standard Locales, Locale Categories, Locales +@section 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 +ANSI C says that all programs start by default in the standard @samp{C} +locale. To use the locales specified by the environment, you must call +@code{setlocale}. Call it as follows: + +@smallexample +setlocale (LC_ALL, ""); +@end smallexample + +@noindent +to select a locale based on the appropriate environment variables. + +@cindex changing the locale +@cindex locale, changing +You can also use @code{setlocale} to specify a particular locale, for +general use or for a specific category. + +@pindex locale.h +The symbols in this section are defined in the header file @file{locale.h}. + +@comment locale.h +@comment ANSI +@deftypefun {char *} setlocale (int @var{category}, const char *@var{locale}) +The function @code{setlocale} sets the current locale for +category @var{category} to @var{locale}. + +If @var{category} is @code{LC_ALL}, this specifies the locale for all +purposes. The other possible values of @var{category} specify an +individual purpose (@pxref{Locale Categories}). + +You can also use this function to find out the current locale by passing +a null pointer as the @var{locale} argument. In this case, +@code{setlocale} returns a string that is the name of the locale +currently selected for category @var{category}. + +The string returned by @code{setlocale} can be overwritten by subsequent +calls, so you should make a copy of the string (@pxref{Copying and +Concatenation}) if you want to save it past any further calls to +@code{setlocale}. (The standard library is guaranteed never to call +@code{setlocale} itself.) + +You should not modify the string returned by @code{setlocale}. +It might be the same string that was passed as an argument in a +previous call to @code{setlocale}. + +When you read the current locale for category @code{LC_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 @code{LC_ALL} in a subsequent call to +@code{setlocale}, it restores the same combination of locale selections. + +When the @var{locale} argument is not a null pointer, the string returned +by @code{setlocale} reflects the newly modified locale. + +If you specify an empty string for @var{locale}, this means to read the +appropriate environment variable and use its value to select the locale +for @var{category}. + +If you specify an invalid locale name, @code{setlocale} returns a null +pointer and leaves the current locale unchanged. +@end deftypefun + +Here is an example showing how you might use @code{setlocale} to +temporarily switch to a new locale. + +@smallexample +#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; + + /* @r{Get the name of the current locale.} */ + old_locale = setlocale (LC_ALL, NULL); + + /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */ + saved_locale = strdup (old_locale); + if (old_locale == NULL) + fatal ("Out of memory"); + + /* @r{Now change the locale and do some stuff with it.} */ + setlocale (LC_ALL, new_locale); + (*subroutine) (argument); + + /* @r{Restore the original locale.} */ + setlocale (LC_ALL, saved_locale); + free (saved_locale); +@} +@end smallexample + +@strong{Portability Note:} Some ANSI C systems may define additional +locale categories. For portability, assume that any symbol beginning +with @samp{LC_} might be defined in @file{locale.h}. + +@node Standard Locales, Numeric Formatting, Setting the Locale, Locales +@section Standard Locales + +The only locale names you can count on finding on all operating systems +are these three standard ones: + +@table @code +@item "C" +This is the standard C locale. The attributes and behavior it provides +are specified in the ANSI C standard. When your program starts up, it +initially uses this locale by default. + +@item "POSIX" +This is the standard POSIX locale. Currently, it is an alias for the +standard C locale. + +@item "" +The empty name says to select a locale based on environment variables. +@xref{Locale Categories}. +@end table + +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. +@c ??? If we give the GNU system that capability, this place will have +@c ??? to be changed. + +If your program needs to use something other than the @samp{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. + +@node Numeric Formatting, , Standard Locales, Locales +@section 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 +@code{localeconv} to get the data on how to do it. The function +@code{localeconv} is declared in the header file @file{locale.h}. +@pindex locale.h +@cindex monetary value formatting +@cindex numeric value formatting + +@comment locale.h +@comment ANSI +@deftypefun {struct lconv *} localeconv (void) +The @code{localeconv} 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 @code{localeconv}, or by calls to +@code{setlocale}, but no other function in the library overwrites this +value. +@end deftypefun + +@comment locale.h +@comment ANSI +@deftp {Data Type} {struct lconv} +This is the data type of the value returned by @code{localeconv}. +@end deftp + +If a member of the structure @code{struct lconv} has type @code{char}, +and the value is @code{CHAR_MAX}, it means that the current locale has +no value for that parameter. + +@menu +* General Numeric:: Parameters for formatting numbers and + currency amounts. +* Currency Symbol:: How to print the symbol that identifies an + amount of money (e.g. @samp{$}). +* Sign of Money Amount:: How to print the (positive or negative) sign + for a monetary amount, if one exists. +@end menu + +@node General Numeric, Currency Symbol, , Numeric Formatting +@subsection Generic Numeric Formatting Parameters + +These are the standard members of @code{struct lconv}; there may be +others. + +@table @code +@item char *decimal_point +@itemx char *mon_decimal_point +These are the decimal-point separators used in formatting non-monetary +and monetary quantities, respectively. In the @samp{C} locale, the +value of @code{decimal_point} is @code{"."}, and the value of +@code{mon_decimal_point} is @code{""}. +@cindex decimal-point separator + +@item char *thousands_sep +@itemx char *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 @samp{C} locale, both members have a value of +@code{""} (the empty string). + +@item char *grouping +@itemx char *mon_grouping +These are strings that specify how to group the digits to the left of +the decimal point. @code{grouping} applies to non-monetary quantities +and @code{mon_grouping} applies to monetary quantities. Use either +@code{thousands_sep} or @code{mon_thousands_sep} to separate the digit +groups. +@cindex grouping of digits + +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 @code{-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 @code{grouping} is @code{"4;3;2"}, the correct grouping +for the number @code{123456787654321} is @samp{12}, @samp{34}, +@samp{56}, @samp{78}, @samp{765}, @samp{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 @samp{,}, the +number would be printed as @samp{12,34,56,78,765,4321}. + +A value of @code{"3"} indicates repeated groups of three digits, as +normally used in the U.S. + +In the standard @samp{C} locale, both @code{grouping} and +@code{mon_grouping} have a value of @code{""}. This value specifies no +grouping at all. + +@item char int_frac_digits +@itemx char 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 @samp{C} locale, both of these members have the value +@code{CHAR_MAX}, meaning ``unspecified''. The ANSI 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 +@code{mon_decimal_point}, so printing any fractional digits would be +confusing!) +@end table + +@node Currency Symbol, Sign of Money Amount, General Numeric, Numeric Formatting +@subsection Printing the Currency Symbol +@cindex currency symbols + +These members of the @code{struct lconv} structure specify how to print +the symbol to identify a monetary value---the international analog of +@samp{$} for US dollars. + +Each country has two standard currency symbols. The @dfn{local currency +symbol} is used commonly within the country, while the +@dfn{international 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. + +@table @code +@item char *currency_symbol +The local currency symbol for the selected locale. + +In the standard @samp{C} locale, this member has a value of @code{""} +(the empty string), meaning ``unspecified''. The ANSI 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. + +@item char *int_curr_symbol +The international currency symbol for the selected locale. + +The value of @code{int_curr_symbol} should normally consist of a +three-letter abbreviation determined by the international standard +@cite{ISO 4217 Codes for the Representation of Currency and Funds}, +followed by a one-character separator (often a space). + +In the standard @samp{C} locale, this member has a value of @code{""} +(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. + +@item char p_cs_precedes +@itemx char n_cs_precedes +These members are @code{1} if the @code{currency_symbol} string should +precede the value of a monetary amount, or @code{0} if the string should +follow the value. The @code{p_cs_precedes} member applies to positive +amounts (or zero), and the @code{n_cs_precedes} member applies to +negative amounts. + +In the standard @samp{C} locale, both of these members have a value of +@code{CHAR_MAX}, meaning ``unspecified''. The ANSI 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 +@code{int_curr_symbol} as well as the @code{currency_symbol}. The ANSI +C standard seems to imply that they should apply only to the +@code{currency_symbol}---so the @code{int_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 preceed the amount. If we find out a reliable +answer, we will put it here. + +@item char p_sep_by_space +@itemx char n_sep_by_space +These members are @code{1} if a space should appear between the +@code{currency_symbol} string and the amount, or @code{0} if no space +should appear. The @code{p_sep_by_space} member applies to positive +amounts (or zero), and the @code{n_sep_by_space} member applies to +negative amounts. + +In the standard @samp{C} locale, both of these members have a value of +@code{CHAR_MAX}, meaning ``unspecified''. The ANSI 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 @code{currency_symbol}. When you use +@code{int_curr_symbol}, you never print an additional space, because +@code{int_curr_symbol} itself contains the appropriate separator. + +The POSIX standard says that these two members apply to the +@code{int_curr_symbol} as well as the @code{currency_symbol}. But an +example in the ANSI C standard clearly implies that they should apply +only to the @code{currency_symbol}---that the @code{int_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. +@end table + +@node Sign of Money Amount, , Currency Symbol, Numeric Formatting +@subsection Printing the Sign of an Amount of Money + +These members of the @code{struct lconv} structure specify how to print +the sign (if any) in a monetary value. + +@table @code +@item char *positive_sign +@itemx char *negative_sign +These are strings used to indicate positive (or zero) and negative +(respectively) monetary quantities. + +In the standard @samp{C} locale, both of these members have a value of +@code{""} (the empty string), meaning ``unspecified''. + +The ANSI standard doesn't say what to do when you find this value; we +recommend printing @code{positive_sign} as you find it, even if it is +empty. For a negative value, print @code{negative_sign} as you find it +unless both it and @code{positive_sign} are empty, in which case print +@samp{-} instead. (Failing to indicate the sign at all seems rather +unreasonable.) + +@item char p_sign_posn +@itemx char 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 +@code{positive_sign} or @code{negative_sign}.) The possible values are +as follows: + +@table @code +@item 0 +The currency symbol and quantity should be surrounded by parentheses. + +@item 1 +Print the sign string before the quantity and currency symbol. + +@item 2 +Print the sign string after the quantity and currency symbol. + +@item 3 +Print the sign string right before the currency symbol. + +@item 4 +Print the sign string right after the currency symbol. + +@item CHAR_MAX +``Unspecified''. Both members have this value in the standard +@samp{C} locale. +@end table + +The ANSI standard doesn't say what you should do when the value is +@code{CHAR_MAX}. We recommend you print the sign after the currency +symbol. +@end table + +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 ANSI 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. + |