path: root/man3p/localeconv.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "LOCALECONV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" localeconv 
.SH NAME
localeconv \- return locale-specific information
.SH SYNOPSIS
.LP
\fB#include <locale.h>
.br
.sp
struct lconv *localeconv(void);
.br
\fP
.SH DESCRIPTION
.LP
The \fIlocaleconv\fP() function shall set the components of an object
with the type \fBstruct lconv\fP with the values
appropriate for the formatting of numeric quantities (monetary and
otherwise) according to the rules of the current locale.
.LP
The members of the structure with type \fBchar *\fP are pointers to
strings, any of which (except \fBdecimal_point\fP) can
point to \fB""\fP , to indicate that the value is not available in
the current locale or is of zero length. The members with
type \fBchar\fP are non-negative numbers, any of which can be {CHAR_MAX}
to indicate that the value is not available in the
current locale.
.LP
The members include the following:
.TP 7
\fBchar\ *decimal_point\fP
.sp
The radix character used to format non-monetary quantities.
.TP 7
\fBchar\ *thousands_sep\fP
.sp
The character used to separate groups of digits before the decimal-point
character in formatted non-monetary quantities.
.TP 7
\fBchar\ *grouping\fP
.sp
A string whose elements taken as one-byte integer values indicate
the size of each group of digits in formatted non-monetary
quantities.
.TP 7
\fBchar\ *int_curr_symbol\fP
.sp
The international currency symbol applicable to the current locale.
The first three characters contain the alphabetic international
currency symbol in accordance with those specified in the ISO\ 4217:1995
standard. The fourth character (immediately preceding
the null byte) is the character used to separate the international
currency symbol from the monetary quantity.
.TP 7
\fBchar\ *currency_symbol\fP
.sp
The local currency symbol applicable to the current locale.
.TP 7
\fBchar\ *mon_decimal_point\fP
.sp
The radix character used to format monetary quantities.
.TP 7
\fBchar\ *mon_thousands_sep\fP
.sp
The separator for groups of digits before the decimal-point in formatted
monetary quantities.
.TP 7
\fBchar\ *mon_grouping\fP
.sp
A string whose elements taken as one-byte integer values indicate
the size of each group of digits in formatted monetary
quantities.
.TP 7
\fBchar\ *positive_sign\fP
.sp
The string used to indicate a non-negative valued formatted monetary
quantity.
.TP 7
\fBchar\ *negative_sign\fP
.sp
The string used to indicate a negative valued formatted monetary quantity.
.TP 7
\fBchar\ int_frac_digits\fP
.sp
The number of fractional digits (those after the decimal-point) to
be displayed in an internationally formatted monetary
quantity.
.TP 7
\fBchar\ frac_digits\fP
.sp
The number of fractional digits (those after the decimal-point) to
be displayed in a formatted monetary quantity.
.TP 7
\fBchar\ p_cs_precedes\fP
.sp
Set to 1 if the \fBcurrency_symbol\fP precedes the value for a non-negative
formatted monetary quantity. Set to 0 if the symbol
succeeds the value.
.TP 7
\fBchar\ p_sep_by_space\fP
.sp
Set to a value indicating the separation of the \fBcurrency_symbol\fP,
the sign string, and the value for a non-negative formatted
monetary quantity.
.TP 7
\fBchar\ n_cs_precedes\fP
.sp
Set to 1 if the \fBcurrency_symbol\fP precedes the value for a negative
formatted monetary quantity. Set to 0 if the symbol
succeeds the value.
.TP 7
\fBchar\ n_sep_by_space\fP
.sp
Set to a value indicating the separation of the \fBcurrency_symbol\fP,
the sign string, and the value for a negative formatted
monetary quantity.
.TP 7
\fBchar\ p_sign_posn\fP
.sp
Set to a value indicating the positioning of the \fBpositive_sign\fP
for a non-negative formatted monetary quantity.
.TP 7
\fBchar\ n_sign_posn\fP
.sp
Set to a value indicating the positioning of the \fBnegative_sign\fP
for a negative formatted monetary quantity.
.TP 7
\fBchar\ int_p_cs_precedes\fP
.sp
Set to 1 or 0 if the \fBint_curr_symbol\fP respectively precedes or
succeeds the value for a non-negative internationally
formatted monetary quantity.
.TP 7
\fBchar\ int_n_cs_precedes\fP
.sp
Set to 1 or 0 if the \fBint_curr_symbol\fP respectively precedes or
succeeds the value for a negative internationally formatted
monetary quantity.
.TP 7
\fBchar\ int_p_sep_by_space\fP
.sp
Set to a value indicating the separation of the \fBint_curr_symbol\fP,
the sign string, and the value for a non-negative
internationally formatted monetary quantity.
.TP 7
\fBchar\ int_n_sep_by_space\fP
.sp
Set to a value indicating the separation of the \fBint_curr_symbol\fP,
the sign string, and the value for a negative
internationally formatted monetary quantity.
.TP 7
\fBchar\ int_p_sign_posn\fP
.sp
Set to a value indicating the positioning of the \fBpositive_sign\fP
for a non-negative internationally formatted monetary
quantity.
.TP 7
\fBchar\ int_n_sign_posn\fP
.sp
Set to a value indicating the positioning of the \fBnegative_sign\fP
for a negative internationally formatted monetary
quantity.
.sp
.LP
The elements of \fBgrouping\fP and \fBmon_grouping\fP are interpreted
according to the following:
.TP 7
{CHAR_MAX}
No further grouping is to be performed.
.TP 7
0
The previous element is to be repeatedly used for the remainder of
the digits.
.TP 7
\fIother\fP
The integer value is the number of digits that comprise the current
group. The next element is examined to determine the size
of the next group of digits before the current group.
.sp
.LP
The values of \fBp_sep_by_space\fP, \fBn_sep_by_space\fP, \fBint_p_sep_by_space\fP,
and \fBint_n_sep_by_space\fP are
interpreted according to the following:
.TP 7
0
No space separates the currency symbol and value.
.TP 7
1
If the currency symbol and sign string are adjacent, a space separates
them from the value; otherwise, a space separates the
currency symbol from the value.
.TP 7
2
If the currency symbol and sign string are adjacent, a space separates
them; otherwise, a space separates the sign string from
the value.
.sp
.LP
For \fBint_p_sep_by_space\fP and \fBint_n_sep_by_space\fP, the fourth
character of \fBint_curr_symbol\fP is used instead of a
space.
.LP
The values of \fBp_sign_posn\fP, \fBn_sign_posn\fP, \fBint_p_sign_posn\fP,
and \fBint_n_sign_posn\fP are interpreted
according to the following:
.TP 7
0
Parentheses surround the quantity and \fBcurrency_symbol\fP or \fBint_curr_symbol\fP.
.TP 7
1
The sign string precedes the quantity and \fBcurrency_symbol\fP or
\fBint_curr_symbol\fP.
.TP 7
2
The sign string succeeds the quantity and \fBcurrency_symbol\fP or
\fBint_curr_symbol\fP.
.TP 7
3
The sign string immediately precedes the \fBcurrency_symbol\fP or
\fBint_curr_symbol\fP.
.TP 7
4
The sign string immediately succeeds the \fBcurrency_symbol\fP or
\fBint_curr_symbol\fP.
.sp
.LP
The implementation shall behave as if no function in this volume of
IEEE\ Std\ 1003.1-2001 calls
\fIlocaleconv\fP().
.LP
The
\fIlocaleconv\fP() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe. 
.SH RETURN VALUE
.LP
The \fIlocaleconv\fP() function shall return a pointer to the filled-in
object. The application shall not modify the structure
pointed to by the return value which may be overwritten by a subsequent
call to \fIlocaleconv\fP(). In addition, calls to \fIsetlocale\fP()
with the categories \fILC_ALL ,\fP \fILC_MONETARY ,\fP or \fILC_NUMERIC\fP
may overwrite the contents of the structure.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The following table illustrates the rules which may be used by four
countries to format monetary quantities.
.TS C
center; l1 l1 l1 l.
\fBCountry\fP	\fBPositive Format\fP	\fBNegative Format\fP	\fBInternational Format\fP
Italy	L.1.230	-L.1.230	ITL.1.230
Netherlands	F 1.234,56	F -1.234,56	NLG 1.234,56
Norway	kr1.234,56	kr1.234,56-	NOK 1.234,56
Switzerland	SFrs.1,234.56	SFrs.1,234.56C	CHF 1,234.56
.TE
.LP
For these four countries, the respective values for the monetary members
of the structure returned by \fIlocaleconv\fP()
are:
.TS C
center; l2 l2 l2 l2 l.
\fB\ \fP	\fBItaly\fP	\fBNetherlands\fP	\fBNorway\fP	\fBSwitzerland\fP
\fBint_curr_symbol\fP	"ITL."	"NLG "	"NOK "	"CHF "
\fBcurrency_symbol\fP	"L."	"F"	"kr"	"SFrs."
\fBmon_decimal_point\fP	""	","	","	"."
\fBmon_thousands_sep\fP	"."	"."	"."	","
\fBmon_grouping\fP	"\\3"	"\\3"	"\\3"	"\\3"
\fBpositive_sign\fP	""	""	""	""
\fBnegative_sign\fP	"-"	"-"	"-"	"C"
\fBint_frac_digits\fP	0	2	2	2
\fBfrac_digits\fP	0	2	2	2
\fBp_cs_precedes\fP	1	1	1	1
\fBp_sep_by_space\fP	0	1	0	0
\fBn_cs_precedes\fP	1	1	1	1
\fBn_sep_by_space\fP	0	1	0	0
\fBp_sign_posn\fP	1	1	1	1
\fBn_sign_posn\fP	1	4	2	2
\fBint_p_cs_precedes\fP	1	1	1	1
\fBint_n_cs_precedes\fP	1	1	1	1
\fBint_p_sep_by_space\fP	0	0	0	0
\fBint_n_sep_by_space\fP	0	0	0	0
\fBint_p_sign_posn\fP	1	1	1	1
\fBint_n_sign_posn\fP	1	4	4	2
.TE
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIisalpha\fP() , \fIisascii\fP() , \fInl_langinfo\fP() , \fIprintf\fP()
, \fIscanf\fP() ,
\fIsetlocale\fP() , \fIstrcat\fP() , \fIstrchr\fP() , \fIstrcmp\fP()
, \fIstrcoll\fP() , \fIstrcpy\fP() , \fIstrftime\fP() , \fIstrlen\fP()
, \fIstrpbrk\fP() , \fIstrspn\fP() , \fIstrtok\fP() , \fIstrxfrm\fP()
, \fIstrtod\fP() , the
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<langinfo.h>\fP,
\fI<locale.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .