mirror of https://github.com/mkerrisk/man-pages
318 lines
9.8 KiB
Plaintext
318 lines
9.8 KiB
Plaintext
.\" 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 .
|