fixed menu descriptions
[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 ANSI 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                                  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.
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 two 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 ANSI
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 ANSI
139 @item LC_CTYPE
140 @vindex LC_CTYPE
141 This category applies to classification and conversion of characters;
142 see @ref{Character Handling}.
143
144 @comment locale.h
145 @comment ANSI
146 @item LC_MONETARY
147 @vindex LC_MONETARY
148 This category applies to formatting monetary values; see @ref{Numeric
149 Formatting}.
150
151 @comment locale.h
152 @comment ANSI
153 @item LC_NUMERIC
154 @vindex LC_NUMERIC
155 This category applies to formatting numeric values that are not
156 monetary; see @ref{Numeric Formatting}.
157
158 @comment locale.h
159 @comment ANSI
160 @item LC_TIME
161 @vindex LC_TIME
162 This category applies to formatting date and time values; see
163 @ref{Formatting Date and Time}.
164
165 @comment locale.h
166 @comment GNU
167 @item LC_RESPONSE
168 @vindex LC_RESPONSE
169 This category applies to recognizing ``yes'' or ``no'' responses to
170 questions.
171
172 @strong{Incomplete:} This is apparently a feature that was in some early
173 draft of the POSIX.2 standard, but it's not listed in draft 11.  Do we
174 still support this anyway?  Is there a corresponding environment
175 variable?
176
177 @comment locale.h
178 @comment ANSI
179 @item LC_ALL
180 @vindex LC_ALL
181 This is not an environment variable; it is only a macro that you can use
182 with @code{setlocale} to set a single locale for all purposes.
183
184 @comment locale.h
185 @comment ANSI
186 @item LANG
187 @vindex LANG
188 If this environment variable is defined, its value specifies the locale
189 to use for all purposes except as overridden by the variables below.
190 @end table
191
192 @node Setting the Locale, Standard Locales, Locale Categories, Locales
193 @section How Programs Set the Locale
194
195 A C program inherits its locale environment variables when it starts up.
196 This happens automatically.  However, these variables do not
197 automatically control the locale used by the library functions, because
198 ANSI C says that all programs start by default in the standard @samp{C}
199 locale.  To use the locales specified by the environment, you must call
200 @code{setlocale}.  Call it as follows:
201
202 @example
203 setlocale (LC_ALL, "");
204 @end example
205
206 @noindent
207 to select a locale based on the appropriate environment variables.
208
209 @cindex changing the locale
210 @cindex locale, changing
211 You can also use @code{setlocale} to specify a particular locale, for
212 general use or for a specific category.
213
214 @pindex locale.h
215 The symbols in this section are defined in the header file @file{locale.h}.
216
217 @comment locale.h
218 @comment ANSI
219 @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
220 The function @code{setlocale} sets the current locale for 
221 category @var{category} to @var{locale}.
222
223 If @var{category} is @code{LC_ALL}, this specifies the locale for all
224 purposes.  The other possible values of @var{category} specify an
225 individual purpose (@pxref{Locale Categories}).
226
227 You can also use this function to find out the current locale by passing
228 a null pointer as the @var{locale} argument.  In this case,
229 @code{setlocale} returns a string that is the name of the locale
230 currently selected for category @var{category}.
231
232 The string returned by @code{setlocale} can be overwritten by subsequent
233 calls, so you should make a copy of the string (@pxref{Copying and
234 Concatenation}) if you want to save it past any further calls to
235 @code{setlocale}.  (The standard library is guaranteed never to call
236 @code{setlocale} itself.)
237
238 You should not modify the string returned by @code{setlocale}.
239 It might be the same string that was passed as an argument in a 
240 previous call to @code{setlocale}.
241
242 When you read the current locale for category @code{LC_ALL}, the value
243 encodes the entire combination of selected locales for all categories.
244 In this case, the value is not just a single locale name.  In fact, we
245 don't make any promises about what it looks like.  But if you specify
246 the same ``locale name'' with @code{LC_ALL} in a subsequent call to
247 @code{setlocale}, it restores the same combination of locale selections.
248
249 When the @var{locale} argument is not a null pointer, the string returned
250 by @code{setlocale} reflects the newly modified locale.
251
252 If you specify an empty string for @var{locale}, this means to read the
253 appropriate environment variable and use its value to select the locale
254 for @var{category}.
255
256 If you specify an invalid locale name, @code{setlocale} returns a null
257 pointer and leaves the current locale unchanged.
258 @end deftypefun
259
260 Here is an example showing how you might use @code{setlocale} to
261 temporarily switch to a new locale.
262
263 @example
264 #include <stddef.h>
265 #include <locale.h>
266 #include <stdlib.h>
267 #include <string.h>
268
269 void
270 with_other_locale (char *new_locale,
271                    void (*subroutine) (int),
272                    int argument)
273 @{
274   char *old_locale, *saved_locale;
275
276   /* @r{Get the name of the current locale.}  */
277   old_locale = setlocale (LC_ALL, NULL);
278   
279   /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */
280   saved_locale = xmalloc (strlen (old_locale));
281   strcpy (saved_locale, old_locale);
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 example
292
293 @strong{Portability Note:} Some ANSI 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 ANSI 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 stands for a site-specific default locale.  It's supposed
315 to be a good default for the machine on which the program is running.
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).  Users cannot do this.  @xref{Defining New Locales}, for
321 information about what this involves.
322
323 If your program needs to use something other than the @samp{C} locale,
324 it will be more portable if you use the whatever locale the user
325 specifies with the environment, rather than trying to specify some
326 non-standard locale explicitly by name.  Remember, different machines
327 might have different sets of locales installed.
328
329 @node Numeric Formatting,  , Standard Locales, Locales
330 @section Numeric Formatting
331
332 When you want to format a number or a currency amount using the
333 conventions of the current locale, you can use the function
334 @code{localeconv} to get the data on how to do it.  The function
335 @code{localeconv} is declared in the header file @file{locale.h}.
336 @pindex locale.h
337 @cindex monetary value formatting
338 @cindex numeric value formatting
339
340 @comment locale.h
341 @comment ANSI
342 @deftypefun {struct lconv *} localeconv ()
343 The @code{localeconv} function returns a pointer to a structure whose
344 components contain information about how numeric and monetary values
345 should be formatted in the current locale.
346
347 You shouldn't modify the structure or its contents.  The structure might
348 be overwritten by subsequent calls to @code{localeconv}, or by calls to
349 @code{setlocale}, but no other function in the library overwrites this
350 value.
351 @end deftypefun
352
353 @comment locale.h
354 @comment ANSI
355 @deftp {Data Type} {struct lconv}
356 This is the data type of the value returned by @code{localeconv}.
357 @end deftp
358
359 If a member of the structure @code{struct lconv} has type @code{char},
360 and the value is @code{CHAR_MAX}, it means that the current locale has
361 no value for that parameter.
362
363 @menu
364 * General Numeric::             Parameters for formatting numbers and
365                                  currency amounts.
366 * Currency Symbol::             How to print the symbol that identifies an
367                                  amount of money (e.g. @samp{$}).
368 * Sign of Money Amount::        How to print the (positive or negative) sign
369                                  for a monetary amount, if one exists.
370 @end menu
371
372 @node General Numeric, Currency Symbol,  , Numeric Formatting
373 @subsection Generic Numeric Formatting Parameters
374
375 These are the standard members of @code{struct lconv}; there may be
376 others.
377
378 @table @code
379 @item char *decimal_point
380 @itemx char *mon_decimal_point
381 These are the decimal-point separators used in formatting non-monetary
382 and monetary quantities, respectively.  In the @samp{C} locale, the
383 value of @code{decimal_point} is @code{"."}, and the value of
384 @code{mon_decimal_point} is @code{""}.
385 @cindex decimal-point separator
386
387 @item char *thousands_sep
388 @itemx char *mon_thousands_sep
389 These are the separators used to delimit groups of digits to the left of
390 the decimal point in formatting non-monetary and monetary quantities,
391 respectively.  In the @samp{C} locale, both members have a value of
392 @code{""} (the empty string).
393
394 @item char *grouping
395 @itemx char *mon_grouping
396 These are strings that specify how to group the digits to the left of
397 the decimal point.  @code{grouping} applies to non-monetary quantities
398 and @code{mon_grouping} applies to monetary quantities.  Use either
399 @code{thousands_sep} or @code{mon_thousands_sep} to separate the digit
400 groups.
401 @cindex grouping of digits
402
403 Each string is made up of decimal numbers separated by semicolons.
404 Successive numbers (from left to right) give the sizes of successive
405 groups (from right to left, starting at the decimal point).  The last
406 number in the string is used over and over for all the remaining groups.
407
408 If the last integer is @code{-1}, it means that there is no more
409 grouping---or, put another way, any remaining digits form one large
410 group without separators.
411
412 For example, if @code{grouping} is @code{"4;3;2"}, the number
413 @code{123456787654321} should be grouped into @samp{12}, @samp{34},
414 @samp{56}, @samp{78}, @samp{765}, @samp{4321}.  This uses a group of 4
415 digits at the end, preceded by a group of 3 digits, preceded by groups
416 of 2 digits (as many as needed).  With a separator of @samp{,}, the
417 number would be printed as @samp{12,34,56,78,765,4321}.
418
419 A value of @code{"3"} indicates repeated groups of three digits, as
420 normally used in the U.S.
421
422 In the standard @samp{C} locale, both @code{grouping} and
423 @code{mon_grouping} have a value of @code{""}.  This value specifies no
424 grouping at all.
425
426 @item char int_frac_digits
427 @itemx char frac_digits
428 These are small integers indicating how many fractional digits (to the
429 right of the decimal point) should be displayed in a monetary value in
430 international and local formats, respectively.  (Most often, both
431 members have the same value.)
432
433 In the standard @samp{C} locale, both of these members have the value
434 @code{CHAR_MAX}, meaning ``unspecified''.  The ANSI standard doesn't say
435 what to do when you find this the value; we recommend printing no
436 fractional digits.  (This locale also specifies the empty string for
437 @code{mon_decimal_point}, so printing any fractional digits would be
438 confusing!)
439 @end table
440
441 @node Currency Symbol, Sign of Money Amount, General Numeric, Numeric Formatting
442 @subsection Printing the Currency Symbol
443 @cindex currency symbols
444
445 These members of the @code{struct lconv} structure specify how to print
446 the symbol to identify a monetary value---the international analog of
447 @samp{$} for US dollars.
448
449 Each country has two standard currency symbols.  The @dfn{local currency
450 symbol} is used commonly within the country, while the
451 @dfn{international currency symbol} is used internationally to refer to
452 that country's currency when it is necessary to indicate the country
453 unambiguously.
454
455 For example, many countries use the dollar as their monetary unit, and
456 when dealing with international currencies it's important to specify
457 that one is dealing with (say) Canadian dollars instead of U.S. dollars
458 or Australian dollars.  But when the context is known to be Canada,
459 there is no need to make this explicit---dollar amounts are implicitly
460 assumed to be in Canadian dollars.
461
462 @table @code
463 @item char *currency_symbol
464 The local currency symbol for the selected locale.
465
466 In the standard @samp{C} locale, this member has a value of @code{""}
467 (the empty string), meaning ``unspecified''.  The ANSI standard doesn't
468 say what to do when you find this value; we recommend you simply print
469 the empty string as you would print any other string found in the
470 appropriate member.
471
472 @item char *int_curr_symbol
473 The international currency symbol for the selected locale.
474
475 The value of @code{int_curr_symbol} should normally consist of a
476 three-letter abbreviation determined by the international standard
477 @cite{ISO 4217 Codes for the Representation of Currency and Funds},
478 followed by a one-character separator (often a space).
479
480 In the standard @samp{C} locale, this member has a value of @code{""}
481 (the empty string), meaning ``unspecified''.  We recommend you simply
482 print the empty string as you would print any other string found in the
483 appropriate member.
484
485 @item char p_cs_precedes
486 @itemx char n_cs_precedes
487 These members are @code{1} if the @code{currency_symbol} string should
488 precede the value of a monetary amount, or @code{0} if the string should
489 follow the value.  The @code{p_cs_precedes} member applies to positive
490 amounts (or zero), and the @code{n_cs_precedes} member applies to
491 negative amounts.
492
493 In the standard @samp{C} locale, both of these members have a value of
494 @code{CHAR_MAX}, meaning ``unspecified''.  The ANSI standard doesn't say
495 what to do when you find this value, but we recommend printing the
496 currency symbol before the amount.  That's right for most countries.
497 In other words, treat all nonzero values alike in these members.
498
499 The POSIX standard says that these two members apply to the
500 @code{int_curr_symbol} as well as the @code{currency_symbol}.  The ANSI
501 C standard seems to imply that they should apply only to the
502 @code{currency_symbol}---so the @code{int_curr_symbol} should always
503 preceed the amount.
504
505 We can only guess which of these (if either) matches the usual
506 conventions for printing international currency symbols.  Our guess is
507 that they should always preceed the amount.  If we find out a reliable
508 answer, we will put it here.
509
510 @item char p_sep_by_space
511 @itemx char n_sep_by_space
512 These members are @code{1} if a space should appear between the
513 @code{currency_symbol} string and the amount, or @code{0} if no space
514 should appear.  The @code{p_sep_by_space} member applies to positive
515 amounts (or zero), and the @code{n_sep_by_space} member applies to
516 negative amounts.
517
518 In the standard @samp{C} locale, both of these members have a value of
519 @code{CHAR_MAX}, meaning ``unspecified''.  The ANSI standard doesn't say
520 what you should do when you find this value; we suggest you treat it as
521 one (print a space).  In other words, treat all nonzero values alike in
522 these members.
523
524 These members apply only to @code{currency_symbol}.  When you use
525 @code{int_curr_symbol}, you never print an additional space, because
526 @code{int_curr_symbol} itself contains the appropriate separator.
527
528 The POSIX standard says that these two members apply to the
529 @code{int_curr_symbol} as well as the @code{currency_symbol}.  But an
530 example in the ANSI C standard clearly implies that they should apply
531 only to the @code{currency_symbol}---that the @code{int_curr_symbol}
532 contains any appropriate separator, so you should never print an
533 additional space.
534
535 Based on what we know now, we recommend you ignore these members when
536 printing international currency symbols, and print no extra space.
537 @end table
538
539 @node Sign of Money Amount,  , Currency Symbol, Numeric Formatting
540 @subsection Printing the Sign of an Amount of Money
541
542 These members of the @code{struct lconv} structure specify how to print
543 the sign (if any) in a monetary value.
544
545 @table @code
546 @item char *positive_sign
547 @itemx char *negative_sign
548 These are strings used to indicate positive (or zero) and negative
549 (respectively) monetary quantities.
550
551 In the standard @samp{C} locale, both of these members have a value of
552 @code{""} (the empty string), meaning ``unspecified''.
553
554 The ANSI standard doesn't say what to do when you find this value; we
555 recommend printing @code{positive_sign} as you find it, even if it is
556 empty.  For a negative value, print @code{negative_sign} as you find it
557 unless both it and @code{positive_sign} are empty, in which case print
558 @samp{-} instead.  (Failing to indicate the sign at all seems rather
559 unreasonable.)
560
561 @item char p_sign_posn
562 @itemx char n_sign_posn
563 These members have values that are small integers indicating how to
564 position the sign for nonnegative and negative monetary quantities,
565 respectively.  (The string used by the sign is what was specified with
566 @code{positive_sign} or @code{negative_sign}.)  The possible values are
567 as follows:
568
569 @table @code
570 @item 0
571 The currency symbol and quantity should be surrounded by parentheses.
572
573 @item 1
574 Print the sign string before the quantity and currency symbol.
575
576 @item 2
577 Print the sign string after the quantity and currency symbol.
578
579 @item 3
580 Print the sign string right before the currency symbol.
581
582 @item 4
583 Print the sign string right after the currency symbol.
584
585 @item CHAR_MAX
586 ``Unspecified''.  Both members have this value in the standard
587 @samp{C} locale.
588 @end table
589
590 The ANSI standard doesn't say what you should do when the value is
591 @code{CHAR_MAX}.  We recommend you print the sign after the currency
592 symbol.
593 @end table
594
595 It is not clear whether you should let these members apply to the
596 international currency format or not.  POSIX says you should, but
597 intuition plus the examples in the ANSI C standard suggest you should
598 not.  We hope that someone who knows well the conventions for formatting
599 monetary quantities will tell us what we should recommend.
600