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