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: * Yes-or-No Questions::         Check a Response against the locale.
   35: @end menu
   36: 
   37: @node Effects of Locale, Choosing Locale,  , Locales
   38: @section What Effects a Locale Has
   39: 
   40: Each locale specifies conventions for several purposes, including the
   41: following:
   42: 
   43: @itemize @bullet
   44: @item
   45: What multibyte character sequences are valid, and how they are
   46: interpreted (@pxref{Character Set Handling}).
   47: 
   48: @item
   49: Classification of which characters in the local character set are
   50: considered alphabetic, and upper- and lower-case conversion conventions
   51: (@pxref{Character Handling}).
   52: 
   53: @item
   54: The collating sequence for the local language and character set
   55: (@pxref{Collation Functions}).
   56: 
   57: @item
   58: Formatting of numbers and currency amounts (@pxref{General Numeric}).
   59: 
   60: @item
   61: Formatting of dates and times (@pxref{Formatting Calendar Time}).
   62: 
   63: @item
   64: What language to use for output, including error messages
   65: (@pxref{Message Translation}).
   66: 
   67: @item
   68: What language to use for user answers to yes-or-no questions
   69: (@pxref{Yes-or-No Questions}).
   70: 
   71: @item
   72: What language to use for more complex user input.
   73: (The C library doesn't yet help you implement this.)
   74: @end itemize
   75: 
   76: Some aspects of adapting to the specified locale are handled
   77: automatically by the library subroutines.  For example, all your program
   78: needs to do in order to use the collating sequence of the chosen locale
   79: is to use @code{strcoll} or @code{strxfrm} to compare strings.
   80: 
   81: Other aspects of locales are beyond the comprehension of the library.
   82: For example, the library can't automatically translate your program's
   83: output messages into other languages.  The only way you can support
   84: output in the user's favorite language is to program this more or less
   85: by hand.  The C library provides functions to handle translations for
   86: multiple languages easily.
   87: 
   88: This chapter discusses the mechanism by which you can modify the current
   89: locale.  The effects of the current locale on specific library functions
   90: are discussed in more detail in the descriptions of those functions.
   91: 
   92: @node Choosing Locale, Locale Categories, Effects of Locale, Locales
   93: @section Choosing a Locale
   94: 
   95: The simplest way for the user to choose a locale is to set the
   96: environment variable @code{LANG}.  This specifies a single locale to use
   97: for all purposes.  For example, a user could specify a hypothetical
   98: locale named @samp{espana-castellano} to use the standard conventions of
   99: most of Spain.
  100: 
  101: The set of locales supported depends on the operating system you are
  102: using, and so do their names.  We can't make any promises about what
  103: locales will exist, except for one standard locale called @samp{C} or
  104: @samp{POSIX}.  Later we will describe how to construct locales.
  105: @comment (@pxref{Building Locale Files}).
  106: 
  107: @cindex combining locales
  108: A user also has the option of specifying different locales for different
  109: purposes---in effect, choosing a mixture of multiple locales.
  110: 
  111: For example, the user might specify the locale @samp{espana-castellano}
  112: for most purposes, but specify the locale @samp{usa-english} for
  113: currency formatting.  This might make sense if the user is a
  114: Spanish-speaking American, working in Spanish, but representing monetary
  115: amounts in US dollars.
  116: 
  117: Note that both locales @samp{espana-castellano} and @samp{usa-english},
  118: like all locales, would include conventions for all of the purposes to
  119: which locales apply.  However, the user can choose to use each locale
  120: for a particular subset of those purposes.
  121: 
  122: @node Locale Categories, Setting the Locale, Choosing Locale, Locales
  123: @section Categories of Activities that Locales Affect
  124: @cindex categories for locales
  125: @cindex locale categories
  126: 
  127: The purposes that locales serve are grouped into @dfn{categories}, so
  128: that a user or a program can choose the locale for each category
  129: independently.  Here is a table of categories; each name is both an
  130: environment variable that a user can set, and a macro name that you can
  131: use as an argument to @code{setlocale}.
  132: 
  133: @vtable @code
  134: @comment locale.h
  135: @comment ISO
  136: @item LC_COLLATE
  137: This category applies to collation of strings (functions @code{strcoll}
  138: and @code{strxfrm}); see @ref{Collation Functions}.
  139: 
  140: @comment locale.h
  141: @comment ISO
  142: @item LC_CTYPE
  143: This category applies to classification and conversion of characters,
  144: and to multibyte and wide characters;
  145: see @ref{Character Handling}, and @ref{Character Set Handling}.
  146: 
  147: @comment locale.h
  148: @comment ISO
  149: @item LC_MONETARY
  150: This category applies to formatting monetary values; see @ref{General Numeric}.
  151: 
  152: @comment locale.h
  153: @comment ISO
  154: @item LC_NUMERIC
  155: This category applies to formatting numeric values that are not
  156: monetary; see @ref{General Numeric}.
  157: 
  158: @comment locale.h
  159: @comment ISO
  160: @item LC_TIME
  161: This category applies to formatting date and time values; see
  162: @ref{Formatting Calendar Time}.
  163: 
  164: @comment locale.h
  165: @comment XOPEN
  166: @item LC_MESSAGES
  167: This category applies to selecting the language used in the user
  168: interface for message translation (@pxref{The Uniforum approach};
  169: @pxref{Message catalogs a la X/Open})  and contains regular expressions
  170: for affirmative and negative responses.
  171: 
  172: @comment locale.h
  173: @comment ISO
  174: @item LC_ALL
  175: This is not an environment variable; it is only a macro that you can use
  176: with @code{setlocale} to set a single locale for all purposes.  Setting
  177: this environment variable overwrites all selections by the other
  178: @code{LC_*} variables or @code{LANG}.
  179: 
  180: @comment locale.h
  181: @comment ISO
  182: @item LANG
  183: If this environment variable is defined, its value specifies the locale
  184: to use for all purposes except as overridden by the variables above.
  185: @end vtable
  186: 
  187: @vindex LANGUAGE
  188: When developing the message translation functions it was felt that the
  189: functionality provided by the variables above is not sufficient.  For
  190: example, it should be possible to specify more than one locale name.
  191: Take a Swedish user who better speaks German than English, and a program
  192: whose messages are output in English by default.  It should be possible
  193: to specify that the first choice of language is Swedish, the second
  194: German, and if this also fails to use English.  This is
  195: possible with the variable @code{LANGUAGE}.  For further description of
  196: this GNU extension see @ref{Using gettextized software}.
  197: 
  198: @node Setting the Locale, Standard Locales, Locale Categories, Locales
  199: @section How Programs Set the Locale
  200: 
  201: A C program inherits its locale environment variables when it starts up.
  202: This happens automatically.  However, these variables do not
  203: automatically control the locale used by the library functions, because
  204: @w{ISO C} says that all programs start by default in the standard @samp{C}
  205: locale.  To use the locales specified by the environment, you must call
  206: @code{setlocale}.  Call it as follows:
  207: 
  208: @smallexample
  209: setlocale (LC_ALL, "");
  210: @end smallexample
  211: 
  212: @noindent
  213: to select a locale based on the user choice of the appropriate
  214: environment variables.
  215: 
  216: @cindex changing the locale
  217: @cindex locale, changing
  218: You can also use @code{setlocale} to specify a particular locale, for
  219: general use or for a specific category.
  220: 
  221: @pindex locale.h
  222: The symbols in this section are defined in the header file @file{locale.h}.
  223: 
  224: @comment locale.h
  225: @comment ISO
  226: @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
  227: The function @code{setlocale} sets the current locale for category
  228: @var{category} to @var{locale}.  A list of all the locales the system
  229: provides can be created by running
  230: 
  231: @pindex locale
  232: @smallexample
  233:   locale -a
  234: @end smallexample
  235: 
  236: If @var{category} is @code{LC_ALL}, this specifies the locale for all
  237: purposes.  The other possible values of @var{category} specify an
  238: single purpose (@pxref{Locale Categories}).
  239: 
  240: You can also use this function to find out the current locale by passing
  241: a null pointer as the @var{locale} argument.  In this case,
  242: @code{setlocale} returns a string that is the name of the locale
  243: currently selected for category @var{category}.
  244: 
  245: The string returned by @code{setlocale} can be overwritten by subsequent
  246: calls, so you should make a copy of the string (@pxref{Copying and
  247: Concatenation}) if you want to save it past any further calls to
  248: @code{setlocale}.  (The standard library is guaranteed never to call
  249: @code{setlocale} itself.)
  250: 
  251: You should not modify the string returned by @code{setlocale}.  It might
  252: be the same string that was passed as an argument in a previous call to
  253: @code{setlocale}.  One requirement is that the @var{category} must be
  254: the same in the call the string was returned and the one when the string
  255: is passed in as @var{locale} parameter.
  256: 
  257: When you read the current locale for category @code{LC_ALL}, the value
  258: encodes the entire combination of selected locales for all categories.
  259: In this case, the value is not just a single locale name.  In fact, we
  260: don't make any promises about what it looks like.  But if you specify
  261: the same ``locale name'' with @code{LC_ALL} in a subsequent call to
  262: @code{setlocale}, it restores the same combination of locale selections.
  263: 
  264: To be sure you can use the returned string encoding the currently selected
  265: locale at a later time, you must make a copy of the string.  It is not
  266: guaranteed that the returned pointer remains valid over time.
  267: 
  268: When the @var{locale} argument is not a null pointer, the string returned
  269: by @code{setlocale} reflects the newly-modified locale.
  270: 
  271: If you specify an empty string for @var{locale}, this means to read the
  272: appropriate environment variable and use its value to select the locale
  273: for @var{category}.
  274: 
  275: If a nonempty string is given for @var{locale}, then the locale of that
  276: name is used if possible.
  277: 
  278: If you specify an invalid locale name, @code{setlocale} returns a null
  279: pointer and leaves the current locale unchanged.
  280: @end deftypefun
  281: 
  282: Here is an example showing how you might use @code{setlocale} to
  283: temporarily switch to a new locale.
  284: 
  285: @smallexample
  286: #include <stddef.h>
  287: #include <locale.h>
  288: #include <stdlib.h>
  289: #include <string.h>
  290: 
  291: void
  292: with_other_locale (char *new_locale,
  293:                    void (*subroutine) (int),
  294:                    int argument)
  295: @{
  296:   char *old_locale, *saved_locale;
  297: 
  298:   /* @r{Get the name of the current locale.}  */
  299:   old_locale = setlocale (LC_ALL, NULL);
  300: 
  301:   /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */
  302:   saved_locale = strdup (old_locale);
  303:   if (saved_locale == NULL)
  304:     fatal ("Out of memory");
  305: 
  306:   /* @r{Now change the locale and do some stuff with it.} */
  307:   setlocale (LC_ALL, new_locale);
  308:   (*subroutine) (argument);
  309: 
  310:   /* @r{Restore the original locale.} */
  311:   setlocale (LC_ALL, saved_locale);
  312:   free (saved_locale);
  313: @}
  314: @end smallexample
  315: 
  316: @strong{Portability Note:} Some @w{ISO C} systems may define additional
  317: locale categories, and future versions of the library will do so.  For
  318: portability, assume that any symbol beginning with @samp{LC_} might be
  319: defined in @file{locale.h}.
  320: 
  321: @node Standard Locales, Locale Information, Setting the Locale, Locales
  322: @section Standard Locales
  323: 
  324: The only locale names you can count on finding on all operating systems
  325: are these three standard ones:
  326: 
  327: @table @code
  328: @item "C"
  329: This is the standard C locale.  The attributes and behavior it provides
  330: are specified in the @w{ISO C} standard.  When your program starts up, it
  331: initially uses this locale by default.
  332: 
  333: @item "POSIX"
  334: This is the standard POSIX locale.  Currently, it is an alias for the
  335: standard C locale.
  336: 
  337: @item ""
  338: The empty name says to select a locale based on environment variables.
  339: @xref{Locale Categories}.
  340: @end table
  341: 
  342: Defining and installing named locales is normally a responsibility of
  343: the system administrator at your site (or the person who installed the
  344: GNU C library).  It is also possible for the user to create private
  345: locales.  All this will be discussed later when describing the tool to
  346: do so.
  347: @comment (@pxref{Building Locale Files}).
  348: 
  349: If your program needs to use something other than the @samp{C} locale,
  350: it will be more portable if you use whatever locale the user specifies
  351: with the environment, rather than trying to specify some non-standard
  352: locale explicitly by name.  Remember, different machines might have
  353: different sets of locales installed.
  354: 
  355: @node Locale Information, Formatting Numbers, Standard Locales, Locales
  356: @section Accessing Locale Information
  357: 
  358: There are several ways to access locale information.  The simplest
  359: way is to let the C library itself do the work.  Several of the
  360: functions in this library implicitly access the locale data, and use
  361: what information is provided by the currently selected locale.  This is
  362: how the locale model is meant to work normally.
  363: 
  364: As an example take the @code{strftime} function, which is meant to nicely
  365: format date and time information (@pxref{Formatting Calendar Time}).
  366: Part of the standard information contained in the @code{LC_TIME}
  367: category is the names of the months.  Instead of requiring the
  368: programmer to take care of providing the translations the
  369: @code{strftime} function does this all by itself.  @code{%A}
  370: in the format string is replaced by the appropriate weekday
  371: name of the locale currently selected by @code{LC_TIME}.  This is an
  372: easy example, and wherever possible functions do things automatically
  373: in this way.
  374: 
  375: But there are quite often situations when there is simply no function
  376: to perform the task, or it is simply not possible to do the work
  377: automatically.  For these cases it is necessary to access the
  378: information in the locale directly.  To do this the C library provides
  379: two functions: @code{localeconv} and @code{nl_langinfo}.  The former is
  380: part of @w{ISO C} and therefore portable, but has a brain-damaged
  381: interface.  The second is part of the Unix interface and is portable in
  382: as far as the system follows the Unix standards.
  383: 
  384: @menu
  385: * The Lame Way to Locale Data::   ISO C's @code{localeconv}.
  386: * The Elegant and Fast Way::      X/Open's @code{nl_langinfo}.
  387: @end menu
  388: 
  389: @node The Lame Way to Locale Data, The Elegant and Fast Way, ,Locale Information
  390: @subsection @code{localeconv}: It is portable but @dots{}
  391: 
  392: Together with the @code{setlocale} function the @w{ISO C} people
  393: invented the @code{localeconv} function.  It is a masterpiece of poor
  394: design.  It is expensive to use, not extendable, and not generally
  395: usable as it provides access to only @code{LC_MONETARY} and
  396: @code{LC_NUMERIC} related information.  Nevertheless, if it is
  397: applicable to a given situation it should be used since it is very
  398: portable.  The function @code{strfmon} formats monetary amounts
  399: according to the selected locale using this information.
  400: @pindex locale.h
  401: @cindex monetary value formatting
  402: @cindex numeric value formatting
  403: 
  404: @comment locale.h
  405: @comment ISO
  406: @deftypefun {struct lconv *} localeconv (void)
  407: The @code{localeconv} function returns a pointer to a structure whose
  408: components contain information about how numeric and monetary values
  409: should be formatted in the current locale.
  410: 
  411: You should not modify the structure or its contents.  The structure might
  412: be overwritten by subsequent calls to @code{localeconv}, or by calls to
  413: @code{setlocale}, but no other function in the library overwrites this
  414: value.
  415: @end deftypefun
  416: 
  417: @comment locale.h
  418: @comment ISO
  419: @deftp {Data Type} {struct lconv}
  420: @code{localeconv}'s return value is of this data type.  Its elements are
  421: described in the following subsections.
  422: @end deftp
  423: 
  424: If a member of the structure @code{struct lconv} has type @code{char},
  425: and the value is @code{CHAR_MAX}, it means that the current locale has
  426: no value for that parameter.
  427: 
  428: @menu
  429: * General Numeric::             Parameters for formatting numbers and
  430:                                  currency amounts.
  431: * Currency Symbol::             How to print the symbol that identifies an
  432:                                  amount of money (e.g. @samp{$}).
  433: * Sign of Money Amount::        How to print the (positive or negative) sign
  434:                                  for a monetary amount, if one exists.
  435: @end menu
  436: 
  437: @node General Numeric, Currency Symbol, , The Lame Way to Locale Data
  438: @subsubsection Generic Numeric Formatting Parameters
  439: 
  440: These are the standard members of @code{struct lconv}; there may be
  441: others.
  442: 
  443: @table @code
  444: @item char *decimal_point
  445: @itemx char *mon_decimal_point
  446: These are the decimal-point separators used in formatting non-monetary
  447: and monetary quantities, respectively.  In the @samp{C} locale, the
  448: value of @code{decimal_point} is @code{"."}, and the value of
  449: @code{mon_decimal_point} is @code{""}.
  450: @cindex decimal-point separator
  451: 
  452: @item char *thousands_sep
  453: @itemx char *mon_thousands_sep
  454: These are the separators used to delimit groups of digits to the left of
  455: the decimal point in formatting non-monetary and monetary quantities,
  456: respectively.  In the @samp{C} locale, both members have a value of
  457: @code{""} (the empty string).
  458: 
  459: @item char *grouping
  460: @itemx char *mon_grouping
  461: These are strings that specify how to group the digits to the left of
  462: the decimal point.  @code{grouping} applies to non-monetary quantities
  463: and @code{mon_grouping} applies to monetary quantities.  Use either
  464: @code{thousands_sep} or @code{mon_thousands_sep} to separate the digit
  465: groups.
  466: @cindex grouping of digits
  467: 
  468: Each member of these strings is to be interpreted as an integer value of
  469: type @code{char}.  Successive numbers (from left to right) give the
  470: sizes of successive groups (from right to left, starting at the decimal
  471: point.)  The last member is either @code{0}, in which case the previous
  472: member is used over and over again for all the remaining groups, or
  473: @code{CHAR_MAX}, in which case there is no more grouping---or, put
  474: another way, any remaining digits form one large group without
  475: separators.
  476: 
  477: For example, if @code{grouping} is @code{"\04\03\02"}, the correct
  478: grouping for the number @code{123456787654321} is @samp{12}, @samp{34},
  479: @samp{56}, @samp{78}, @samp{765}, @samp{4321}.  This uses a group of 4
  480: digits at the end, preceded by a group of 3 digits, preceded by groups
  481: of 2 digits (as many as needed).  With a separator of @samp{,}, the
  482: number would be printed as @samp{12,34,56,78,765,4321}.
  483: 
  484: A value of @code{"\03"} indicates repeated groups of three digits, as
  485: normally used in the U.S.
  486: 
  487: In the standard @samp{C} locale, both @code{grouping} and
  488: @code{mon_grouping} have a value of @code{""}.  This value specifies no
  489: grouping at all.
  490: 
  491: @item char int_frac_digits
  492: @itemx char frac_digits
  493: These are small integers indicating how many fractional digits (to the
  494: right of the decimal point) should be displayed in a monetary value in
  495: international and local formats, respectively.  (Most often, both
  496: members have the same value.)
  497: 
  498: In the standard @samp{C} locale, both of these members have the value
  499: @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
  500: what to do when you find this value; we recommend printing no
  501: fractional digits.  (This locale also specifies the empty string for
  502: @code{mon_decimal_point}, so printing any fractional digits would be
  503: confusing!)
  504: @end table
  505: 
  506: @node Currency Symbol, Sign of Money Amount, General Numeric, The Lame Way to Locale Data
  507: @subsubsection Printing the Currency Symbol
  508: @cindex currency symbols
  509: 
  510: These members of the @code{struct lconv} structure specify how to print
  511: the symbol to identify a monetary value---the international analog of
  512: @samp{$} for US dollars.
  513: 
  514: Each country has two standard currency symbols.  The @dfn{local currency
  515: symbol} is used commonly within the country, while the
  516: @dfn{international currency symbol} is used internationally to refer to
  517: that country's currency when it is necessary to indicate the country
  518: unambiguously.
  519: 
  520: For example, many countries use the dollar as their monetary unit, and
  521: when dealing with international currencies it's important to specify
  522: that one is dealing with (say) Canadian dollars instead of U.S. dollars
  523: or Australian dollars.  But when the context is known to be Canada,
  524: there is no need to make this explicit---dollar amounts are implicitly
  525: assumed to be in Canadian dollars.
  526: 
  527: @table @code
  528: @item char *currency_symbol
  529: The local currency symbol for the selected locale.
  530: 
  531: In the standard @samp{C} locale, this member has a value of @code{""}
  532: (the empty string), meaning ``unspecified''.  The ISO standard doesn't
  533: say what to do when you find this value; we recommend you simply print
  534: the empty string as you would print any other string pointed to by this
  535: variable.
  536: 
  537: @item char *int_curr_symbol
  538: The international currency symbol for the selected locale.
  539: 
  540: The value of @code{int_curr_symbol} should normally consist of a
  541: three-letter abbreviation determined by the international standard
  542: @cite{ISO 4217 Codes for the Representation of Currency and Funds},
  543: followed by a one-character separator (often a space).
  544: 
  545: In the standard @samp{C} locale, this member has a value of @code{""}
  546: (the empty string), meaning ``unspecified''.  We recommend you simply print
  547: the empty string as you would print any other string pointed to by this
  548: variable.
  549: 
  550: @item char p_cs_precedes
  551: @itemx char n_cs_precedes
  552: @itemx char int_p_cs_precedes
  553: @itemx char int_n_cs_precedes
  554: These members are @code{1} if the @code{currency_symbol} or
  555: @code{int_curr_symbol} strings should precede the value of a monetary
  556: amount, or @code{0} if the strings should follow the value.  The
  557: @code{p_cs_precedes} and @code{int_p_cs_precedes} members apply to
  558: positive amounts (or zero), and the @code{n_cs_precedes} and
  559: @code{int_n_cs_precedes} members apply to negative amounts.
  560: 
  561: In the standard @samp{C} locale, all of these members have a value of
  562: @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
  563: what to do when you find this value.  We recommend printing the
  564: currency symbol before the amount, which is right for most countries.
  565: In other words, treat all nonzero values alike in these members.
  566: 
  567: The members with the @code{int_} prefix apply to the
  568: @code{int_curr_symbol} while the other two apply to
  569: @code{currency_symbol}.
  570: 
  571: @item char p_sep_by_space
  572: @itemx char n_sep_by_space
  573: @itemx char int_p_sep_by_space
  574: @itemx char int_n_sep_by_space
  575: These members are @code{1} if a space should appear between the
  576: @code{currency_symbol} or @code{int_curr_symbol} strings and the
  577: amount, or @code{0} if no space should appear.  The
  578: @code{p_sep_by_space} and @code{int_p_sep_by_space} members apply to
  579: positive amounts (or zero), and the @code{n_sep_by_space} and
  580: @code{int_n_sep_by_space} members apply to negative amounts.
  581: 
  582: In the standard @samp{C} locale, all of these members have a value of
  583: @code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
  584: what you should do when you find this value; we suggest you treat it as
  585: 1 (print a space).  In other words, treat all nonzero values alike in
  586: these members.
  587: 
  588: The members with the @code{int_} prefix apply to the
  589: @code{int_curr_symbol} while the other two apply to
  590: @code{currency_symbol}.  There is one specialty with the
  591: @code{int_curr_symbol}, though.  Since all legal values contain a space
  592: at the end the string one either printf this space (if the currency
  593: symbol must appear in front and must be separated) or one has to avoid
  594: printing this character at all (especially when at the end of the
  595: string).
  596: @end table
  597: 
  598: @node Sign of Money Amount, , Currency Symbol, The Lame Way to Locale Data
  599: @subsubsection Printing the Sign of a Monetary Amount
  600: 
  601: These members of the @code{struct lconv} structure specify how to print
  602: the sign (if any) of a monetary value.
  603: 
  604: @table @code
  605: @item char *positive_sign
  606: @itemx char *negative_sign
  607: These are strings used to indicate positive (or zero) and negative
  608: monetary quantities, respectively.
  609: 
  610: In the standard @samp{C} locale, both of these members have a value of
  611: @code{""} (the empty string), meaning ``unspecified''.
  612: 
  613: The ISO standard doesn't say what to do when you find this value; we
  614: recommend printing @code{positive_sign} as you find it, even if it is
  615: empty.  For a negative value, print @code{negative_sign} as you find it
  616: unless both it and @code{positive_sign} are empty, in which case print
  617: @samp{-} instead.  (Failing to indicate the sign at all seems rather
  618: unreasonable.)
  619: 
  620: @item char p_sign_posn
  621: @itemx char n_sign_posn
  622: @itemx char int_p_sign_posn
  623: @itemx char int_n_sign_posn
  624: These members are small integers that indicate how to
  625: position the sign for nonnegative and negative monetary quantities,
  626: respectively.  (The string used by the sign is what was specified with
  627: @code{positive_sign} or @code{negative_sign}.)  The possible values are
  628: as follows:
  629: 
  630: @table @code
  631: @item 0
  632: The currency symbol and quantity should be surrounded by parentheses.
  633: 
  634: @item 1
  635: Print the sign string before the quantity and currency symbol.
  636: 
  637: @item 2
  638: Print the sign string after the quantity and currency symbol.
  639: 
  640: @item 3
  641: Print the sign string right before the currency symbol.
  642: 
  643: @item 4
  644: Print the sign string right after the currency symbol.
  645: 
  646: @item CHAR_MAX
  647: ``Unspecified''.  Both members have this value in the standard
  648: @samp{C} locale.
  649: @end table
  650: 
  651: The ISO standard doesn't say what you should do when the value is
  652: @code{CHAR_MAX}.  We recommend you print the sign after the currency
  653: symbol.
  654: 
  655: The members with the @code{int_} prefix apply to the
  656: @code{int_curr_symbol} while the other two apply to
  657: @code{currency_symbol}.
  658: @end table
  659: 
  660: @node The Elegant and Fast Way, , The Lame Way to Locale Data, Locale Information
  661: @subsection Pinpoint Access to Locale Data
  662: 
  663: When writing the X/Open Portability Guide the authors realized that the
  664: @code{localeconv} function is not enough to provide reasonable access to
  665: locale information.  The information which was meant to be available
  666: in the locale (as later specified in the POSIX.1 standard) requires more
  667: ways to access it.  Therefore the @code{nl_langinfo} function
  668: was introduced.
  669: 
  670: @comment langinfo.h
  671: @comment XOPEN
  672: @deftypefun {char *} nl_langinfo (nl_item @var{item})
  673: The @code{nl_langinfo} function can be used to access individual
  674: elements of the locale categories.  Unlike the @code{localeconv}
  675: function, which returns all the information, @code{nl_langinfo}
  676: lets the caller select what information it requires.  This is very
  677: fast and it is not a problem to call this function multiple times.
  678: 
  679: A second advantage is that in addition to the numeric and monetary
  680: formatting information, information from the
  681: @code{LC_TIME} and @code{LC_MESSAGES} categories is available.
  682: 
  683: @pindex langinfo.h
  684: The type @code{nl_type} is defined in @file{nl_types.h}.  The argument
  685: @var{item} is a numeric value defined in the header @file{langinfo.h}.
  686: The X/Open standard defines the following values:
  687: 
  688: @vtable @code
  689: @item CODESET
  690: @code{nl_langinfo} returns a string with the name of the coded character
  691: set used in the selected locale.
  692: 
  693: @item ABDAY_1
  694: @itemx ABDAY_2
  695: @itemx ABDAY_3
  696: @itemx ABDAY_4
  697: @itemx ABDAY_5
  698: @itemx ABDAY_6
  699: @itemx ABDAY_7
  700: @code{nl_langinfo} returns the abbreviated weekday name.  @code{ABDAY_1}
  701: corresponds to Sunday.
  702: @item DAY_1
  703: @itemx DAY_2
  704: @itemx DAY_3
  705: @itemx DAY_4
  706: @itemx DAY_5
  707: @itemx DAY_6
  708: @itemx DAY_7
  709: Similar to @code{ABDAY_1} etc., but here the return value is the
  710: unabbreviated weekday name.
  711: @item ABMON_1
  712: @itemx ABMON_2
  713: @itemx ABMON_3
  714: @itemx ABMON_4
  715: @itemx ABMON_5
  716: @itemx ABMON_6
  717: @itemx ABMON_7
  718: @itemx ABMON_8
  719: @itemx ABMON_9
  720: @itemx ABMON_10
  721: @itemx ABMON_11
  722: @itemx ABMON_12
  723: The return value is abbreviated name of the month.  @code{ABMON_1}
  724: corresponds to January.
  725: @item MON_1
  726: @itemx MON_2
  727: @itemx MON_3
  728: @itemx MON_4
  729: @itemx MON_5
  730: @itemx MON_6
  731: @itemx MON_7
  732: @itemx MON_8
  733: @itemx MON_9
  734: @itemx MON_10
  735: @itemx MON_11
  736: @itemx MON_12
  737: Similar to @code{ABMON_1} etc., but here the month names are not abbreviated.
  738: Here the first value @code{MON_1} also corresponds to January.
  739: @item AM_STR
  740: @itemx PM_STR
  741: The return values are strings which can be used in the representation of time
  742: as an hour from 1 to 12 plus an am/pm specifier.
  743: 
  744: Note that in locales which do not use this time representation
  745: these strings might be empty, in which case the am/pm format
  746: cannot be used at all.
  747: @item D_T_FMT
  748: The return value can be used as a format string for @code{strftime} to
  749: represent time and date in a locale-specific way.
  750: @item D_FMT
  751: The return value can be used as a format string for @code{strftime} to
  752: represent a date in a locale-specific way.
  753: @item T_FMT
  754: