localeconv.3p (11219B)
- '\" et
- .TH LOCALECONV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- localeconv
- \(em return locale-specific information
- .SH SYNOPSIS
- .LP
- .nf
- #include <locale.h>
- .P
- struct lconv *localeconv(void);
- .fi
- .SH DESCRIPTION
- The functionality described on this reference page is aligned with the
- ISO\ C standard. Any conflict between the requirements described here and the
- ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
- .P
- The
- \fIlocaleconv\fR()
- function shall set the components of an object with the type
- .BR "struct lconv"
- with the values appropriate for the formatting of numeric quantities
- (monetary and otherwise) according to the rules of the current locale.
- .P
- The members of the structure with type
- .BR "char *"
- are pointers to strings, any of which (except
- .BR decimal_point )
- can point to
- .BR \(dq\^\(dq ,
- to indicate that the value is not available in the current locale or is
- of zero length. The members with type
- .BR char
- are non-negative numbers, any of which can be
- {CHAR_MAX}
- to indicate that the value is not available in the current locale.
- .P
- The members include the following:
- .IP "\fBchar\ *decimal_point\fP" 6
- .br
- The radix character used to format non-monetary quantities.
- .IP "\fBchar\ *thousands_sep\fP" 6
- .br
- The character used to separate groups of digits before the
- decimal-point character in formatted non-monetary quantities.
- .IP "\fBchar\ *grouping\fP" 6
- .br
- A string whose elements taken as one-byte integer values indicate the
- size of each group of digits in formatted non-monetary quantities.
- .IP "\fBchar\ *int_curr_symbol\fP" 6
- .br
- 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:\|2001 standard. The
- fourth character (immediately preceding the null byte) is the character
- used to separate the international currency symbol from the monetary
- quantity.
- .IP "\fBchar\ *currency_symbol\fP" 6
- .br
- The local currency symbol applicable to the current locale.
- .IP "\fBchar\ *mon_decimal_point\fP" 6
- .br
- The radix character used to format monetary quantities.
- .IP "\fBchar\ *mon_thousands_sep\fP" 6
- .br
- The separator for groups of digits before the decimal-point in
- formatted monetary quantities.
- .IP "\fBchar\ *mon_grouping\fP" 6
- .br
- A string whose elements taken as one-byte integer values indicate the
- size of each group of digits in formatted monetary quantities.
- .IP "\fBchar\ *positive_sign\fP" 6
- .br
- The string used to indicate a non-negative valued formatted monetary
- quantity.
- .IP "\fBchar\ *negative_sign\fP" 6
- .br
- The string used to indicate a negative valued formatted monetary
- quantity.
- .IP "\fBchar\ int_frac_digits\fP" 6
- .br
- The number of fractional digits (those after the decimal-point) to be
- displayed in an internationally formatted monetary quantity.
- .IP "\fBchar\ frac_digits\fP" 6
- .br
- The number of fractional digits (those after the decimal-point) to be
- displayed in a formatted monetary quantity.
- .IP "\fBchar\ p_cs_precedes\fP" 6
- .br
- Set to 1 if the
- .BR currency_symbol
- precedes the value for a non-negative formatted monetary quantity. Set
- to 0 if the symbol succeeds the value.
- .IP "\fBchar\ p_sep_by_space\fP" 6
- .br
- Set to a value indicating the separation of the
- .BR currency_symbol ,
- the sign string, and the value for a non-negative formatted monetary
- quantity.
- .IP "\fBchar\ n_cs_precedes\fP" 6
- .br
- Set to 1 if the
- .BR currency_symbol
- precedes the value for a negative formatted monetary quantity. Set
- to 0 if the symbol succeeds the value.
- .IP "\fBchar\ n_sep_by_space\fP" 6
- .br
- Set to a value indicating the separation of the
- .BR currency_symbol ,
- the sign string, and the value for a negative formatted monetary
- quantity.
- .IP "\fBchar\ p_sign_posn\fP" 6
- .br
- Set to a value indicating the positioning of the
- .BR positive_sign
- for a non-negative formatted monetary quantity.
- .IP "\fBchar\ n_sign_posn\fP" 6
- .br
- Set to a value indicating the positioning of the
- .BR negative_sign
- for a negative formatted monetary quantity.
- .IP "\fBchar\ int_p_cs_precedes\fP" 6
- .br
- Set to 1 or 0 if the
- .BR int_curr_symbol
- respectively precedes or succeeds the value for a non-negative
- internationally formatted monetary quantity.
- .IP "\fBchar\ int_n_cs_precedes\fP" 6
- .br
- Set to 1 or 0 if the
- .BR int_curr_symbol
- respectively precedes or succeeds the value for a negative
- internationally formatted monetary quantity.
- .IP "\fBchar\ int_p_sep_by_space\fP" 6
- .br
- Set to a value indicating the separation of the
- .BR int_curr_symbol ,
- the sign string, and the value for a non-negative internationally
- formatted monetary quantity.
- .IP "\fBchar\ int_n_sep_by_space\fP" 6
- .br
- Set to a value indicating the separation of the
- .BR int_curr_symbol ,
- the sign string, and the value for a negative internationally formatted
- monetary quantity.
- .IP "\fBchar\ int_p_sign_posn\fP" 6
- .br
- Set to a value indicating the positioning of the
- .BR positive_sign
- for a non-negative internationally formatted monetary quantity.
- .IP "\fBchar\ int_n_sign_posn\fP" 6
- .br
- Set to a value indicating the positioning of the
- .BR negative_sign
- for a negative internationally formatted monetary quantity.
- .P
- The elements of
- .BR grouping
- and
- .BR mon_grouping
- are interpreted according to the following:
- .IP {CHAR_MAX} 12
- No further grouping is to be performed.
- .IP 0 12
- The previous element is to be repeatedly used for the remainder of the
- digits.
- .IP "\fIother\fP" 12
- 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.
- .P
- The values of
- .BR p_sep_by_space ,
- .BR n_sep_by_space ,
- .BR int_p_sep_by_space ,
- and
- .BR int_n_sep_by_space
- are interpreted according to the following:
- .IP 0 6
- No space separates the currency symbol and value.
- .IP 1 6
- 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.
- .IP 2 6
- If the currency symbol and sign string are adjacent, a space separates
- them; otherwise, a space separates the sign string from the value.
- .P
- For
- .BR int_p_sep_by_space
- and
- .BR int_n_sep_by_space ,
- the fourth character of
- .BR int_curr_symbol
- is used instead of a space.
- .P
- The values of
- .BR p_sign_posn ,
- .BR n_sign_posn ,
- .BR int_p_sign_posn ,
- and
- .BR int_n_sign_posn
- are interpreted according to the following:
- .IP 0 6
- Parentheses surround the quantity and
- .BR currency_symbol
- or
- .BR int_curr_symbol .
- .IP 1 6
- The sign string precedes the quantity and
- .BR currency_symbol
- or
- .BR int_curr_symbol .
- .IP 2 6
- The sign string succeeds the quantity and
- .BR currency_symbol
- or
- .BR int_curr_symbol .
- .IP 3 6
- The sign string immediately precedes the
- .BR currency_symbol
- or
- .BR int_curr_symbol .
- .IP 4 6
- The sign string immediately succeeds the
- .BR currency_symbol
- or
- .BR int_curr_symbol .
- .P
- The implementation shall behave as if no function in this volume of POSIX.1\(hy2017 calls
- \fIlocaleconv\fR().
- .P
- The
- \fIlocaleconv\fR()
- function need not be thread-safe.
- .SH "RETURN VALUE"
- The
- \fIlocaleconv\fR()
- function shall return a pointer to the filled-in object. The application
- shall not modify the structure to which the return value points,
- nor any storage areas pointed to by pointers within the structure. The
- returned pointer, and pointers within the structure, might be
- invalidated or
- the structure
- or the storage areas
- might be overwritten by a subsequent call to
- \fIlocaleconv\fR().
- In addition,
- the returned pointer, and pointers within the structure, might be
- invalidated or
- the structure
- or the storage areas
- might be overwritten by subsequent calls to
- \fIsetlocale\fR()
- with the categories LC_ALL, LC_MONETARY, or LC_NUMERIC,
- or by calls to
- \fIuselocale\fR()
- which change the categories LC_MONETARY or LC_NUMERIC. The returned
- pointer, pointers within the structure, the structure, and the
- storage areas might also be invalidated if the calling thread is
- terminated.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- The following table illustrates the rules which may be used by four
- countries to format monetary quantities.
- .TS
- center box tab(!);
- cB | cB | cB | cB
- l | l | l | l.
- Country!Positive Format!Negative Format!International Format
- _
- Italy!\(eu.1.230!\-\(eu.1.230!EUR.1.230
- Netherlands!\(eu 1.234,56!\(eu \-1.234,56!EUR 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
- .P
- For these four countries, the respective values for the monetary
- members of the structure returned by
- \fIlocaleconv\fR()
- are:
- .TS
- center box tab(!);
- cB | cB | cB | cB | cB
- lb | cf5 | cf5 | cf5 | cf5.
- !Italy!Netherlands!Norway!Switzerland
- _
- int_curr_symbol!"EUR."!"EUR "!"NOK "!"CHF "
- currency_symbol!"\(eu."!"\(eu"!"kr"!"SFrs."
- mon_decimal_point!""!","!","!"."
- mon_thousands_sep!"."!"."!"."!","
- mon_grouping!"\e3"!"\e3"!"\e3"!"\e3"
- positive_sign!""!""!""!""
- negative_sign!"-"!"-"!"-"!"C"
- int_frac_digits!0!2!2!2
- frac_digits!0!2!2!2
- p_cs_precedes!1!1!1!1
- p_sep_by_space!0!1!0!0
- n_cs_precedes!1!1!1!1
- n_sep_by_space!0!1!0!0
- p_sign_posn!1!1!1!1
- n_sign_posn!1!4!2!2
- int_p_cs_precedes!1!1!1!1
- int_n_cs_precedes!1!1!1!1
- int_p_sep_by_space!0!0!0!0
- int_n_sep_by_space!0!0!0!0
- int_p_sign_posn!1!1!1!1
- int_n_sign_posn!1!4!4!2
- .TE
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIfprintf\fR\^(\|)",
- .IR "\fIfscanf\fR\^(\|)",
- .IR "\fIisalpha\fR\^(\|)",
- .IR "\fIisascii\fR\^(\|)",
- .IR "\fInl_langinfo\fR\^(\|)",
- .IR "\fIsetlocale\fR\^(\|)",
- .IR "\fIstrcat\fR\^(\|)",
- .IR "\fIstrchr\fR\^(\|)",
- .IR "\fIstrcmp\fR\^(\|)",
- .IR "\fIstrcoll\fR\^(\|)",
- .IR "\fIstrcpy\fR\^(\|)",
- .IR "\fIstrftime\fR\^(\|)",
- .IR "\fIstrlen\fR\^(\|)",
- .IR "\fIstrpbrk\fR\^(\|)",
- .IR "\fIstrspn\fR\^(\|)",
- .IR "\fIstrtok\fR\^(\|)",
- .IR "\fIstrxfrm\fR\^(\|)",
- .IR "\fIstrtod\fR\^(\|)",
- .IR "\fIuselocale\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<langinfo.h>\fP",
- .IR "\fB<locale.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .