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