</DL>
<P>
Defining and installing named locales is normally a responsibility of
the system administrator at your site (or the person who installed the
GNU C library).  Some systems may allow users to create locales, but
we don't discuss that here.
<P>
If your program needs to use something other than the <SAMP>`C'</SAMP> locale,
it will be more portable if you use the whatever locale the user
specifies with the environment, rather than trying to specify some
non-standard locale explicitly by name.  Remember, different machines
might have different sets of locales installed.
<P>
<H2><A NAME="SEC82" HREF="library_toc.html#SEC82" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC82">Numeric Formatting</A></H2>
<P>
When you want to format a number or a currency amount using the
conventions of the current locale, you can use the function
<CODE>localeconv</CODE> to get the data on how to do it.  The function
<CODE>localeconv</CODE> is declared in the header file <TT>`locale.h'</TT>.
<A NAME="IDX373"></A>
<A NAME="IDX374"></A>
<A NAME="IDX372"></A>
<P>
<A NAME="IDX375"></A>
<U>Function:</U> struct lconv * <B>localeconv</B> <I>(void)</I><P>
The <CODE>localeconv</CODE> function returns a pointer to a structure whose
components contain information about how numeric and monetary values
should be formatted in the current locale.
<P>
You shouldn't modify the structure or its contents.  The structure might
be overwritten by subsequent calls to <CODE>localeconv</CODE>, or by calls to
<CODE>setlocale</CODE>, but no other function in the library overwrites this
value.
<P>
<A NAME="IDX376"></A>
<U>Data Type:</U> <B>struct lconv</B><P>
This is the data type of the value returned by <CODE>localeconv</CODE>.
<P>
If a member of the structure <CODE>struct lconv</CODE> has type <CODE>char</CODE>,
and the value is <CODE>CHAR_MAX</CODE>, it means that the current locale has
no value for that parameter.
<P>
<H3><A NAME="SEC83" HREF="library_toc.html#SEC83" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC83">Generic Numeric Formatting Parameters</A></H3>
<P>
These are the standard members of <CODE>struct lconv</CODE>; there may be
others.
<P>
<DL COMPACT>
<DT><CODE>char *decimal_point</CODE>
<DD><DT><CODE>char *mon_decimal_point</CODE>
<DD>These are the decimal-point separators used in formatting non-monetary
and monetary quantities, respectively.  In the <SAMP>`C'</SAMP> locale, the
value of <CODE>decimal_point</CODE> is <CODE>"."</CODE>, and the value of
<CODE>mon_decimal_point</CODE> is <CODE>""</CODE>.
<A NAME="IDX377"></A>
<P>
<DT><CODE>char *thousands_sep</CODE>
<DD><DT><CODE>char *mon_thousands_sep</CODE>
<DD>These are the separators used to delimit groups of digits to the left of
the decimal point in formatting non-monetary and monetary quantities,
respectively.  In the <SAMP>`C'</SAMP> locale, both members have a value of
<CODE>""</CODE> (the empty string).
<P>
<DT><CODE>char *grouping</CODE>
<DD><DT><CODE>char *mon_grouping</CODE>
<DD>These are strings that specify how to group the digits to the left of
the decimal point.  <CODE>grouping</CODE> applies to non-monetary quantities
and <CODE>mon_grouping</CODE> applies to monetary quantities.  Use either
<CODE>thousands_sep</CODE> or <CODE>mon_thousands_sep</CODE> to separate the digit
groups.
<A NAME="IDX378"></A>
<P>
Each string is made up of decimal numbers separated by semicolons.
Successive numbers (from left to right) give the sizes of successive
groups (from right to left, starting at the decimal point).  The last
number in the string is used over and over for all the remaining groups.
<P>
If the last integer is <CODE>-1</CODE>, it means that there is no more
grouping--or, put another way, any remaining digits form one large
group without separators.
<P>
For example, if <CODE>grouping</CODE> is <CODE>"4;3;2"</CODE>, the number
<CODE>123456787654321</CODE> should be grouped into <SAMP>`12'</SAMP>, <SAMP>`34'</SAMP>,
<SAMP>`56'</SAMP>, <SAMP>`78'</SAMP>, <SAMP>`765'</SAMP>, <SAMP>`4321'</SAMP>.  This uses a group of 4
digits at the end, preceded by a group of 3 digits, preceded by groups
of 2 digits (as many as needed).  With a separator of <SAMP>`,'</SAMP>, the
number would be printed as <SAMP>`12,34,56,78,765,4321'</SAMP>.
<P>
A value of <CODE>"3"</CODE> indicates repeated groups of three digits, as
normally used in the U.S.
<P>
In the standard <SAMP>`C'</SAMP> locale, both <CODE>grouping</CODE> and
<CODE>mon_grouping</CODE> have a value of <CODE>""</CODE>.  This value specifies no
grouping at all.
<P>
<DT><CODE>char int_frac_digits</CODE>
<DD><DT><CODE>char frac_digits</CODE>
<DD>These are small integers indicating how many fractional digits (to the
right of the decimal point) should be displayed in a monetary value in
international and local formats, respectively.  (Most often, both
members have the same value.)
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have the value
<CODE>CHAR_MAX</CODE>, meaning "unspecified".  The ANSI standard doesn't say
what to do when you find this the value; we recommend printing no
fractional digits.  (This locale also specifies the empty string for
<CODE>mon_decimal_point</CODE>, so printing any fractional digits would be
confusing!)
</DL>
<P>
<A NAME="IDX379"></A>
<H3><A NAME="SEC84" HREF="library_toc.html#SEC84" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC84">Printing the Currency Symbol</A></H3>
<P>
These members of the <CODE>struct lconv</CODE> structure specify how to print
the symbol to identify a monetary value--the international analog of
<SAMP>`$'</SAMP> for US dollars.
<P>
Each country has two standard currency symbols.  The <DFN>local currency
symbol</DFN> is used commonly within the country, while the
<DFN>international currency symbol</DFN> is used internationally to refer to
that country's currency when it is necessary to indicate the country
unambiguously.
<P>
For example, many countries use the dollar as their monetary unit, and
when dealing with international currencies it's important to specify
that one is dealing with (say) Canadian dollars instead of U.S. dollars
or Australian dollars.  But when the context is known to be Canada,
there is no need to make this explicit--dollar amounts are implicitly
assumed to be in Canadian dollars.
<P>
<DL COMPACT>
<DT><CODE>char *currency_symbol</CODE>
<DD>The local currency symbol for the selected locale.
<P>
In the standard <SAMP>`C'</SAMP> locale, this member has a value of <CODE>""</CODE>
(the empty string), meaning "unspecified".  The ANSI standard doesn't
say what to do when you find this value; we recommend you simply print
the empty string as you would print any other string found in the
appropriate member.
<P>
<DT><CODE>char *int_curr_symbol</CODE>
<DD>The international currency symbol for the selected locale.
<P>
The value of <CODE>int_curr_symbol</CODE> should normally consist of a
three-letter abbreviation determined by the international standard
<CITE>ISO 4217 Codes for the Representation of Currency and Funds</CITE>,
followed by a one-character separator (often a space).
<P>
In the standard <SAMP>`C'</SAMP> locale, this member has a value of <CODE>""</CODE>
(the empty string), meaning "unspecified".  We recommend you simply
print the empty string as you would print any other string found in the
appropriate member.
<P>
<DT><CODE>char p_cs_precedes</CODE>
<DD><DT><CODE>char n_cs_precedes</CODE>
<DD>These members are <CODE>1</CODE> if the <CODE>currency_symbol</CODE> string should
precede the value of a monetary amount, or <CODE>0</CODE> if the string should
follow the value.  The <CODE>p_cs_precedes</CODE> member applies to positive
amounts (or zero), and the <CODE>n_cs_precedes</CODE> member applies to
negative amounts.
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have a value of
<CODE>CHAR_MAX</CODE>, meaning "unspecified".  The ANSI standard doesn't say
what to do when you find this value, but we recommend printing the
currency symbol before the amount.  That's right for most countries.
In other words, treat all nonzero values alike in these members.
<P>
The POSIX standard says that these two members apply to the
<CODE>int_curr_symbol</CODE> as well as the <CODE>currency_symbol</CODE>.  The ANSI
C standard seems to imply that they should apply only to the
<CODE>currency_symbol</CODE>---so the <CODE>int_curr_symbol</CODE> should always
preceed the amount.
<P>
We can only guess which of these (if either) matches the usual
conventions for printing international currency symbols.  Our guess is
that they should always preceed the amount.  If we find out a reliable
answer, we will put it here.
<P>
<DT><CODE>char p_sep_by_space</CODE>
<DD><DT><CODE>char n_sep_by_space</CODE>
<DD>These members are <CODE>1</CODE> if a space should appear between the
<CODE>currency_symbol</CODE> string and the amount, or <CODE>0</CODE> if no space
should appear.  The <CODE>p_sep_by_space</CODE> member applies to positive
amounts (or zero), and the <CODE>n_sep_by_space</CODE> member applies to
negative amounts.
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have a value of
<CODE>CHAR_MAX</CODE>, meaning "unspecified".  The ANSI standard doesn't say
what you should do when you find this value; we suggest you treat it as
one (print a space).  In other words, treat all nonzero values alike in
these members.
<P>
These members apply only to <CODE>currency_symbol</CODE>.  When you use
<CODE>int_curr_symbol</CODE>, you never print an additional space, because
<CODE>int_curr_symbol</CODE> itself contains the appropriate separator.
<P>
The POSIX standard says that these two members apply to the
<CODE>int_curr_symbol</CODE> as well as the <CODE>currency_symbol</CODE>.  But an
example in the ANSI C standard clearly implies that they should apply
only to the <CODE>currency_symbol</CODE>---that the <CODE>int_curr_symbol</CODE>
contains any appropriate separator, so you should never print an
additional space.
<P>
Based on what we know now, we recommend you ignore these members when
printing international currency symbols, and print no extra space.
</DL>
<P>
<H3><A NAME="SEC85" HREF="library_toc.html#SEC85" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC85">Printing the Sign of an Amount of Money</A></H3>
<P>
These members of the <CODE>struct lconv</CODE> structure specify how to print
the sign (if any) in a monetary value.
<P>
<DL COMPACT>
<DT><CODE>char *positive_sign</CODE>
<DD><DT><CODE>char *negative_sign</CODE>
<DD>These are strings used to indicate positive (or zero) and negative
(respectively) monetary quantities.
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have a value of
<CODE>""</CODE> (the empty string), meaning "unspecified".
<P>
The ANSI standard doesn't say what to do when you find this value; we
recommend printing <CODE>positive_sign</CODE> as you find it, even if it is
empty.  For a negative value, print <CODE>negative_sign</CODE> as you find it
unless both it and <CODE>positive_sign</CODE> are empty, in which case print
<SAMP>`-'</SAMP> instead.  (Failing to indicate the sign at all seems rather
unreasonable.)
<P>
<DT><CODE>char p_sign_posn</CODE>
<DD><DT><CODE>char n_sign_posn</CODE>
<DD>These members have values that are small integers indicating how to
position the sign for nonnegative and negative monetary quantities,
respectively.  (The string used by the sign is what was specified with
<CODE>positive_sign</CODE> or <CODE>negative_sign</CODE>.)  The possible values are
as follows:
<P>
<DL COMPACT>
<DT><CODE>0</CODE>
<DD>The currency symbol and quantity should be surrounded by parentheses.
<P>
<DT><CODE>1</CODE>
<DD>Print the sign string before the quantity and currency symbol.
<P>
<DT><CODE>2</CODE>
<DD>Print the sign string after the quantity and currency symbol.
<P>
<DT><CODE>3</CODE>
<DD>Print the sign string right before the currency symbol.
<P>
<DT><CODE>4</CODE>
<DD>Print the sign string right after the currency symbol.
<P>
<DT><CODE>CHAR_MAX</CODE>
<DD>"Unspecified".  Both members have this value in the standard
<SAMP>`C'</SAMP> locale.
</DL>
<P>
The ANSI standard doesn't say what you should do when the value is
<CODE>CHAR_MAX</CODE>.  We recommend you print the sign after the currency
symbol.
</DL>
<P>
It is not clear whether you should let these members apply to the
international currency format or not.  POSIX says you should, but
intuition plus the examples in the ANSI C standard suggest you should
not.  We hope that someone who knows well the conventions for formatting
monetary quantities will tell us what we should recommend.
<P>
<P>Go to the <A HREF="library_6.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_6.html">previous</A>, <A HREF="library_8.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_8.html">next</A> section.<P>