update from main archive 961207
[kopensolaris-gnu/glibc.git] / manual / locale.texi
1 @node Locales, Searching and Sorting, Extended Characters, Top
2 @chapter Locales and Internationalization
3
4 Different countries and cultures have varying conventions for how to
5 communicate.  These conventions range from very simple ones, such as the
6 format for representing dates and times, to very complex ones, such as
7 the language spoken.
8
9 @cindex internationalization
10 @cindex locales
11 @dfn{Internationalization} of software means programming it to be able
12 to adapt to the user's favorite conventions.  In @w{ISO C},
13 internationalization works by means of @dfn{locales}.  Each locale
14 specifies a collection of conventions, one convention for each purpose.
15 The user chooses a set of conventions by specifying a locale (via
16 environment variables).
17
18 All programs inherit the chosen locale as part of their environment.
19 Provided the programs are written to obey the choice of locale, they
20 will follow the conventions preferred by the user.
21
22 @menu
23 * Effects of Locale::           Actions affected by the choice of
24                                  locale.
25 * Choosing Locale::             How the user specifies a locale.
26 * Locale Categories::           Different purposes for which you can
27                                  select a locale.
28 * Setting the Locale::          How a program specifies the locale
29                                  with library functions.
30 * Standard Locales::            Locale names available on all systems.
31 * Numeric Formatting::          How to format numbers according to the
32                                  chosen locale.
33 @end menu
34
35 @node Effects of Locale, Choosing Locale,  , Locales
36 @section What Effects a Locale Has
37
38 Each locale specifies conventions for several purposes, including the
39 following:
40
41 @itemize @bullet
42 @item
43 What multibyte character sequences are valid, and how they are
44 interpreted (@pxref{Extended Characters}).
45
46 @item
47 Classification of which characters in the local character set are
48 considered alphabetic, and upper- and lower-case conversion conventions
49 (@pxref{Character Handling}).
50
51 @item
52 The collating sequence for the local language and character set
53 (@pxref{Collation Functions}).
54
55 @item
56 Formatting of numbers and currency amounts (@pxref{Numeric Formatting}).
57
58 @item
59 Formatting of dates and times (@pxref{Formatting Date and Time}).
60
61 @item
62 What language to use for output, including error messages.
63 (The C library doesn't yet help you implement this.)
64
65 @item
66 What language to use for user answers to yes-or-no questions.
67
68 @item
69 What language to use for more complex user input.
70 (The C library doesn't yet help you implement this.)
71 @end itemize
72
73 Some aspects of adapting to the specified locale are handled
74 automatically by the library subroutines.  For example, all your program
75 needs to do in order to use the collating sequence of the chosen locale
76 is to use @code{strcoll} or @code{strxfrm} to compare strings.
77
78 Other aspects of locales are beyond the comprehension of the library.
79 For example, the library can't automatically translate your program's
80 output messages into other languages.  The only way you can support
81 output in the user's favorite language is to program this more or less
82 by hand.  (Eventually, we hope to provide facilities to make this
83 easier.)
84
85 This chapter discusses the mechanism by which you can modify the current
86 locale.  The effects of the current locale on specific library functions
87 are discussed in more detail in the descriptions of those functions.
88
89 @node Choosing Locale, Locale Categories, Effects of Locale, Locales
90 @section Choosing a Locale
91
92 The simplest way for the user to choose a locale is to set the
93 environment variable @code{LANG}.  This specifies a single locale to use
94 for all purposes.  For example, a user could specify a hypothetical
95 locale named @samp{espana-castellano} to use the standard conventions of
96 most of Spain.
97
98 The set of locales supported depends on the operating system you are
99 using, and so do their names.  We can't make any promises about what
100 locales will exist, except for one standard locale called @samp{C} or
101 @samp{POSIX}.
102
103 @cindex combining locales
104 A user also has the option of specifying different locales for different
105 purposes---in effect, choosing a mixture of multiple locales.
106
107 For example, the user might specify the locale @samp{espana-castellano}
108 for most purposes, but specify the locale @samp{usa-english} for
109 currency formatting.  This might make sense if the user is a
110 Spanish-speaking American, working in Spanish, but representing monetary
111 amounts in US dollars.
112
113 Note that both locales @samp{espana-castellano} and @samp{usa-english},
114 like all locales, would include conventions for all of the purposes to
115 which locales apply.  However, the user can choose to use each locale
116 for a particular subset of those purposes.
117
118 @node Locale Categories, Setting the Locale, Choosing Locale, Locales
119 @section Categories of Activities that Locales Affect
120 @cindex categories for locales
121 @cindex locale categories
122
123 The purposes that locales serve are grouped into @dfn{categories}, so
124 that a user or a program can choose the locale for each category
125 independently.  Here is a table of categories; each name is both an
126 environment variable that a user can set, and a macro name that you can
127 use as an argument to @code{setlocale}.
128
129 @table @code
130 @comment locale.h
131 @comment ISO
132 @item LC_COLLATE
133 @vindex LC_COLLATE
134 This category applies to collation of strings (functions @code{strcoll}
135 and @code{strxfrm}); see @ref{Collation Functions}.
136
137 @comment locale.h
138 @comment ISO
139 @item LC_CTYPE
140 @vindex LC_CTYPE
141 This category applies to classification and conversion of characters,
142 and to multibyte and wide characters;
143 see @ref{Character Handling} and @ref{Extended Characters}.
144
145 @comment locale.h
146 @comment ISO
147 @item LC_MONETARY
148 @vindex LC_MONETARY
149 This category applies to formatting monetary values; see @ref{Numeric
150 Formatting}.
151
152 @comment locale.h
153 @comment ISO
154 @item LC_NUMERIC
155 @vindex LC_NUMERIC
156 This category applies to formatting numeric values that are not
157 monetary; see @ref{Numeric Formatting}.
158
159 @comment locale.h
160 @comment ISO
161 @item LC_TIME
162 @vindex LC_TIME
163 This category applies to formatting date and time values; see
164 @ref{Formatting Date and Time}.
165
166 @comment locale.h
167 @comment XOPEN
168 @item LC_MESSAGES
169 @vindex LC_MESSAGES
170 This category applies to selecting the language used in the user interface
171 for message translation.
172 @ignore  see @ref{gettext} and @ref{catgets}
173 @end ignore
174
175 @comment locale.h
176 @comment ISO
177 @item LC_ALL
178 @vindex LC_ALL
179 This is not an environment variable; it is only a macro that you can use
180 with @code{setlocale} to set a single locale for all purposes.
181
182 @comment locale.h
183 @comment ISO
184 @item LANG
185 @vindex LANG
186 If this environment variable is defined, its value specifies the locale
187 to use for all purposes except as overridden by the variables above.
188 @end table
189
190 @node Setting the Locale, Standard Locales, Locale Categories, Locales
191 @section How Programs Set the Locale
192
193 A C program inherits its locale environment variables when it starts up.
194 This happens automatically.  However, these variables do not
195 automatically control the locale used by the library functions, because
196 @w{ISO C} says that all programs start by default in the standard @samp{C}
197 locale.  To use the locales specified by the environment, you must call
198 @code{setlocale}.  Call it as follows:
199
200 @smallexample
201 setlocale (LC_ALL, "");
202 @end smallexample
203
204 @noindent
205 to select a locale based on the appropriate environment variables.
206
207 @cindex changing the locale
208 @cindex locale, changing
209 You can also use @code{setlocale} to specify a particular locale, for
210 general use or for a specific category.
211
212 @pindex locale.h
213 The symbols in this section are defined in the header file @file{locale.h}.
214
215 @comment locale.h
216 @comment ISO
217 @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
218 The function @code{setlocale} sets the current locale for
219 category @var{category} to @var{locale}.
220
221 If @var{category} is @code{LC_ALL}, this specifies the locale for all
222 purposes.  The other possible values of @var{category} specify an
223 individual purpose (@pxref{Locale Categories}).
224
225 You can also use this function to find out the current locale by passing
226 a null pointer as the @var{locale} argument.  In this case,
227 @code{setlocale} returns a string that is the name of the locale
228 currently selected for category @var{category}.
229
230 The string returned by @code{setlocale} can be overwritten by subsequent
231 calls, so you should make a copy of the string (@pxref{Copying and
232 Concatenation}) if you want to save it past any further calls to
233 @code{setlocale}.  (The standard library is guaranteed never to call
234 @code{setlocale} itself.)
235
236 You should not modify the string returned by @code{setlocale}.
237 It might be the same string that was passed as an argument in a
238 previous call to @code{setlocale}.
239
240 When you read the current locale for category @code{LC_ALL}, the value
241 encodes the entire combination of selected locales for all categories.
242 In this case, the value is not just a single locale name.  In fact, we
243 don't make any promises about what it looks like.  But if you specify
244 the same ``locale name'' with @code{LC_ALL} in a subsequent call to
245 @code{setlocale}, it restores the same combination of locale selections.
246
247 When the @var{locale} argument is not a null pointer, the string returned
248 by @code{setlocale} reflects the newly modified locale.
249
250 If you specify an empty string for @var{locale}, this means to read the
251 appropriate environment variable and use its value to select the locale
252 for @var{category}.
253
254 If you specify an invalid locale name, @code{setlocale} returns a null
255 pointer and leaves the current locale unchanged.
256 @end deftypefun
257
258 Here is an example showing how you might use @code{setlocale} to
259 temporarily switch to a new locale.
260
261 @smallexample
262 #include <stddef.h>
263 #include <locale.h>
264 #include <stdlib.h>
265 #include <string.h>
266
267 void
268 with_other_locale (char *new_locale,
269                    void (*subroutine) (int),
270                    int argument)
271 @{
272   char *old_locale, *saved_locale;
273
274   /* @r{Get the name of the current locale.}  */
275   old_locale = setlocale (LC_ALL, NULL);
276
277   /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */
278   saved_locale = strdup (old_locale);
279   if (old_locale == NULL)
280     fatal ("Out of memory");
281
282   /* @r{Now change the locale and do some stuff with it.} */
283   setlocale (LC_ALL, new_locale);
284   (*subroutine) (argument);
285
286   /* @r{Restore the original locale.} */
287   setlocale (LC_ALL, saved_locale);
288   free (saved_locale);
289 @}
290 @end smallexample
291
292 @strong{Portability Note:} Some @w{ISO C} systems may define additional
293 locale categories.  For portability, assume that any symbol beginning
294 with @samp{LC_} might be defined in @file{locale.h}.
295
296 @node Standard Locales, Numeric Formatting, Setting the Locale, Locales
297 @section Standard Locales
298
299 The only locale names you can count on finding on all operating systems
300 are these three standard ones:
301
302 @table @code
303 @item "C"
304 This is the standard C locale.  The attributes and behavior it provides
305 are specified in the @w{ISO C} standard.  When your program starts up, it
306 initially uses this locale by default.
307
308 @item "POSIX"
309 This is the standard POSIX locale.  Currently, it is an alias for the
310 standard C locale.
311
312 @item ""
313 The empty name says to select a locale based on environment variables.
314 @xref{Locale Categories}.
315 @end table
316
317 Defining and installing named locales is normally a responsibility of
318 the system administrator at your site (or the person who installed the
319 GNU C library).  Some systems may allow users to create locales, but
320 we don't discuss that here.
321 @c ??? If we give the GNU system that capability, this place will have
322 @c ??? to be changed.
323
324 If your program needs to use something other than the @samp{C} locale,
325 it will be more portable if you use whatever locale the user specifies
326 with the environment, rather than trying to specify some non-standard
327 locale explicitly by name.  Remember, different machines might have
328 different sets of locales installed.
329
330 @node Numeric Formatting,  , Standard Locales, Locales
331 @section Numeric Formatting
332
333 When you want to format a number or a currency amount using the
334 conventions of the current locale, you can use the function
335 @code{localeconv} to get the data on how to do it.  The function
336 @code{localeconv} is declared in the header file @file{locale.h}.
337 @pindex locale.h
338 @cindex monetary value formatting
339 @cindex numeric value formatting
340
341 @comment locale.h
342 @comment ISO
343 @deftypefun {struct lconv *} localeconv (void)
344 The @code{localeconv} function returns a pointer to a structure whose
345 components contain information about how numeric and monetary values
346 should be formatted in the current locale.
347
348 You shouldn't modify the structure or its contents.  The structure might
349 be overwritten by subsequent calls to @code{localeconv}, or by calls to
350 @code{setlocale}, but no other function in the library overwrites this
351 value.
352 @end deftypefun
353
354 @comment locale.h
355 @comment ISO
356 @deftp {Data Type} {struct lconv}
357 This is the data type of the value returned by @code{localeconv}.
358 @end deftp
359
360 If a member of the structure @code{struct lconv} has type @code{char},
361 and the value is @code{CHAR_MAX}, it means that the current locale has
362 no value for that parameter.
363
364 @menu
365 * General Numeric::             Parameters for formatting numbers and
366                                  currency amounts.
367 * Currency Symbol::             How to print the symbol that identifies an
368                                  amount of money (e.g. @samp{$}).
369 * Sign of Money Amount::        How to print the (positive or negative) sign
370                                  for a monetary amount, if one exists.
371 @end menu
372
373 @node General Numeric, Currency Symbol,  , Numeric Formatting
374 @subsection Generic Numeric Formatting Parameters
375
376 These are the standard members of @code{struct lconv}; there may be
377 others.
378
379 @table @code
380 @item char *decimal_point
381 @itemx char *mon_decimal_point
382 These are the decimal-point separators used in formatting non-monetary
383 and monetary quantities, respectively.  In the @samp{C} locale, the
384 value of @code{decimal_point} is @code{"."}, and the value of
385 @code{mon_decimal_point} is @code{""}.
386 @cindex decimal-point separator
387
388 @item char *thousands_sep
389 @itemx char *mon_thousands_sep
390 These are the separators used to delimit groups of digits to the left of
391 the decimal point in formatting non-monetary and monetary quantities,
392 respectively.  In the @samp{C} locale, both members have a value of
393 @code{""} (the empty string).
394
395 @item char *grouping
396 @itemx char *mon_grouping
397 These are strings that specify how to group the digits to the left of
398 the decimal point.  @code{grouping} applies to non-monetary quantities
399 and @code{mon_grouping} applies to monetary quantities.  Use either
400 @code{thousands_sep} or @code{mon_thousands_sep} to separate the digit
401 groups.
402 @cindex grouping of digits
403
404 Each string is made up of decimal numbers separated by semicolons.
405 Successive numbers (from left to right) give the sizes of successive
406 groups (from right to left, starting at the decimal point).  The last
407 number in the string is used over and over for all the remaining groups.
408
409 If the last integer is @code{-1}, it means that there is no more
410 grouping---or, put another way, any remaining digits form one large
411 group without separators.
412
413 For example, if @code{grouping} is @code{"4;3;2"}, the correct grouping
414 for the number @code{123456787654321} is @samp{12}, @samp{34},
415 @samp{56}, @samp{78}, @samp{765}, @samp{4321}.  This uses a group of 4
416 digits at the end, preceded by a group of 3 digits, preceded by groups
417 of 2 digits (as many as needed).  With a separator of @samp{,}, the
418 number would be printed as @samp{12,34,56,78,765,4321}.
419
420 A value of @code{"3"} indicates repeated groups of three digits, as
421 normally used in the U.S.
422
423 In the standard @samp{C} locale, both @code{grouping} and
424 @code{mon_grouping} have a value of @code{""}.  This value specifies no
425 grouping at all.
426
427 @item char int_frac_digits
428 @itemx char frac_digits
429 These are small integers indicating how many fractional digits (to the
430 right of the decimal point) should be displayed in a monetary value in
431 international and local formats, respectively.  (Most often, both
432 members have the same value.)
433
434 In the standard @samp{C} locale, both of these members have the value
435 @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
436 what to do when you find this the value; we recommend printing no
437 fractional digits.  (This locale also specifies the empty string for
438 @code{mon_decimal_point}, so printing any fractional digits would be
439 confusing!)
440 @end table
441
442 @node Currency Symbol, Sign of Money Amount, General Numeric, Numeric Formatting
443 @subsection Printing the Currency Symbol
444 @cindex currency symbols
445
446 These members of the @code{struct lconv} structure specify how to print
447 the symbol to identify a monetary value---the international analog of
448 @samp{$} for US dollars.
449
450 Each country has two standard currency symbols.  The @dfn{local currency
451 symbol} is used commonly within the country, while the
452 @dfn{international currency symbol} is used internationally to refer to
453 that country's currency when it is necessary to indicate the country
454 unambiguously.
455
456 For example, many countries use the dollar as their monetary unit, and
457 when dealing with international currencies it's important to specify
458 that one is dealing with (say) Canadian dollars instead of U.S. dollars
459 or Australian dollars.  But when the context is known to be Canada,
460 there is no need to make this explicit---dollar amounts are implicitly
461 assumed to be in Canadian dollars.
462
463 @table @code
464 @item char *currency_symbol
465 The local currency symbol for the selected locale.
466
467 In the standard @samp{C} locale, this member has a value of @code{""}
468 (the empty string), meaning ``unspecified''.  The ISO standard doesn't
469 say what to do when you find this value; we recommend you simply print
470 the empty string as you would print any other string found in the
471 appropriate member.
472
473 @item char *int_curr_symbol
474 The international currency symbol for the selected locale.
475
476 The value of @code{int_curr_symbol} should normally consist of a
477 three-letter abbreviation determined by the international standard
478 @cite{ISO 4217 Codes for the Representation of Currency and Funds},
479 followed by a one-character separator (often a space).
480
481 In the standard @samp{C} locale, this member has a value of @code{""}
482 (the empty string), meaning ``unspecified''.  We recommend you simply
483 print the empty string as you would print any other string found in the
484 appropriate member.
485
486 @item char p_cs_precedes
487 @itemx char n_cs_precedes
488 These members are @code{1} if the @code{currency_symbol} string should
489 precede the value of a monetary amount, or @code{0} if the string should
490 follow the value.  The @code{p_cs_precedes} member applies to positive
491 amounts (or zero), and the @code{n_cs_precedes} member applies to
492 negative amounts.
493
494 In the standard @samp{C} locale, both of these members have a value of
495 @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
496 what to do when you find this value, but we recommend printing the
497 currency symbol before the amount.  That's right for most countries.
498 In other words, treat all nonzero values alike in these members.
499
500 The POSIX standard says that these two members apply to the
501 @code{int_curr_symbol} as well as the @code{currency_symbol}.  The ISO
502 C standard seems to imply that they should apply only to the
503 @code{currency_symbol}---so the @code{int_curr_symbol} should always
504 precede the amount.
505
506 We can only guess which of these (if either) matches the usual
507 conventions for printing international currency symbols.  Our guess is
508 that they should always preceed the amount.  If we find out a reliable
509 answer, we will put it here.
510
511 @item char p_sep_by_space
512 @itemx char n_sep_by_space
513 These members are @code{1} if a space should appear between the
514 @code{currency_symbol} string and the amount, or @code{0} if no space
515 should appear.  The @code{p_sep_by_space} member applies to positive
516 amounts (or zero), and the @code{n_sep_by_space} member applies to
517 negative amounts.
518
519 In the standard @samp{C} locale, both of these members have a value of
520 @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
521 what you should do when you find this value; we suggest you treat it as
522 one (print a space).  In other words, treat all nonzero values alike in
523 these members.
524
525 These members apply only to @code{currency_symbol}.  When you use
526 @code{int_curr_symbol}, you never print an additional space, because
527 @code{int_curr_symbol} itself contains the appropriate separator.
528
529 The POSIX standard says that these two members apply to the
530 @code{int_curr_symbol} as well as the @code{currency_symbol}.  But an
531 example in the @w{ISO C} standard clearly implies that they should apply
532 only to the @code{currency_symbol}---that the @code{int_curr_symbol}
533 contains any appropriate separator, so you should never print an
534 additional space.
535
536 Based on what we know now, we recommend you ignore these members when
537 printing international currency symbols, and print no extra space.
538 @end table
539
540 @node Sign of Money Amount,  , Currency Symbol, Numeric Formatting
541 @subsection Printing the Sign of an Amount of Money
542
543 These members of the @code{struct lconv} structure specify how to print
544 the sign (if any) in a monetary value.
545
546 @table @code
547 @item char *positive_sign
548 @itemx char *negative_sign
549 These are strings used to indicate positive (or zero) and negative
550 (respectively) monetary quantities.
551
552 In the standard @samp{C} locale, both of these members have a value of
553 @code{""} (the empty string), meaning ``unspecified''.
554
555 The ISO standard doesn't say what to do when you find this value; we
556 recommend printing @code{positive_sign} as you find it, even if it is
557 empty.  For a negative value, print @code{negative_sign} as you find it
558 unless both it and @code{positive_sign} are empty, in which case print
559 @samp{-} instead.  (Failing to indicate the sign at all seems rather
560 unreasonable.)
561
562 @item char p_sign_posn
563 @itemx char n_sign_posn
564 These members have values that are small integers indicating how to
565 position the sign for nonnegative and negative monetary quantities,
566 respectively.  (The string used by the sign is what was specified with
567 @code{positive_sign} or @code{negative_sign}.)  The possible values are
568 as follows:
569
570 @table @code
571 @item 0
572 The currency symbol and quantity should be surrounded by parentheses.
573
574 @item 1
575 Print the sign string before the quantity and currency symbol.
576
577 @item 2
578 Print the sign string after the quantity and currency symbol.
579
580 @item 3
581 Print the sign string right before the currency symbol.
582
583 @item 4
584 Print the sign string right after the currency symbol.
585
586 @item CHAR_MAX
587 ``Unspecified''.  Both members have this value in the standard
588 @samp{C} locale.
589 @end table
590
591 The ISO standard doesn't say what you should do when the value is
592 @code{CHAR_MAX}.  We recommend you print the sign after the currency
593 symbol.
594 @end table
595
596 It is not clear whether you should let these members apply to the
597 international currency format or not.  POSIX says you should, but
598 intuition plus the examples in the @w{ISO C} standard suggest you should
599 not.  We hope that someone who knows well the conventions for formatting
600 monetary quantities will tell us what we should recommend.