Misc. changes.
[kopensolaris-gnu/glibc.git] / manual / locale.texi
1 @node Locales
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 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
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
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
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
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
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
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
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 whose elements indicate the size of each group of 
390 digits to the left of the decimal point in formatting non-monetary
391 and monetary quantities, respectively.
392 @cindex grouping of digits
393
394 The characters in this string are actually interpreted as numbers.  A
395 nonzero value is the number of digits in the next group of digits, going
396 from right to left (less significant digits to more significant).  The
397 last character in the string is used over and over for successive
398 groups.
399
400 If a character in the string has value @code{CHAR_MAX}, it indicates
401 that no further grouping is to be performed.
402
403 For example, if @code{grouping} is @code{"\004\003\002"}, the number
404 @code{123456787654321} should be grouped into @samp{12}, @samp{34},
405 @samp{56}, @samp{78}, @samp{765}, @samp{4321}.  This uses a group of 4
406 digits at the end, preceded by a group of 3 digits, preceded by groups
407 of 2 digits (as many as needed).  With a separator of @samp{,}, the number
408 would be printed as @samp{12,34,56,78,765,4321}.
409
410 A value of @code{"\003"} indicates repeated groups of three digits, as
411 normally used in the U.S.
412
413 In the standard @samp{C} locale, both @code{grouping} and
414 @code{mon_grouping} have a value of @code{""}, which specifies no
415 grouping of digits.
416
417 @item char int_frac_digits
418 @itemx char frac_digits
419 These are small integers indicating how many fractional digits (to the
420 right of the decimal point) should be displayed in a monetary value in
421 international and local formats, respectively.  (Most often, both
422 members have the same value.)
423
424 In the standard @samp{C} locale, both of these members have the value
425 @code{CHAR_MAX}, meaning ``unspecified''.  The ANSI standard doesn't say
426 what to do when you find this the value; we recommend printing no
427 fractional digits.  (This locale also specifies the empty string for
428 @code{mon_decimal_point}, so printing any fractional digits would be
429 confusing!)
430 @end table
431
432 @node Currency Symbol
433 @subsection Printing the Currency Symbol
434 @cindex currency symbols
435
436 These members of the @code{struct lconv} structure specify how to print
437 the symbol to identify a monetary value---the international analog of
438 @samp{$} for US dollars.
439
440 Each country has two standard currency symbols.  The @dfn{local currency
441 symbol} is used commonly within the country, while the
442 @dfn{international currency symbol} is used internationally to refer to
443 that country's currency when it is necessary to indicate the country
444 unambiguously.
445
446 For example, many countries use the dollar as their monetary unit, and
447 when dealing with international currencies it's important to specify
448 that one is dealing with (say) Canadian dollars instead of U.S. dollars
449 or Australian dollars.  But locally within Canada, dollar amounts are
450 implicitly assumed to be in Canadian dollars.
451
452 @table @code
453 @item char *currency_symbol
454 The local currency symbol for the selected locale.
455
456 In the standard @samp{C} locale, this member has a value of @code{""}
457 (the empty string), meaning ``unspecified''.  The ANSI standard doesn't
458 say what to do when you find this value; we recommend you simply print
459 the empty string as you would print any other string found in the
460 appropriate member.
461
462 @item char *int_curr_symbol
463 The international currency symbol for the selected locale.
464
465 The value of @code{int_curr_symbol} should normally consist of a
466 three-letter abbreviation determined by the international standard
467 @cite{ISO 4217 Codes for the Representation of Currency and Funds},
468 followed by a one-character separator (often a space).
469
470 In the standard @samp{C} locale, this member has a value of @code{""}
471 (the empty string), meaning ``unspecified''.  We recommend you simply
472 print the empty string as you would print any other string found in the
473 appropriate member.
474
475 @item char p_cs_precedes
476 @itemx char n_cs_precedes
477 These members are @code{1} if the @code{currency_symbol} string should
478 precede the value of a monetary amount, or @code{0} if the string should
479 follow the value.  The @code{p_cs_precedes} member applies to positive
480 amounts (or zero), and the @code{n_cs_precedes} member applies to
481 negative amounts.
482
483 In the standard @samp{C} locale, both of these members have a value of
484 @code{CHAR_MAX}, meaning ``unspecified''.  The ANSI standard doesn't say
485 what to do when you find this value, but we recommend printing the
486 currency symbol before the amount.  That's right for most countries.
487 In other words, treat all nonzero values alike in these members.
488
489 These members apply only to @code{currency_symbol}.  When you use
490 @code{int_curr_symbol}, always print it before the amount.
491
492 @item char p_sep_by_space
493 @itemx char n_sep_by_space
494 These members are @code{1} if a space should appear between the
495 @code{currency_symbol} string and the amount, or @code{0} if no space
496 should appear.  The @code{p_sep_by_space} member applies to positive
497 amounts (or zero), and the @code{n_sep_by_space} member applies to
498 negative amounts.
499
500 In the standard @samp{C} locale, both of these members have a value of
501 @code{CHAR_MAX}, meaning ``unspecified''.  The ANSI standard doesn't say
502 what you should do when you find this value; we suggest you treat it as
503 one (print a space).  In other words, treat all nonzero values alike in
504 these members.
505
506 These members apply only to @code{currency_symbol}.  When you use
507 @code{int_curr_symbol}, you never print an additional space, because
508 @code{int_curr_symbol} itself contains the appropriate separator.
509 @end table
510
511 @node Sign of Money Amount
512 @subsection Printing the Sign of an Amount of Money
513
514 These members of the @code{struct lconv} structure specify how to print
515 the sign (if any) in a monetary value.
516
517 @table @code
518 @item char *positive_sign
519 @itemx char *negative_sign
520 These are strings used to indicate positive (or zero) and negative
521 (respectively) monetary quantities.
522
523 In the standard @samp{C} locale, both of these members have a value of
524 @code{""} (the empty string), meaning ``unspecified''.
525
526 The ANSI standard doesn't say what to do when you find this value; we
527 recommend printing @code{positive_sign} as you find it, even if it is
528 empty.  For a negative value, print @code{negative_sign} as you find it
529 unless both it and @code{positive_sign} are empty, in which case print
530 @samp{-} instead.  (Failing to indicate the sign at all seems rather
531 unreasonable.)
532
533 It is not clear whether you should use these sign strings for the
534 international currency format or not.
535
536 @item char p_sign_posn
537 @itemx char n_sign_posn
538 These members have values that are small integers indicating how to
539 position the sign for nonnegative and negative monetary quantities,
540 respectively.  (The string used by the sign is what was specified with
541 @code{positive_sign} or @code{negative_sign}.)  The possible values are
542 as follows:
543
544 @table @code
545 @item 0
546 The currency symbol and quantity should be surrounded by parentheses.
547
548 @item 1
549 Print the sign string before the quantity and currency symbol.
550
551 @item 2
552 Print the sign string after the quantity and currency symbol.
553
554 @item 3
555 Print the sign string right before the currency symbol.
556
557 @item 4
558 Print the sign string right after the currency symbol.
559
560 @item CHAR_MAX
561 ``Unspecified''.  Both members have this value in the standard
562 @samp{C} locale.
563 @end table
564
565 The ANSI standard doesn't say what you should do when the value is
566 @code{CHAR_MAX}.  We recommend you print the sign after the currency
567 symbol.
568
569 It is not clear whether these members apply to the international
570 currency format or not.
571 @end table