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
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
10 @cindex internationalization
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).
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.
24 * Effects of Locale:: Actions affected by the choice of
26 * Choosing Locale:: How the user specifies a locale.
27 * Locale Categories:: Different purposes for which you can
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.
36 @node Effects of Locale, Choosing Locale, , Locales
37 @section What Effects a Locale Has
39 Each locale specifies conventions for several purposes, including the
44 What multibyte character sequences are valid, and how they are
45 interpreted (@pxref{Character Set Handling}).
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}).
53 The collating sequence for the local language and character set
54 (@pxref{Collation Functions}).
57 Formatting of numbers and currency amounts (@pxref{General Numeric}).
60 Formatting of dates and times (@pxref{Formatting Calendar Time}).
63 What language to use for output, including error messages
64 (@pxref{Message Translation}).
67 What language to use for user answers to yes-or-no questions.
70 What language to use for more complex user input.
71 (The C library doesn't yet help you implement this.)
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.
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.
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.
90 @node Choosing Locale, Locale Categories, Effects of Locale, Locales
91 @section Choosing a Locale
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
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}).
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.
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.
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.
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
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}.
135 This category applies to collation of strings (functions @code{strcoll}
136 and @code{strxfrm}); see @ref{Collation Functions}.
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}.
148 This category applies to formatting monetary values; see @ref{General Numeric}.
153 This category applies to formatting numeric values that are not
154 monetary; see @ref{General Numeric}.
159 This category applies to formatting date and time values; see
160 @ref{Formatting Calendar Time}.
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}).
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}.
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.
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}.
195 @node Setting the Locale, Standard Locales, Locale Categories, Locales
196 @section How Programs Set the Locale
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:
206 setlocale (LC_ALL, "");
210 to select a locale based on the user choice of the appropriate
211 environment variables.
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.
219 The symbols in this section are defined in the header file @file{locale.h}.
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}.
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}).
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}.
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.)
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}.
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.
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.
257 When the @var{locale} argument is not a null pointer, the string returned
258 by @code{setlocale} reflects the newly-modified locale.
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
264 If a nonempty string is given for @var{locale}, then the locale of that
265 name is used if possible.
267 If you specify an invalid locale name, @code{setlocale} returns a null
268 pointer and leaves the current locale unchanged.
271 Here is an example showing how you might use @code{setlocale} to
272 temporarily switch to a new locale.
281 with_other_locale (char *new_locale,
282 void (*subroutine) (int),
285 char *old_locale, *saved_locale;
287 /* @r{Get the name of the current locale.} */
288 old_locale = setlocale (LC_ALL, NULL);
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");
295 /* @r{Now change the locale and do some stuff with it.} */
296 setlocale (LC_ALL, new_locale);
297 (*subroutine) (argument);
299 /* @r{Restore the original locale.} */
300 setlocale (LC_ALL, saved_locale);
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}.
310 @node Standard Locales, Locale Information, Setting the Locale, Locales
311 @section Standard Locales
313 The only locale names you can count on finding on all operating systems
314 are these three standard ones:
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.
323 This is the standard POSIX locale. Currently, it is an alias for the
327 The empty name says to select a locale based on environment variables.
328 @xref{Locale Categories}.
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
336 @comment (@pxref{Building Locale Files}).
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.
344 @node Locale Information, Formatting Numbers, Standard Locales, Locales
345 @section Accessing Locale Information
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.
353 As an example take the @code{strftime} function, which is meant to nicely
354 format date and time information (@pxref{Formatting Calendar 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
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.
374 * The Lame Way to Locale Data:: ISO C's @code{localeconv}.
375 * The Elegant and Fast Way:: X/Open's @code{nl_langinfo}.
378 @node The Lame Way to Locale Data, The Elegant and Fast Way, ,Locale Information
379 @subsection @code{localeconv}: It is portable but @dots{}
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.
390 @cindex monetary value formatting
391 @cindex numeric value formatting
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.
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
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.
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.
418 * General Numeric:: Parameters for formatting numbers and
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.
426 @node General Numeric, Currency Symbol, , The Lame Way to Locale Data
427 @subsubsection Generic Numeric Formatting Parameters
429 These are the standard members of @code{struct lconv}; there may be
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
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).
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
455 @cindex grouping of digits
457 Each member of these strings is to be interpreted as an integer value of
458 type @code{char}. Successive numbers (from left to right) give the
459 sizes of successive groups (from right to left, starting at the decimal
460 point.) The last member is either @code{0}, in which case the previous
461 member is used over and over again for all the remaining groups, or
462 @code{CHAR_MAX}, in which case there is no more grouping---or, put
463 another way, any remaining digits form one large group without
466 For example, if @code{grouping} is @code{"\04\03\02"}, the correct
467 grouping 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}.
473 A value of @code{"\03"} indicates repeated groups of three digits, as
474 normally used in the U.S.
476 In the standard @samp{C} locale, both @code{grouping} and
477 @code{mon_grouping} have a value of @code{""}. This value specifies no
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.)
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
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
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.
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
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.
517 @item char *currency_symbol
518 The local currency symbol for the selected locale.
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
526 @item char *int_curr_symbol
527 The international currency symbol for the selected locale.
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).
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
539 @item char p_cs_precedes
540 @itemx char n_cs_precedes
541 @itemx char int_p_cs_precedes
542 @itemx char int_n_cs_precedes
543 These members are @code{1} if the @code{currency_symbol} or
544 @code{int_curr_symbol} strings should precede the value of a monetary
545 amount, or @code{0} if the strings should follow the value. The
546 @code{p_cs_precedes} and @code{int_p_cs_precedes} members apply to
547 positive amounts (or zero), and the @code{n_cs_precedes} and
548 @code{int_n_cs_precedes} members apply to negative amounts.
550 In the standard @samp{C} locale, all of these members have a value of
551 @code{CHAR_MAX}, meaning ``unspecified''. The ISO standard doesn't say
552 what to do when you find this value. We recommend printing the
553 currency symbol before the amount, which is right for most countries.
554 In other words, treat all nonzero values alike in these members.
556 The members with the @code{int_} prefix apply to the
557 @code{int_curr_symbol} while the other two apply to
558 @code{currency_symbol}.
560 @item char p_sep_by_space
561 @itemx char n_sep_by_space
562 @itemx char int_p_sep_by_space
563 @itemx char int_n_sep_by_space
564 These members are @code{1} if a space should appear between the
565 @code{currency_symbol} or @code{int_curr_symbol} strings and the
566 amount, or @code{0} if no space should appear. The
567 @code{p_sep_by_space} and @code{int_p_sep_by_space} members apply to
568 positive amounts (or zero), and the @code{n_sep_by_space} and
569 @code{int_n_sep_by_space} members apply to negative amounts.
571 In the standard @samp{C} locale, all of these members have a value of
572 @code{CHAR_MAX}, meaning ``unspecified''. The ISO standard doesn't say
573 what you should do when you find this value; we suggest you treat it as
574 1 (print a space). In other words, treat all nonzero values alike in
577 The members with the @code{int_} prefix apply to the
578 @code{int_curr_symbol} while the other two apply to
579 @code{currency_symbol}. There is one specialty with the
580 @code{int_curr_symbol}, though. Since all legal values contain a space
581 at the end the string one either printf this space (if the currency
582 symbol must appear in front and must be separated) or one has to avoid
583 printing this character at all (especially when at the end of the
587 @node Sign of Money Amount, , Currency Symbol, The Lame Way to Locale Data
588 @subsubsection Printing the Sign of a Monetary Amount
590 These members of the @code{struct lconv} structure specify how to print
591 the sign (if any) of a monetary value.
594 @item char *positive_sign
595 @itemx char *negative_sign
596 These are strings used to indicate positive (or zero) and negative
597 monetary quantities, respectively.
599 In the standard @samp{C} locale, both of these members have a value of
600 @code{""} (the empty string), meaning ``unspecified''.
602 The ISO standard doesn't say what to do when you find this value; we
603 recommend printing @code{positive_sign} as you find it, even if it is
604 empty. For a negative value, print @code{negative_sign} as you find it
605 unless both it and @code{positive_sign} are empty, in which case print
606 @samp{-} instead. (Failing to indicate the sign at all seems rather
609 @item char p_sign_posn
610 @itemx char n_sign_posn
611 @itemx char int_p_sign_posn
612 @itemx char int_n_sign_posn
613 These members are small integers that indicate how to
614 position the sign for nonnegative and negative monetary quantities,
615 respectively. (The string used by the sign is what was specified with
616 @code{positive_sign} or @code{negative_sign}.) The possible values are
621 The currency symbol and quantity should be surrounded by parentheses.
624 Print the sign string before the quantity and currency symbol.
627 Print the sign string after the quantity and currency symbol.
630 Print the sign string right before the currency symbol.
633 Print the sign string right after the currency symbol.
636 ``Unspecified''. Both members have this value in the standard
640 The ISO standard doesn't say what you should do when the value is
641 @code{CHAR_MAX}. We recommend you print the sign after the currency
644 The members with the @code{int_} prefix apply to the
645 @code{int_curr_symbol} while the other two apply to
646 @code{currency_symbol}.
649 @node The Elegant and Fast Way, , The Lame Way to Locale Data, Locale Information
650 @subsection Pinpoint Access to Locale Data
652 When writing the X/Open Portability Guide the authors realized that the
653 @code{localeconv} function is not enough to provide reasonable access to
654 locale information. The information which was meant to be available
655 in the locale (as later specified in the POSIX.1 standard) requires more
656 ways to access it. Therefore the @code{nl_langinfo} function
661 @deftypefun {char *} nl_langinfo (nl_item @var{item})
662 The @code{nl_langinfo} function can be used to access individual
663 elements of the locale categories. Unlike the @code{localeconv}
664 function, which returns all the information, @code{nl_langinfo}
665 lets the caller select what information it requires. This is very
666 fast and it is not a problem to call this function multiple times.
668 A second advantage is that in addition to the numeric and monetary
669 formatting information, information from the
670 @code{LC_TIME} and @code{LC_MESSAGES} categories is available.
672 The type @code{nl_type} is defined in @file{nl_types.h}. The argument
673 @var{item} is a numeric value defined in the header @file{langinfo.h}.
674 The X/Open standard defines the following values:
684 @code{nl_langinfo} returns the abbreviated weekday name. @code{ABDAY_1}
685 corresponds to Sunday.
693 Similar to @code{ABDAY_1} etc., but here the return value is the
694 unabbreviated weekday name.
707 The return value is abbreviated name of the month. @code{ABMON_1}
708 corresponds to January.
721 Similar to @code{ABMON_1} etc., but here the month names are not abbreviated.
722 Here the first value @code{MON_1} also corresponds to January.
725 The return values are strings which can be used in the representation of time
726 as an hour from 1 to 12 plus an am/pm specifier.
728 Note that in locales which do not use this time representation
729 these strings might be empty, in which case the am/pm format
730 cannot be used at all.
732 The return value can be used as a format string for @code{strftime} to
733 represent time and date in a locale-specific way.
735 The return value can be used as a format string for @code{strftime} to
736 represent a date in a locale-specific way.
738 The return value can be used as a format string for @code{strftime} to
739 represent time in a locale-specific way.
741 The return value can be used as a format string for @code{strftime} to
742 represent time in the am/pm format.
744 Note that if the am/pm format does not make any sense for the
745 selected locale, the return value might be the same as the one for
748 The return value represents the era used in the current locale.
750 Most locales do not define this value. An example of a locale which
751 does define this value is the Japanese one. In Japan, the traditional
752 representation of dates includes the name of the era corresponding to
753 the then-emperor's reign.
755 Normally it should not be necessary to use this value directly.
756 Specifying the @code{E} modifier in their format strings causes the
757 @code{strftime} functions to use this information. The format of the
758 returned string is not specified, and therefore you should not assume
759 knowledge of it on different systems.
761 The return value gives the year in the relevant era of the locale.
762 As for @code{ERA} it should not be necessary to use this value directly.
764 This return value can be used as a format string for @code{strftime} to
765 represent dates and times in a locale-specific era-based way.
767 This return value can be used as a format string for @code{strftime} to
768 represent a date in a locale-specific era-based way.
770 This return value can be used as a format string for @code{strftime} to
771 represent time in a locale-specific era-based way.
773 The return value is a representation of up to @math{100} values used to
774 represent the values @math{0} to @math{99}. As for @code{ERA} this
775 value is not intended to be used directly, but instead indirectly
776 through the @code{strftime} function. When the modifier @code{O} is
777 used in a format which would otherwise use numerals to represent hours,
778 minutes, seconds, weekdays, months, or weeks, the appropriate value for
779 the locale is used instead.
780 @item INT_CURR_SYMBOL
781 The same as the value returned by @code{localeconv} in the
782 @code{int_curr_symbol} element of the @code{struct lconv}.
783 @item CURRENCY_SYMBOL
785 The same as the value returned by @code{localeconv} in the
786 @code{currency_symbol} element of the @code{struct lconv}.
788 @code{CRNCYSTR} is a deprecated alias still required by Unix98.
789 @item MON_DECIMAL_POINT
790 The same as the value returned by @code{localeconv} in the
791 @code{mon_decimal_point} element of the @code{struct lconv}.
792 @item MON_THOUSANDS_SEP
793 The same as the value returned by @code{localeconv} in the
794 @code{mon_thousands_sep} element of the @code{struct lconv}.
796 The same as the value returned by @code{localeconv} in the
797 @code{mon_grouping} element of the @code{struct lconv}.
799 The same as the value returned by @code{localeconv} in the
800 @code{positive_sign} element of the @code{struct lconv}.
802 The same as the value returned by @code{localeconv} in the
803 @code{negative_sign} element of the @code{struct lconv}.
804 @item INT_FRAC_DIGITS
805 The same as the value returned by @code{localeconv} in the
806 @code{int_frac_digits} element of the @code{struct lconv}.
808 The same as the value returned by @code{localeconv} in the
809 @code{frac_digits} element of the @code{struct lconv}.
811 The same as the value returned by @code{localeconv} in the
812 @code{p_cs_precedes} element of the @code{struct lconv}.
814 The same as the value returned by @code{localeconv} in the
815 @code{p_sep_by_space} element of the @code{struct lconv}.
817 The same as the value returned by @code{localeconv} in the
818 @code{n_cs_precedes} element of the @code{struct lconv}.
820 The same as the value returned by @code{localeconv} in the
821 @code{n_sep_by_space} element of the @code{struct lconv}.
823 The same as the value returned by @code{localeconv} in the
824 @code{p_sign_posn} element of the @code{struct lconv}.
826 The same as the value returned by @code{localeconv} in the
827 @code{n_sign_posn} element of the @code{struct lconv}.
830 The same as the value returned by @code{localeconv} in the
831 @code{decimal_point} element of the @code{struct lconv}.
833 The name @code{RADIXCHAR} is a deprecated alias still used in Unix98.
836 The same as the value returned by @code{localeconv} in the
837 @code{thousands_sep} element of the @code{struct lconv}.
839 The name @code{THOUSEP} is a deprecated alias still used in Unix98.
841 The same as the value returned by @code{localeconv} in the
842 @code{grouping} element of the @code{struct lconv}.
844 The return value is a regular expression which can be used with the
845 @code{regex} function to recognize a positive response to a yes/no
848 The return value is a regular expression which can be used with the
849 @code{regex} function to recognize a negative response to a yes/no
852 The return value is a locale-specific translation of the positive response
853 to a yes/no question.
855 Using this value is deprecated since it is a very special case of
856 message translation, and is better handled by the message
857 translation functions (@pxref{Message Translation}).
859 The return value is a locale-specific translation of the negative response
860 to a yes/no question. What is said for @code{YESSTR} is also true here.
863 The file @file{langinfo.h} defines a lot more symbols but none of them
864 is official. Using them is not portable, and the format of the
865 return values might change. Therefore we recommended you not use
868 Note that the return value for any valid argument can be used for
869 in all situations (with the possible exception of the am/pm time formatting
870 codes). If the user has not selected any locale for the
871 appropriate category, @code{nl_langinfo} returns the information from the
872 @code{"C"} locale. It is therefore possible to use this function as
873 shown in the example below.
875 If the argument @var{item} is not valid, a pointer to an empty string is
879 An example of @code{nl_langinfo} usage is a function which has to
880 print a given date and time in a locale-specific way. At first one
881 might think that, since @code{strftime} internally uses the locale
882 information, writing something like the following is enough:
886 i18n_time_n_data (char *s, size_t len, const struct tm *tp)
888 return strftime (s, len, "%X %D", tp);
892 The format contains no weekday or month names and therefore is
893 internationally usable. Wrong! The output produced is something like
894 @code{"hh:mm:ss MM/DD/YY"}. This format is only recognizable in the
895 USA. Other countries use different formats. Therefore the function
896 should be rewritten like this:
900 i18n_time_n_data (char *s, size_t len, const struct tm *tp)
902 return strftime (s, len, nl_langinfo (D_T_FMT), tp);
906 Now it uses the date and time format of the locale
907 selected when the program runs. If the user selects the locale
908 correctly there should never be a misunderstanding over the time and
911 @node Formatting Numbers, , Locale Information, Locales
912 @section A dedicated function to format numbers
914 We have seen that the structure returned by @code{localeconv} as well as
915 the values given to @code{nl_langinfo} allow you to retrieve the various
916 pieces of locale-specific information to format numbers and monetary
917 amounts. We have also seen that the underlying rules are quite complex.
919 Therefore the X/Open standards introduce a function which uses such
920 locale information, making it easier for the user to format
921 numbers according to these rules.
923 @deftypefun ssize_t strfmon (char *@var{s}, size_t @var{maxsize}, const char *@var{format}, @dots{})
924 The @code{strfmon} function is similar to the @code{strftime} function
925 in that it takes a buffer, its size, a format string,
926 and values to write into the buffer as text in a form specified
927 by the format string. Like @code{strftime}, the function
928 also returns the number of bytes written into the buffer.
930 There are two differences: @code{strfmon} can take more than one
931 argument, and, of course, the format specification is different. Like
932 @code{strftime}, the format string consists of normal text, which is
933 output as is, and format specifiers, which are indicated by a @samp{%}.
934 Immediately after the @samp{%}, you can optionally specify various flags
935 and formatting information before the main formatting character, in a
936 similar way to @code{printf}:
940 Immediately following the @samp{%} there can be one or more of the
943 @item @samp{=@var{f}}
944 The single byte character @var{f} is used for this field as the numeric
945 fill character. By default this character is a space character.
946 Filling with this character is only performed if a left precision
947 is specified. It is not just to fill to the given field width.
949 The number is printed without grouping the digits according to the rules
950 of the current locale. By default grouping is enabled.
951 @item @samp{+}, @samp{(}
952 At most one of these flags can be used. They select which format to
953 represent the sign of a currency amount. By default, and if
954 @samp{+} is given, the locale equivalent of @math{+}/@math{-} is used. If
955 @samp{(} is given, negative amounts are enclosed in parentheses. The
956 exact format is determined by the values of the @code{LC_MONETARY}
957 category of the locale selected at program runtime.
959 The output will not contain the currency symbol.
961 The output will be formatted left-justified instead of right-justified if
962 it does not fill the entire field width.
966 The next part of a specification is an optional field width. If no
967 width is specified @math{0} is taken. During output, the function first
968 determines how much space is required. If it requires at least as many
969 characters as given by the field width, it is output using as much space
970 as necessary. Otherwise, it is extended to use the full width by
971 filling with the space character. The presence or absence of the
972 @samp{-} flag determines the side at which such padding occurs. If
973 present, the spaces are added at the right making the output
974 left-justified, and vice versa.
976 So far the format looks familiar, being similar to the @code{printf} and
977 @code{strftime} formats. However, the next two optional fields
978 introduce something new. The first one is a @samp{#} character followed
979 by a decimal digit string. The value of the digit string specifies the
980 number of @emph{digit} positions to the left of the decimal point (or
981 equivalent). This does @emph{not} include the grouping character when
982 the @samp{^} flag is not given. If the space needed to print the number
983 does not fill the whole width, the field is padded at the left side with
984 the fill character, which can be selected using the @samp{=} flag and by
985 default is a space. For example, if the field width is selected as 6
986 and the number is @math{123}, the fill character is @samp{*} the result
987 will be @samp{***123}.
989 The second optional field starts with a @samp{.} (period) and consists
990 of another decimal digit string. Its value describes the number of
991 characters printed after the decimal point. The default is selected
992 from the current locale (@code{frac_digits}, @code{int_frac_digits}, see
993 @pxref{General Numeric}). If the exact representation needs more digits
994 than given by the field width, the displayed value is rounded. If the
995 number of fractional digits is selected to be zero, no decimal point is
998 As a GNU extension, the @code{strfmon} implementation in the GNU libc
999 allows an optional @samp{L} next as a format modifier. If this modifier
1000 is given, the argument is expected to be a @code{long double} instead of
1001 a @code{double} value.
1003 Finally, the last component is a format specifier. There are three
1008 Use the locale's rules for formatting an international currency value.
1010 Use the locale's rules for formatting a national currency value.
1012 Place a @samp{%} in the output. There must be no flag, width
1013 specifier or modifier given, only @samp{%%} is allowed.
1016 As for @code{printf}, the function reads the format string
1017 from left to right and uses the values passed to the function following
1018 the format string. The values are expected to be either of type
1019 @code{double} or @code{long double}, depending on the presence of the
1020 modifier @samp{L}. The result is stored in the buffer pointed to by
1021 @var{s}. At most @var{maxsize} characters are stored.
1023 The return value of the function is the number of characters stored in
1024 @var{s}, including the terminating @code{NULL} byte. If the number of
1025 characters stored would exceed @var{maxsize}, the function returns
1026 @math{-1} and the content of the buffer @var{s} is unspecified. In this
1027 case @code{errno} is set to @code{E2BIG}.
1030 A few examples should make clear how the function works. It is
1031 assumed that all the following pieces of code are executed in a program
1032 which uses the USA locale (@code{en_US}). The simplest
1033 form of the format is this:
1036 strfmon (buf, 100, "@@%n@@%n@@%n@@", 123.45, -567.89, 12345.678);
1040 The output produced is
1042 "@@$123.45@@-$567.89@@$12,345.68@@"
1045 We can notice several things here. First, the widths of the output
1046 numbers are different. We have not specified a width in the format
1047 string, and so this is no wonder. Second, the third number is printed
1048 using thousands separators. The thousands separator for the
1049 @code{en_US} locale is a comma. The number is also rounded.
1050 @math{.678} is rounded to @math{.68} since the format does not specify a
1051 precision and the default value in the locale is @math{2}. Finally,
1052 note that the national currency symbol is printed since @samp{%n} was
1053 used, not @samp{i}. The next example shows how we can align the output.
1056 strfmon (buf, 100, "@@%=*11n@@%=*11n@@%=*11n@@", 123.45, -567.89, 12345.678);
1060 The output this time is:
1063 "@@ $123.45@@ -$567.89@@ $12,345.68@@"
1066 Two things stand out. Firstly, all fields have the same width (eleven
1067 characters) since this is the width given in the format and since no
1068 number required more characters to be printed. The second important
1069 point is that the fill character is not used. This is correct since the
1070 white space was not used to achieve a precision given by a @samp{#}
1071 modifier, but instead to fill to the given width. The difference
1072 becomes obvious if we now add a width specification.
1075 strfmon (buf, 100, "@@%=*11#5n@@%=*11#5n@@%=*11#5n@@",
1076 123.45, -567.89, 12345.678);
1083 "@@ $***123.45@@-$***567.89@@ $12,456.68@@"
1086 Here we can see that all the currency symbols are now aligned, and that
1087 the space between the currency sign and the number is filled with the
1088 selected fill character. Note that although the width is selected to be
1089 @math{5} and @math{123.45} has three digits left of the decimal point,
1090 the space is filled with three asterisks. This is correct since, as
1091 explained above, the width does not include the positions used to store
1092 thousands separators. One last example should explain the remaining
1096 strfmon (buf, 100, "@@%=0(16#5.3i@@%=0(16#5.3i@@%=0(16#5.3i@@",
1097 123.45, -567.89, 12345.678);
1101 This rather complex format string produces the following output:
1104 "@@ USD 000123,450 @@(USD 000567.890)@@ USD 12,345.678 @@"
1107 The most noticeable change is the alternative way of representing
1108 negative numbers. In financial circles this is often done using
1109 parentheses, and this is what the @samp{(} flag selected. The fill
1110 character is now @samp{0}. Note that this @samp{0} character is not
1111 regarded as a numeric zero, and therefore the first and second numbers
1112 are not printed using a thousands separator. Since we used the format
1113 specifier @samp{i} instead of @samp{n}, the international form of the
1114 currency symbol is used. This is a four letter string, in this case
1115 @code{"USD "}. The last point is that since the precision right of the
1116 decimal point is selected to be three, the first and second numbers are
1117 printed with an extra zero at the end and the third number is printed