(Formatting Numbers): Fix @node pointers.
[kopensolaris-gnu/glibc.git] / manual / locale.texi
1 @node Locales, Message Translation, Character Set Handling, 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 * Locale Information::          How to access the information for the locale.
33 * Formatting Numbers::          A dedicated function to format numbers.
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{Character Set Handling}).
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{General Numeric}).
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 (@pxref{Message Translation}).
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.  The C library provides functions to handle translations for
84 multiple languages easily.
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}.  Later we will describe how to construct locales.
103 @comment (@pxref{Building Locale Files}).
104
105 @cindex combining locales
106 A user also has the option of specifying different locales for different
107 purposes---in effect, choosing a mixture of multiple locales.
108
109 For example, the user might specify the locale @samp{espana-castellano}
110 for most purposes, but specify the locale @samp{usa-english} for
111 currency formatting.  This might make sense if the user is a
112 Spanish-speaking American, working in Spanish, but representing monetary
113 amounts in US dollars.
114
115 Note that both locales @samp{espana-castellano} and @samp{usa-english},
116 like all locales, would include conventions for all of the purposes to
117 which locales apply.  However, the user can choose to use each locale
118 for a particular subset of those purposes.
119
120 @node Locale Categories, Setting the Locale, Choosing Locale, Locales
121 @section Categories of Activities that Locales Affect
122 @cindex categories for locales
123 @cindex locale categories
124
125 The purposes that locales serve are grouped into @dfn{categories}, so
126 that a user or a program can choose the locale for each category
127 independently.  Here is a table of categories; each name is both an
128 environment variable that a user can set, and a macro name that you can
129 use as an argument to @code{setlocale}.
130
131 @vtable @code
132 @comment locale.h
133 @comment ISO
134 @item 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 This category applies to classification and conversion of characters,
142 and to multibyte and wide characters;
143 see @ref{Character Handling}, and @ref{Character Set Handling}.
144
145 @comment locale.h
146 @comment ISO
147 @item LC_MONETARY
148 This category applies to formatting monetary values; see @ref{General Numeric}.
149
150 @comment locale.h
151 @comment ISO
152 @item LC_NUMERIC
153 This category applies to formatting numeric values that are not
154 monetary; see @ref{General Numeric}.
155
156 @comment locale.h
157 @comment ISO
158 @item LC_TIME
159 This category applies to formatting date and time values; see
160 @ref{Formatting Date and Time}.
161
162 @comment locale.h
163 @comment XOPEN
164 @item LC_MESSAGES
165 This category applies to selecting the language used in the user
166 interface for message translation (@pxref{The Uniforum approach};
167 @pxref{Message catalogs a la X/Open}).
168
169 @comment locale.h
170 @comment ISO
171 @item LC_ALL
172 This is not an environment variable; it is only a macro that you can use
173 with @code{setlocale} to set a single locale for all purposes.  Setting
174 this environment variable overwrites all selections by the other
175 @code{LC_*} variables or @code{LANG}.
176
177 @comment locale.h
178 @comment ISO
179 @item LANG
180 If this environment variable is defined, its value specifies the locale
181 to use for all purposes except as overridden by the variables above.
182 @end vtable
183
184 @vindex LANGUAGE
185 When developing the message translation functions it was felt that the
186 functionality provided by the variables above is not sufficient.  For
187 example, it should be possible to specify more than one locale name.  
188 Take a Swedish user who better speaks German than English, and a program
189 whose messages are output in English by default.  It should be possible
190 to specify that the first choice of language is Swedish, the second
191 German, and if this also fails to use English.  This is
192 possible with the variable @code{LANGUAGE}.  For further description of
193 this GNU extension see @ref{Using gettextized software}.
194
195 @node Setting the Locale, Standard Locales, Locale Categories, Locales
196 @section How Programs Set the Locale
197
198 A C program inherits its locale environment variables when it starts up.
199 This happens automatically.  However, these variables do not
200 automatically control the locale used by the library functions, because
201 @w{ISO C} says that all programs start by default in the standard @samp{C}
202 locale.  To use the locales specified by the environment, you must call
203 @code{setlocale}.  Call it as follows:
204
205 @smallexample
206 setlocale (LC_ALL, "");
207 @end smallexample
208
209 @noindent
210 to select a locale based on the user choice of the appropriate
211 environment variables.
212
213 @cindex changing the locale
214 @cindex locale, changing
215 You can also use @code{setlocale} to specify a particular locale, for
216 general use or for a specific category.
217
218 @pindex locale.h
219 The symbols in this section are defined in the header file @file{locale.h}.
220
221 @comment locale.h
222 @comment ISO
223 @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
224 The function @code{setlocale} sets the current locale for
225 category @var{category} to @var{locale}.
226
227 If @var{category} is @code{LC_ALL}, this specifies the locale for all
228 purposes.  The other possible values of @var{category} specify an
229 single purpose (@pxref{Locale Categories}).
230
231 You can also use this function to find out the current locale by passing
232 a null pointer as the @var{locale} argument.  In this case,
233 @code{setlocale} returns a string that is the name of the locale
234 currently selected for category @var{category}.
235
236 The string returned by @code{setlocale} can be overwritten by subsequent
237 calls, so you should make a copy of the string (@pxref{Copying and
238 Concatenation}) if you want to save it past any further calls to
239 @code{setlocale}.  (The standard library is guaranteed never to call
240 @code{setlocale} itself.)
241
242 You should not modify the string returned by @code{setlocale}.
243 It might be the same string that was passed as an argument in a
244 previous call to @code{setlocale}.
245
246 When you read the current locale for category @code{LC_ALL}, the value
247 encodes the entire combination of selected locales for all categories.
248 In this case, the value is not just a single locale name.  In fact, we
249 don't make any promises about what it looks like.  But if you specify
250 the same ``locale name'' with @code{LC_ALL} in a subsequent call to
251 @code{setlocale}, it restores the same combination of locale selections.
252
253 To be sure you can use the returned string encoding the currently selected
254 locale at a later time, you must make a copy of the string.  It is not
255 guaranteed that the returned pointer remains valid over time.
256
257 When the @var{locale} argument is not a null pointer, the string returned
258 by @code{setlocale} reflects the newly-modified locale.
259
260 If you specify an empty string for @var{locale}, this means to read the
261 appropriate environment variable and use its value to select the locale
262 for @var{category}.
263
264 If a nonempty string is given for @var{locale}, then the locale of that
265 name is used if possible.
266
267 If you specify an invalid locale name, @code{setlocale} returns a null
268 pointer and leaves the current locale unchanged.
269 @end deftypefun
270
271 Here is an example showing how you might use @code{setlocale} to
272 temporarily switch to a new locale.
273
274 @smallexample
275 #include <stddef.h>
276 #include <locale.h>
277 #include <stdlib.h>
278 #include <string.h>
279
280 void
281 with_other_locale (char *new_locale,
282                    void (*subroutine) (int),
283                    int argument)
284 @{
285   char *old_locale, *saved_locale;
286
287   /* @r{Get the name of the current locale.}  */
288   old_locale = setlocale (LC_ALL, NULL);
289
290   /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */
291   saved_locale = strdup (old_locale);
292   if (saved_locale == NULL)
293     fatal ("Out of memory");
294
295   /* @r{Now change the locale and do some stuff with it.} */
296   setlocale (LC_ALL, new_locale);
297   (*subroutine) (argument);
298
299   /* @r{Restore the original locale.} */
300   setlocale (LC_ALL, saved_locale);
301   free (saved_locale);
302 @}
303 @end smallexample
304
305 @strong{Portability Note:} Some @w{ISO C} systems may define additional
306 locale categories, and future versions of the library will do so.  For
307 portability, assume that any symbol beginning with @samp{LC_} might be
308 defined in @file{locale.h}.
309
310 @node Standard Locales, Locale Information, Setting the Locale, Locales
311 @section Standard Locales
312
313 The only locale names you can count on finding on all operating systems
314 are these three standard ones:
315
316 @table @code
317 @item "C"
318 This is the standard C locale.  The attributes and behavior it provides
319 are specified in the @w{ISO C} standard.  When your program starts up, it
320 initially uses this locale by default.
321
322 @item "POSIX"
323 This is the standard POSIX locale.  Currently, it is an alias for the
324 standard C locale.
325
326 @item ""
327 The empty name says to select a locale based on environment variables.
328 @xref{Locale Categories}.
329 @end table
330
331 Defining and installing named locales is normally a responsibility of
332 the system administrator at your site (or the person who installed the
333 GNU C library).  It is also possible for the user to create private
334 locales.  All this will be discussed later when describing the tool to
335 do so.
336 @comment (@pxref{Building Locale Files}).
337
338 If your program needs to use something other than the @samp{C} locale,
339 it will be more portable if you use whatever locale the user specifies
340 with the environment, rather than trying to specify some non-standard
341 locale explicitly by name.  Remember, different machines might have
342 different sets of locales installed.
343
344 @node Locale Information, Formatting Numbers, Standard Locales, Locales
345 @section Accessing Locale Information
346
347 There are several ways to access locale information.  The simplest
348 way is to let the C library itself do the work.  Several of the
349 functions in this library implicitly access the locale data, and use
350 what information is provided by the currently selected locale.  This is
351 how the locale model is meant to work normally.
352
353 As an example take the @code{strftime} function, which is meant to nicely
354 format date and time information (@pxref{Formatting Date and Time}).
355 Part of the standard information contained in the @code{LC_TIME}
356 category is the names of the months.  Instead of requiring the
357 programmer to take care of providing the translations the
358 @code{strftime} function does this all by itself.  @code{%A}
359 in the format string is replaced by the appropriate weekday
360 name of the locale currently selected by @code{LC_TIME}.  This is an
361 easy example, and wherever possible functions do things automatically
362 in this way.
363
364 But there are quite often situations when there is simply no function
365 to perform the task, or it is simply not possible to do the work
366 automatically.  For these cases it is necessary to access the
367 information in the locale directly.  To do this the C library provides
368 two functions: @code{localeconv} and @code{nl_langinfo}.  The former is
369 part of @w{ISO C} and therefore portable, but has a brain-damaged
370 interface.  The second is part of the Unix interface and is portable in
371 as far as the system follows the Unix standards.
372
373 @menu
374 * The Lame Way to Locale Data::   ISO C's @code{localeconv}.
375 * The Elegant and Fast Way::      X/Open's @code{nl_langinfo}.
376 @end menu
377
378 @node The Lame Way to Locale Data, The Elegant and Fast Way, ,Locale Information
379 @subsection @code{localeconv}: It is portable but @dots{}
380
381 Together with the @code{setlocale} function the @w{ISO C} people
382 invented the @code{localeconv} function.  It is a masterpiece of poor
383 design.  It is expensive to use, not extendable, and not generally
384 usable as it provides access to only @code{LC_MONETARY} and
385 @code{LC_NUMERIC} related information.  Nevertheless, if it is
386 applicable to a given situation it should be used since it is very
387 portable.  The function @code{strfmon} formats monetary amounts
388 according to the selected locale using this information.
389 @pindex locale.h
390 @cindex monetary value formatting
391 @cindex numeric value formatting
392
393 @comment locale.h
394 @comment ISO
395 @deftypefun {struct lconv *} localeconv (void)
396 The @code{localeconv} function returns a pointer to a structure whose
397 components contain information about how numeric and monetary values
398 should be formatted in the current locale.
399
400 You should not modify the structure or its contents.  The structure might
401 be overwritten by subsequent calls to @code{localeconv}, or by calls to
402 @code{setlocale}, but no other function in the library overwrites this
403 value.
404 @end deftypefun
405
406 @comment locale.h
407 @comment ISO
408 @deftp {Data Type} {struct lconv}
409 @code{localeconv}'s return value is of this data type.  Its elements are
410 described in the following subsections.
411 @end deftp
412
413 If a member of the structure @code{struct lconv} has type @code{char},
414 and the value is @code{CHAR_MAX}, it means that the current locale has
415 no value for that parameter.
416
417 @menu
418 * General Numeric::             Parameters for formatting numbers and
419                                  currency amounts.
420 * Currency Symbol::             How to print the symbol that identifies an
421                                  amount of money (e.g. @samp{$}).
422 * Sign of Money Amount::        How to print the (positive or negative) sign
423                                  for a monetary amount, if one exists.
424 @end menu
425
426 @node General Numeric, Currency Symbol, , The Lame Way to Locale Data
427 @subsubsection Generic Numeric Formatting Parameters
428
429 These are the standard members of @code{struct lconv}; there may be
430 others.
431
432 @table @code
433 @item char *decimal_point
434 @itemx char *mon_decimal_point
435 These are the decimal-point separators used in formatting non-monetary
436 and monetary quantities, respectively.  In the @samp{C} locale, the
437 value of @code{decimal_point} is @code{"."}, and the value of
438 @code{mon_decimal_point} is @code{""}.
439 @cindex decimal-point separator
440
441 @item char *thousands_sep
442 @itemx char *mon_thousands_sep
443 These are the separators used to delimit groups of digits to the left of
444 the decimal point in formatting non-monetary and monetary quantities,
445 respectively.  In the @samp{C} locale, both members have a value of
446 @code{""} (the empty string).
447
448 @item char *grouping
449 @itemx char *mon_grouping
450 These are strings that specify how to group the digits to the left of
451 the decimal point.  @code{grouping} applies to non-monetary quantities
452 and @code{mon_grouping} applies to monetary quantities.  Use either
453 @code{thousands_sep} or @code{mon_thousands_sep} to separate the digit
454 groups.
455 @cindex grouping of digits
456
457 Each string is made up of decimal numbers separated by semicolons.
458 Successive numbers (from left to right) give the sizes of successive
459 groups (from right to left, starting at the decimal point).  The last
460 number in the string is used over and over for all the remaining groups.
461
462 If the last integer is @code{-1}, it means that there is no more
463 grouping---or, put another way, any remaining digits form one large
464 group without separators.
465
466 For example, if @code{grouping} is @code{"4;3;2"}, the correct grouping
467 for the number @code{123456787654321} is @samp{12}, @samp{34},
468 @samp{56}, @samp{78}, @samp{765}, @samp{4321}.  This uses a group of 4
469 digits at the end, preceded by a group of 3 digits, preceded by groups
470 of 2 digits (as many as needed).  With a separator of @samp{,}, the
471 number would be printed as @samp{12,34,56,78,765,4321}.
472
473 A value of @code{"3"} indicates repeated groups of three digits, as
474 normally used in the U.S.
475
476 In the standard @samp{C} locale, both @code{grouping} and
477 @code{mon_grouping} have a value of @code{""}.  This value specifies no
478 grouping at all.
479
480 @item char int_frac_digits
481 @itemx char frac_digits
482 These are small integers indicating how many fractional digits (to the
483 right of the decimal point) should be displayed in a monetary value in
484 international and local formats, respectively.  (Most often, both
485 members have the same value.)
486
487 In the standard @samp{C} locale, both of these members have the value
488 @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
489 what to do when you find this value; we recommend printing no
490 fractional digits.  (This locale also specifies the empty string for
491 @code{mon_decimal_point}, so printing any fractional digits would be
492 confusing!)
493 @end table
494
495 @node Currency Symbol, Sign of Money Amount, General Numeric, The Lame Way to Locale Data
496 @subsubsection Printing the Currency Symbol
497 @cindex currency symbols
498
499 These members of the @code{struct lconv} structure specify how to print
500 the symbol to identify a monetary value---the international analog of
501 @samp{$} for US dollars.
502
503 Each country has two standard currency symbols.  The @dfn{local currency
504 symbol} is used commonly within the country, while the
505 @dfn{international currency symbol} is used internationally to refer to
506 that country's currency when it is necessary to indicate the country
507 unambiguously.
508
509 For example, many countries use the dollar as their monetary unit, and
510 when dealing with international currencies it's important to specify
511 that one is dealing with (say) Canadian dollars instead of U.S. dollars
512 or Australian dollars.  But when the context is known to be Canada,
513 there is no need to make this explicit---dollar amounts are implicitly
514 assumed to be in Canadian dollars.
515
516 @table @code
517 @item char *currency_symbol
518 The local currency symbol for the selected locale.
519
520 In the standard @samp{C} locale, this member has a value of @code{""}
521 (the empty string), meaning ``unspecified''.  The ISO standard doesn't
522 say what to do when you find this value; we recommend you simply print
523 the empty string as you would print any other string pointed to by this
524 variable.
525
526 @item char *int_curr_symbol
527 The international currency symbol for the selected locale.
528
529 The value of @code{int_curr_symbol} should normally consist of a
530 three-letter abbreviation determined by the international standard
531 @cite{ISO 4217 Codes for the Representation of Currency and Funds},
532 followed by a one-character separator (often a space).
533
534 In the standard @samp{C} locale, this member has a value of @code{""}
535 (the empty string), meaning ``unspecified''.  We recommend you simply print
536 the empty string as you would print any other string pointed to by this
537 variable.
538
539 @item char p_cs_precedes
540 @itemx char n_cs_precedes
541 These members are @code{1} if the @code{currency_symbol} string should
542 precede the value of a monetary amount, or @code{0} if the string should
543 follow the value.  The @code{p_cs_precedes} member applies to positive
544 amounts (or zero), and the @code{n_cs_precedes} member applies to
545 negative amounts.
546
547 In the standard @samp{C} locale, both of these members have a value of
548 @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
549 what to do when you find this value.  We recommend printing the
550 currency symbol before the amount, which is right for most countries.
551 In other words, treat all nonzero values alike in these members.
552
553 The POSIX standard says that these two members apply to the
554 @code{int_curr_symbol} as well as the @code{currency_symbol}.  The ISO
555 C standard seems to imply that they should apply only to the
556 @code{currency_symbol}---so the @code{int_curr_symbol} should always
557 precede the amount.
558
559 We can only guess which of these (if either) matches the usual
560 conventions for printing international currency symbols.  Our guess is
561 that they should always precede the amount.  If we find out a reliable
562 answer, we will put it here.
563
564 @item char p_sep_by_space
565 @itemx char n_sep_by_space
566 These members are @code{1} if a space should appear between the
567 @code{currency_symbol} string and the amount, or @code{0} if no space
568 should appear.  The @code{p_sep_by_space} member applies to positive
569 amounts (or zero), and the @code{n_sep_by_space} member applies to
570 negative amounts.
571
572 In the standard @samp{C} locale, both of these members have a value of
573 @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
574 what you should do when you find this value; we suggest you treat it as
575 1 (print a space).  In other words, treat all nonzero values alike in
576 these members.
577
578 These members apply only to @code{currency_symbol}.  When you use
579 @code{int_curr_symbol}, you never print an additional space, because
580 @code{int_curr_symbol} itself contains the appropriate separator.
581
582 The POSIX standard says that these two members apply to the
583 @code{int_curr_symbol} as well as the @code{currency_symbol}.  However, an
584 example in the @w{ISO C} standard clearly implies that they should apply
585 only to the @code{currency_symbol}---that the @code{int_curr_symbol}
586 contains any appropriate separator, so you should never print an
587 additional space.
588
589 Based on what we know now, we recommend you ignore these members when
590 printing international currency symbols, and print no extra space.
591 @end table
592
593 @node Sign of Money Amount, , Currency Symbol, The Lame Way to Locale Data
594 @subsubsection Printing the Sign of a Monetary Amount
595
596 These members of the @code{struct lconv} structure specify how to print
597 the sign (if any) of a monetary value.
598
599 @table @code
600 @item char *positive_sign
601 @itemx char *negative_sign
602 These are strings used to indicate positive (or zero) and negative
603 monetary quantities, respectively.
604
605 In the standard @samp{C} locale, both of these members have a value of
606 @code{""} (the empty string), meaning ``unspecified''.
607
608 The ISO standard doesn't say what to do when you find this value; we
609 recommend printing @code{positive_sign} as you find it, even if it is
610 empty.  For a negative value, print @code{negative_sign} as you find it
611 unless both it and @code{positive_sign} are empty, in which case print
612 @samp{-} instead.  (Failing to indicate the sign at all seems rather
613 unreasonable.)
614
615 @item char p_sign_posn
616 @itemx char n_sign_posn
617 These members are small integers that indicate how to
618 position the sign for nonnegative and negative monetary quantities,
619 respectively.  (The string used by the sign is what was specified with
620 @code{positive_sign} or @code{negative_sign}.)  The possible values are
621 as follows:
622
623 @table @code
624 @item 0
625 The currency symbol and quantity should be surrounded by parentheses.
626
627 @item 1
628 Print the sign string before the quantity and currency symbol.
629
630 @item 2
631 Print the sign string after the quantity and currency symbol.
632
633 @item 3
634 Print the sign string right before the currency symbol.
635
636 @item 4
637 Print the sign string right after the currency symbol.
638
639 @item CHAR_MAX
640 ``Unspecified''.  Both members have this value in the standard
641 @samp{C} locale.
642 @end table
643
644 The ISO standard doesn't say what you should do when the value is
645 @code{CHAR_MAX}.  We recommend you print the sign after the currency
646 symbol.
647 @end table
648
649 It is not clear whether you should let these members apply to the
650 international currency format or not.  POSIX says you should, but
651 intuition plus the examples in the @w{ISO C} standard suggest you should
652 not.  We hope that someone who knows the conventions for formatting
653 monetary quantities well will tell us what we should recommend.
654
655 @node The Elegant and Fast Way, , The Lame Way to Locale Data, Locale Information
656 @subsection Pinpoint Access to Locale Data
657
658 When writing the X/Open Portability Guide the authors realized that the
659 @code{localeconv} function is not enough to provide reasonable access to
660 locale information.  The information which was meant to be available
661 in the locale (as later specified in the POSIX.1 standard) requires more
662 ways to access it.  Therefore the @code{nl_langinfo} function
663 was introduced.
664
665 @comment langinfo.h
666 @comment XOPEN
667 @deftypefun {char *} nl_langinfo (nl_item @var{item})
668 The @code{nl_langinfo} function can be used to access individual
669 elements of the locale categories.  Unlike the @code{localeconv}
670 function, which returns all the information, @code{nl_langinfo}
671 lets the caller select what information it requires.  This is very
672 fast and it is not a problem to call this function multiple times.
673
674 A second advantage is that in addition to the numeric and monetary
675 formatting information, information from the
676 @code{LC_TIME} and @code{LC_MESSAGES} categories is available.
677
678 The type @code{nl_type} is defined in @file{nl_types.h}.  The argument
679 @var{item} is a numeric value defined in the header @file{langinfo.h}.
680 The X/Open standard defines the following values:
681
682 @vtable @code
683 @item ABDAY_1
684 @itemx ABDAY_2
685 @itemx ABDAY_3
686 @itemx ABDAY_4
687 @itemx ABDAY_5
688 @itemx ABDAY_6
689 @itemx ABDAY_7
690 @code{nl_langinfo} returns the abbreviated weekday name.  @code{ABDAY_1}
691 corresponds to Sunday.
692 @item DAY_1
693 @itemx DAY_2
694 @itemx DAY_3
695 @itemx DAY_4
696 @itemx DAY_5
697 @itemx DAY_6
698 @itemx DAY_7
699 Similar to @code{ABDAY_1} etc., but here the return value is the
700 unabbreviated weekday name.
701 @item ABMON_1
702 @itemx ABMON_2
703 @itemx ABMON_3
704 @itemx ABMON_4
705 @itemx ABMON_5
706 @itemx ABMON_6
707 @itemx ABMON_7
708 @itemx ABMON_8
709 @itemx ABMON_9
710 @itemx ABMON_10
711 @itemx ABMON_11
712 @itemx ABMON_12
713 The return value is abbreviated name of the month.  @code{ABMON_1}
714 corresponds to January.
715 @item MON_1
716 @itemx MON_2
717 @itemx MON_3
718 @itemx MON_4
719 @itemx MON_5
720 @itemx MON_6
721 @itemx MON_7
722 @itemx MON_8
723 @itemx MON_9
724 @itemx MON_10
725 @itemx MON_11
726 @itemx MON_12
727 Similar to @code{ABMON_1} etc., but here the month names are not abbreviated.
728 Here the first value @code{MON_1} also corresponds to January.
729 @item AM_STR
730 @itemx PM_STR
731 The return values are strings which can be used in the representation of time
732 as an hour from 1 to 12 plus an am/pm specifier.
733
734 Note that in locales which do not use this time representation
735 these strings might be empty, in which case the am/pm format
736 cannot be used at all.
737 @item D_T_FMT
738 The return value can be used as a format string for @code{strftime} to
739 represent time and date in a locale-specific way.
740 @item D_FMT
741 The return value can be used as a format string for @code{strftime} to
742 represent a date in a locale-specific way.
743 @item T_FMT
744 The return value can be used as a format string for @code{strftime} to
745 represent time in a locale-specific way.
746 @item T_FMT_AMPM
747 The return value can be used as a format string for @code{strftime} to
748 represent time in the am/pm format.
749
750 Note that if the am/pm format does not make any sense for the
751 selected locale, the return value might be the same as the one for
752 @code{T_FMT}.
753 @item ERA
754 The return value represents the era used in the current locale.
755
756 Most locales do not define this value.  An example of a locale which
757 does define this value is the Japanese one.  In Japan, the traditional
758 representation of dates includes the name of the era corresponding to
759 the then-emperor's reign.
760
761 Normally it should not be necessary to use this value directly.
762 Specifying the @code{E} modifier in their format strings causes the
763 @code{strftime} functions to use this information.  The format of the
764 returned string is not specified, and therefore you should not assume
765 knowledge of it on different systems.
766 @item ERA_YEAR
767 The return value gives the year in the relevant era of the locale.
768 As for @code{ERA} it should not be necessary to use this value directly.
769 @item ERA_D_T_FMT
770 This return value can be used as a format string for @code{strftime} to
771 represent dates and times in a locale-specific era-based way.
772 @item ERA_D_FMT
773 This return value can be used as a format string for @code{strftime} to
774 represent a date in a locale-specific era-based way.
775 @item ERA_T_FMT
776 This return value can be used as a format string for @code{strftime} to
777 represent time in a locale-specific era-based way.
778 @item ALT_DIGITS
779 The return value is a representation of up to @math{100} values used to
780 represent the values @math{0} to @math{99}.  As for @code{ERA} this
781 value is not intended to be used directly, but instead indirectly
782 through the @code{strftime} function.  When the modifier @code{O} is
783 used in a format which would otherwise use numerals to represent hours,
784 minutes, seconds, weekdays, months, or weeks, the appropriate value for
785 the locale is used instead.
786 @item INT_CURR_SYMBOL
787 The same as the value returned by @code{localeconv} in the
788 @code{int_curr_symbol} element of the @code{struct lconv}.
789 @item CURRENCY_SYMBOL
790 @itemx CRNCYSTR
791 The same as the value returned by @code{localeconv} in the
792 @code{currency_symbol} element of the @code{struct lconv}.
793
794 @code{CRNCYSTR} is a deprecated alias still required by Unix98.
795 @item MON_DECIMAL_POINT
796 The same as the value returned by @code{localeconv} in the
797 @code{mon_decimal_point} element of the @code{struct lconv}.
798 @item MON_THOUSANDS_SEP
799 The same as the value returned by @code{localeconv} in the
800 @code{mon_thousands_sep} element of the @code{struct lconv}.
801 @item MON_GROUPING
802 The same as the value returned by @code{localeconv} in the
803 @code{mon_grouping} element of the @code{struct lconv}.
804 @item POSITIVE_SIGN
805 The same as the value returned by @code{localeconv} in the
806 @code{positive_sign} element of the @code{struct lconv}.
807 @item NEGATIVE_SIGN
808 The same as the value returned by @code{localeconv} in the
809 @code{negative_sign} element of the @code{struct lconv}.
810 @item INT_FRAC_DIGITS
811 The same as the value returned by @code{localeconv} in the
812 @code{int_frac_digits} element of the @code{struct lconv}.
813 @item FRAC_DIGITS
814 The same as the value returned by @code{localeconv} in the
815 @code{frac_digits} element of the @code{struct lconv}.
816 @item P_CS_PRECEDES
817 The same as the value returned by @code{localeconv} in the
818 @code{p_cs_precedes} element of the @code{struct lconv}.
819 @item P_SEP_BY_SPACE
820 The same as the value returned by @code{localeconv} in the
821 @code{p_sep_by_space} element of the @code{struct lconv}.
822 @item N_CS_PRECEDES
823 The same as the value returned by @code{localeconv} in the
824 @code{n_cs_precedes} element of the @code{struct lconv}.
825 @item N_SEP_BY_SPACE
826 The same as the value returned by @code{localeconv} in the
827 @code{n_sep_by_space} element of the @code{struct lconv}.
828 @item P_SIGN_POSN
829 The same as the value returned by @code{localeconv} in the
830 @code{p_sign_posn} element of the @code{struct lconv}.
831 @item N_SIGN_POSN
832 The same as the value returned by @code{localeconv} in the
833 @code{n_sign_posn} element of the @code{struct lconv}.
834 @item DECIMAL_POINT
835 @itemx RADIXCHAR
836 The same as the value returned by @code{localeconv} in the
837 @code{decimal_point} element of the @code{struct lconv}.
838
839 The name @code{RADIXCHAR} is a deprecated alias still used in Unix98.
840 @item THOUSANDS_SEP
841 @itemx THOUSEP
842 The same as the value returned by @code{localeconv} in the
843 @code{thousands_sep} element of the @code{struct lconv}.
844
845 The name @code{THOUSEP} is a deprecated alias still used in Unix98.
846 @item GROUPING
847 The same as the value returned by @code{localeconv} in the
848 @code{grouping} element of the @code{struct lconv}.
849 @item YESEXPR
850 The return value is a regular expression which can be used with the
851 @code{regex} function to recognize a positive response to a yes/no
852 question.
853 @item NOEXPR
854 The return value is a regular expression which can be used with the
855 @code{regex} function to recognize a negative response to a yes/no
856 question.
857 @item YESSTR
858 The return value is a locale-specific translation of the positive response
859 to a yes/no question.
860
861 Using this value is deprecated since it is a very special case of
862 message translation, and is better handled by the message
863 translation functions (@pxref{Message Translation}).
864 @item NOSTR
865 The return value is a locale-specific translation of the negative response
866 to a yes/no question.  What is said for @code{YESSTR} is also true here.
867 @end vtable
868
869 The file @file{langinfo.h} defines a lot more symbols but none of them
870 is official.  Using them is not portable, and the format of the
871 return values might change.  Therefore we recommended you not use
872 them.
873
874 Note that the return value for any valid argument can be used for
875 in all situations (with the possible exception of the am/pm time formatting
876 codes).  If the user has not selected any locale for the
877 appropriate category, @code{nl_langinfo} returns the information from the
878 @code{"C"} locale.  It is therefore possible to use this function as
879 shown in the example below.
880
881 If the argument @var{item} is not valid, the global variable @var{errno}
882 is set to @code{EINVAL} and a @code{NULL} pointer is returned.
883 @end deftypefun
884
885 An example of @code{nl_langinfo} usage is a function which has to
886 print a given date and time in a locale-specific way.  At first one
887 might think that, since @code{strftime} internally uses the locale
888 information, writing something like the following is enough:
889
890 @smallexample
891 size_t
892 i18n_time_n_data (char *s, size_t len, const struct tm *tp)
893 @{
894   return strftime (s, len, "%X %D", tp);
895 @}
896 @end smallexample
897
898 The format contains no weekday or month names and therefore is
899 internationally usable.  Wrong!  The output produced is something like
900 @code{"hh:mm:ss MM/DD/YY"}.  This format is only recognizable in the
901 USA.  Other countries use different formats.  Therefore the function
902 should be rewritten like this:
903
904 @smallexample
905 size_t
906 i18n_time_n_data (char *s, size_t len, const struct tm *tp)
907 @{
908   return strftime (s, len, nl_langinfo (D_T_FMT), tp);
909 @}
910 @end smallexample
911
912 Now it uses the date and time format of the locale
913 selected when the program runs.  If the user selects the locale
914 correctly there should never be a misunderstanding over the time and
915 date format.
916
917 @node Formatting Numbers, , Locale Information, Locales
918 @section A dedicated function to format numbers
919
920 We have seen that the structure returned by @code{localeconv} as well as
921 the values given to @code{nl_langinfo} allow you to retrieve the various
922 pieces of locale-specific information to format numbers and monetary
923 amounts.  We have also seen that the underlying rules are quite complex.
924
925 Therefore the X/Open standards introduce a function which uses such
926 locale information, making it easier for the user to format
927 numbers according to these rules.
928
929 @deftypefun ssize_t strfmon (char *@var{s}, size_t @var{maxsize}, const char *@var{format}, @dots{})
930 The @code{strfmon} function is similar to the @code{strftime} function
931 in that it takes a buffer, its size, a format string,
932 and values to write into the buffer as text in a form specified
933 by the format string.  Like @code{strftime}, the function
934 also returns the number of bytes written into the buffer.
935
936 There are two differences: @code{strfmon} can take more than one
937 argument, and, of course, the format specification is different.  Like
938 @code{strftime}, the format string consists of normal text, which is
939 output as is, and format specifiers, which are indicated by a @samp{%}.
940 Immediately after the @samp{%}, you can optionally specify various flags
941 and formatting information before the main formatting character, in a
942 similar way to @code{printf}:
943
944 @itemize @bullet
945 @item
946 Immediately following the @samp{%} there can be one or more of the
947 following flags:
948 @table @asis
949 @item @samp{=@var{f}}
950 The single byte character @var{f} is used for this field as the numeric
951 fill character.  By default this character is a space character.
952 Filling with this character is only performed if a left precision
953 is specified.  It is not just to fill to the given field width.
954 @item @samp{^}
955 The number is printed without grouping the digits according to the rules
956 of the current locale.  By default grouping is enabled.
957 @item @samp{+}, @samp{(}
958 At most one of these flags can be used.  They select which format to
959 represent the sign of a currency amount.  By default, and if
960 @samp{+} is given, the locale equivalent of @math{+}/@math{-} is used.  If
961 @samp{(} is given, negative amounts are enclosed in parentheses.  The
962 exact format is determined by the values of the @code{LC_MONETARY}
963 category of the locale selected at program runtime.
964 @item @samp{!}
965 The output will not contain the currency symbol.
966 @item @samp{-}
967 The output will be formatted left-justified instead of right-justified if
968 it does not fill the entire field width.
969 @end table
970 @end itemize
971
972 The next part of a specification is an optional field width.  If no
973 width is specified @math{0} is taken.  During output, the function first
974 determines how much space is required.  If it requires at least as many
975 characters as given by the field width, it is output using as much space
976 as necessary.  Otherwise, it is extended to use the full width by
977 filling with the space character.  The presence or absence of the
978 @samp{-} flag determines the side at which such padding occurs.  If
979 present, the spaces are added at the right making the output
980 left-justified, and vice versa.
981
982 So far the format looks familiar, being similar to the @code{printf} and
983 @code{strftime} formats.  However, the next two optional fields
984 introduce something new.  The first one is a @samp{#} character followed
985 by a decimal digit string.  The value of the digit string specifies the
986 number of @emph{digit} positions to the left of the decimal point (or
987 equivalent).  This does @emph{not} include the grouping character when
988 the @samp{^} flag is not given.  If the space needed to print the number
989 does not fill the whole width, the field is padded at the left side with
990 the fill character, which can be selected using the @samp{=} flag and by
991 default is a space.  For example, if the field width is selected as 6
992 and the number is @math{123}, the fill character is @samp{*} the result
993 will be @samp{***123}.
994
995 The second optional field starts with a @samp{.} (period) and consists
996 of another decimal digit string.  Its value describes the number of
997 characters printed after the decimal point.  The default is selected
998 from the current locale (@code{frac_digits}, @code{int_frac_digits}, see
999 @pxref{General Numeric}).  If the exact representation needs more digits
1000 than given by the field width, the displayed value is rounded.  If the
1001 number of fractional digits is selected to be zero, no decimal point is
1002 printed.
1003
1004 As a GNU extension, the @code{strfmon} implementation in the GNU libc
1005 allows an optional @samp{L} next as a format modifier.  If this modifier
1006 is given, the argument is expected to be a @code{long double} instead of
1007 a @code{double} value.
1008
1009 Finally, the last component is a format specifier.  There are three
1010 specifiers defined:
1011
1012 @table @asis
1013 @item @samp{i}
1014 Use the locale's rules for formatting an international currency value.
1015 @item @samp{n}
1016 Use the locale's rules for formatting a national currency value.
1017 @item @samp{%}
1018 Place a @samp{%} in the output.  There must be no flag, width
1019 specifier or modifier given, only @samp{%%} is allowed.
1020 @end table
1021
1022 As for @code{printf}, the function reads the format string
1023 from left to right and uses the values passed to the function following
1024 the format string.  The values are expected to be either of type
1025 @code{double} or @code{long double}, depending on the presence of the
1026 modifier @samp{L}.  The result is stored in the buffer pointed to by
1027 @var{s}.  At most @var{maxsize} characters are stored.
1028
1029 The return value of the function is the number of characters stored in
1030 @var{s}, including the terminating @code{NULL} byte.  If the number of
1031 characters stored would exceed @var{maxsize}, the function returns
1032 @math{-1} and the content of the buffer @var{s} is unspecified.  In this
1033 case @code{errno} is set to @code{E2BIG}.
1034 @end deftypefun
1035
1036 A few examples should make clear how the function works.  It is
1037 assumed that all the following pieces of code are executed in a program
1038 which uses the USA locale (@code{en_US}).  The simplest
1039 form of the format is this:
1040
1041 @smallexample
1042 strfmon (buf, 100, "@@%n@@%n@@%n@@", 123.45, -567.89, 12345.678);
1043 @end smallexample
1044
1045 @noindent
1046 The output produced is
1047 @smallexample
1048 "@@$123.45@@-$567.89@@$12,345.68@@"
1049 @end smallexample
1050
1051 We can notice several things here.  First, the widths of the output
1052 numbers are different.  We have not specified a width in the format
1053 string, and so this is no wonder.  Second, the third number is printed
1054 using thousands separators.  The thousands separator for the
1055 @code{en_US} locale is a comma.  The number is also rounded.
1056 @math{.678} is rounded to @math{.68} since the format does not specify a
1057 precision and the default value in the locale is @math{2}.  Finally,
1058 note that the national currency symbol is printed since @samp{%n} was
1059 used, not @samp{i}.  The next example shows how we can align the output.
1060
1061 @smallexample
1062 strfmon (buf, 100, "@@%=*11n@@%=*11n@@%=*11n@@", 123.45, -567.89, 12345.678);
1063 @end smallexample
1064
1065 @noindent
1066 The output this time is:
1067
1068 @smallexample
1069 "@@    $123.45@@   -$567.89@@ $12,345.68@@"
1070 @end smallexample
1071
1072 Two things stand out.  Firstly, all fields have the same width (eleven
1073 characters) since this is the width given in the format and since no
1074 number required more characters to be printed.  The second important
1075 point is that the fill character is not used.  This is correct since the
1076 white space was not used to achieve a precision given by a @samp{#}
1077 modifier, but instead to fill to the given width.  The difference
1078 becomes obvious if we now add a width specification.
1079
1080 @smallexample
1081 strfmon (buf, 100, "@@%=*11#5n@@%=*11#5n@@%=*11#5n@@",
1082          123.45, -567.89, 12345.678);
1083 @end smallexample
1084
1085 @noindent
1086 The output is
1087
1088 @smallexample
1089 "@@ $***123.45@@-$***567.89@@ $12,456.68@@"
1090 @end smallexample
1091
1092 Here we can see that all the currency symbols are now aligned, and that
1093 the space between the currency sign and the number is filled with the
1094 selected fill character.  Note that although the width is selected to be
1095 @math{5} and @math{123.45} has three digits left of the decimal point,
1096 the space is filled with three asterisks.  This is correct since, as
1097 explained above, the width does not include the positions used to store
1098 thousands separators.  One last example should explain the remaining
1099 functionality.
1100
1101 @smallexample
1102 strfmon (buf, 100, "@@%=0(16#5.3i@@%=0(16#5.3i@@%=0(16#5.3i@@",
1103          123.45, -567.89, 12345.678);
1104 @end smallexample
1105
1106 @noindent
1107 This rather complex format string produces the following output:
1108
1109 @smallexample
1110 "@@ USD 000123,450 @@(USD 000567.890)@@ USD 12,345.678 @@"
1111 @end smallexample
1112
1113 The most noticeable change is the alternative way of representing
1114 negative numbers.  In financial circles this is often done using
1115 parentheses, and this is what the @samp{(} flag selected.  The fill
1116 character is now @samp{0}.  Note that this @samp{0} character is not
1117 regarded as a numeric zero, and therefore the first and second numbers
1118 are not printed using a thousands separator.  Since we used the format
1119 specifier @samp{i} instead of @samp{n}, the international form of the
1120 currency symbol is used.  This is a four letter string, in this case
1121 @code{"USD "}.  The last point is that since the precision right of the
1122 decimal point is selected to be three, the first and second numbers are
1123 printed with an extra zero at the end and the third number is printed
1124 without rounding.