1LOCALECONV(3P)             POSIX Programmer's Manual            LOCALECONV(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       localeconv — return locale-specific information
14

SYNOPSIS

16       #include <locale.h>
17
18       struct lconv *localeconv(void);
19

DESCRIPTION

21       The functionality described on this reference page is aligned with  the
22       ISO C  standard.  Any  conflict between the requirements described here
23       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2008
24       defers to the ISO C standard.
25
26       The  localeconv()  function  shall set the components of an object with
27       the type struct lconv with the values appropriate for the formatting of
28       numeric  quantities  (monetary and otherwise) according to the rules of
29       the current locale.
30
31       The members of the structure with type char * are pointers to  strings,
32       any  of  which (except decimal_point) can point to "", to indicate that
33       the value is not available in the current locale or is of zero  length.
34       The  members  with type char are non-negative numbers, any of which can
35       be {CHAR_MAX} to indicate that the value is not available in  the  cur‐
36       rent locale.
37
38       The members include the following:
39
40       char *decimal_point
41             The radix character used to format non-monetary quantities.
42
43       char *thousands_sep
44             The  character used to separate groups of digits before the deci‐
45             mal-point character in formatted non-monetary quantities.
46
47       char *grouping
48             A string whose elements taken as one-byte integer values indicate
49             the  size of each group of digits in formatted non-monetary quan‐
50             tities.
51
52       char *int_curr_symbol
53             The international  currency  symbol  applicable  to  the  current
54             locale.  The first three characters contain the alphabetic inter‐
55             national currency symbol in accordance with  those  specified  in
56             the  ISO 4217:2001  standard.  The  fourth character (immediately
57             preceding the null byte) is the character used  to  separate  the
58             international currency symbol from the monetary quantity.
59
60       char *currency_symbol
61             The local currency symbol applicable to the current locale.
62
63       char *mon_decimal_point
64             The radix character used to format monetary quantities.
65
66       char *mon_thousands_sep
67             The  separator  for  groups of digits before the decimal-point in
68             formatted monetary quantities.
69
70       char *mon_grouping
71             A string whose elements taken as one-byte integer values indicate
72             the  size  of  each group of digits in formatted monetary quanti‐
73             ties.
74
75       char *positive_sign
76             The string used to indicate a non-negative valued formatted mone‐
77             tary quantity.
78
79       char *negative_sign
80             The  string used to indicate a negative valued formatted monetary
81             quantity.
82
83       char int_frac_digits
84             The number of fractional digits (those after  the  decimal-point)
85             to  be  displayed  in an internationally formatted monetary quan‐
86             tity.
87
88       char frac_digits
89             The number of fractional digits (those after  the  decimal-point)
90             to be displayed in a formatted monetary quantity.
91
92       char p_cs_precedes
93             Set to 1 if the currency_symbol precedes the value for a non-neg‐
94             ative formatted monetary quantity. Set to 0 if  the  symbol  suc‐
95             ceeds the value.
96
97       char p_sep_by_space
98             Set  to a value indicating the separation of the currency_symbol,
99             the sign string, and the value for a non-negative formatted mone‐
100             tary quantity.
101
102       char n_cs_precedes
103             Set to 1 if the currency_symbol precedes the value for a negative
104             formatted monetary quantity. Set to 0 if the symbol succeeds  the
105             value.
106
107       char n_sep_by_space
108             Set  to a value indicating the separation of the currency_symbol,
109             the sign string, and the value for a negative formatted  monetary
110             quantity.
111
112       char p_sign_posn
113             Set  to  a  value indicating the positioning of the positive_sign
114             for a non-negative formatted monetary quantity.
115
116       char n_sign_posn
117             Set to a value indicating the positioning  of  the  negative_sign
118             for a negative formatted monetary quantity.
119
120       char int_p_cs_precedes
121             Set  to  1  or  0 if the int_curr_symbol respectively precedes or
122             succeeds the value for a non-negative  internationally  formatted
123             monetary quantity.
124
125       char int_n_cs_precedes
126             Set  to  1  or  0 if the int_curr_symbol respectively precedes or
127             succeeds the value for a negative internationally formatted mone‐
128             tary quantity.
129
130       char int_p_sep_by_space
131             Set  to a value indicating the separation of the int_curr_symbol,
132             the sign string, and the value for a non-negative internationally
133             formatted monetary quantity.
134
135       char int_n_sep_by_space
136             Set  to a value indicating the separation of the int_curr_symbol,
137             the sign string, and the value  for  a  negative  internationally
138             formatted monetary quantity.
139
140       char int_p_sign_posn
141             Set  to  a  value indicating the positioning of the positive_sign
142             for a non-negative internationally formatted monetary quantity.
143
144       char int_n_sign_posn
145             Set to a value indicating the positioning  of  the  negative_sign
146             for a negative internationally formatted monetary quantity.
147
148       The  elements of grouping and mon_grouping are interpreted according to
149       the following:
150
151       {CHAR_MAX}  No further grouping is to be performed.
152
153       0           The previous element is  to  be  repeatedly  used  for  the
154                   remainder of the digits.
155
156       other       The integer value is the number of digits that comprise the
157                   current group. The next element is  examined  to  determine
158                   the  size  of  the  next group of digits before the current
159                   group.
160
161       The values of p_sep_by_space, n_sep_by_space,  int_p_sep_by_space,  and
162       int_n_sep_by_space are interpreted according to the following:
163
164       0     No space separates the currency symbol and value.
165
166       1     If the currency symbol and sign string are adjacent, a space sep‐
167             arates them from the value; otherwise, a space separates the cur‐
168             rency symbol from the value.
169
170       2     If the currency symbol and sign string are adjacent, a space sep‐
171             arates them; otherwise, a space separates the  sign  string  from
172             the value.
173
174       For  int_p_sep_by_space and int_n_sep_by_space, the fourth character of
175       int_curr_symbol is used instead of a space.
176
177       The  values   of   p_sign_posn,   n_sign_posn,   int_p_sign_posn,   and
178       int_n_sign_posn are interpreted according to the following:
179
180       0     Parentheses   surround   the   quantity  and  currency_symbol  or
181             int_curr_symbol.
182
183       1     The sign string precedes  the  quantity  and  currency_symbol  or
184             int_curr_symbol.
185
186       2     The  sign  string  succeeds  the  quantity and currency_symbol or
187             int_curr_symbol.
188
189       3     The sign  string  immediately  precedes  the  currency_symbol  or
190             int_curr_symbol.
191
192       4     The  sign  string  immediately  succeeds  the  currency_symbol or
193             int_curr_symbol.
194
195       The implementation shall behave as if no function  in  this  volume  of
196       POSIX.1‐2008 calls localeconv().
197
198       The localeconv() function need not be thread-safe.
199

RETURN VALUE

201       The  localeconv()  function  shall  return  a  pointer to the filled-in
202       object. The application shall not modify the  structure  to  which  the
203       return  value  points,  nor  any  storage  areas pointed to by pointers
204       within the structure. The returned pointer,  and  pointers  within  the
205       structure,  might  be invalidated or the structure or the storage areas
206       might be overwritten by a subsequent call to  localeconv().   In  addi‐
207       tion, the returned pointer, and pointers within the structure, might be
208       invalidated or the structure or the storage areas might be  overwritten
209       by subsequent calls to setlocale() with the categories LC_ALL, LC_MONE‐
210       TARY, or LC_NUMERIC, or by calls to uselocale() which change the  cate‐
211       gories LC_MONETARY or LC_NUMERIC.
212

ERRORS

214       No errors are defined.
215
216       The following sections are informative.
217

EXAMPLES

219       None.
220

APPLICATION USAGE

222       The  following  table  illustrates  the rules which may be used by four
223       countries to format monetary quantities.
224
225       ┌────────────┬─────────────────┬─────────────────┬──────────────────────┐
226Country   Positive Format Negative Format International Format 
227       ├────────────┼─────────────────┼─────────────────┼──────────────────────┤
228       │Italy       │ €.1.230         │ −€.1.230        │ EUR.1.230            │
229       │Netherlands │ € 1.234,56      │ € −1.234,56     │ EUR 1.234,56         │
230       │Norway      │ kr1.234,56      │ kr1.234,56−     │ NOK 1.234,56         │
231       │Switzerland │ SFrs.1,234.56   │ SFrs.1,234.56C  │ CHF 1,234.56         │
232       └────────────┴─────────────────┴─────────────────┴──────────────────────┘
233       For these four countries, the respective values for the  monetary  mem‐
234       bers of the structure returned by localeconv() are:
235
236         ┌───────────────────┬────────┬─────────────┬────────┬─────────────┐
237         │                   │ Italy  Netherlands Norway Switzerland 
238         ├───────────────────┼────────┼─────────────┼────────┼─────────────┤
239int_curr_symbol    │ "EUR." │   "EUR "    │ "NOK " │   "CHF "    │
240currency_symbol    │  "€."  │     "€"     │  "kr"  │   "SFrs."   │
241mon_decimal_point  │   ""   │     ","     │  ","   │     "."     │
242mon_thousands_sep  │  "."   │     "."     │  "."   │     ","     │
243mon_grouping       │  "\3"  │    "\3"     │  "\3"  │    "\3"     │
244positive_sign      │   ""   │     ""      │   ""   │     ""      │
245negative_sign      │  "-"   │     "-"     │  "-"   │     "C"     │
246int_frac_digits    │   0    │      2      │   2    │      2      │
247frac_digits        │   0    │      2      │   2    │      2      │
248p_cs_precedes      │   1    │      1      │   1    │      1      │
249p_sep_by_space     │   0    │      1      │   0    │      0      │
250n_cs_precedes      │   1    │      1      │   1    │      1      │
251n_sep_by_space     │   0    │      1      │   0    │      0      │
252p_sign_posn        │   1    │      1      │   1    │      1      │
253n_sign_posn        │   1    │      4      │   2    │      2      │
254int_p_cs_precedes  │   1    │      1      │   1    │      1      │
255int_n_cs_precedes  │   1    │      1      │   1    │      1      │
256int_p_sep_by_space │   0    │      0      │   0    │      0      │
257int_n_sep_by_space │   0    │      0      │   0    │      0      │
258int_p_sign_posn    │   1    │      1      │   1    │      1      │
259int_n_sign_posn    │   1    │      4      │   4    │      2      │
260         └───────────────────┴────────┴─────────────┴────────┴─────────────┘

RATIONALE

262       None.
263

FUTURE DIRECTIONS

265       None.
266

SEE ALSO

268       fprintf(),  fscanf(), isalpha(), isascii(), nl_langinfo(), setlocale(),
269       strcat(),  strchr(),   strcmp(),   strcoll(),   strcpy(),   strftime(),
270       strlen(),  strpbrk(),  strspn(),  strtok(), strxfrm(), strtod(), uselo‐
271       cale()
272
273       The Base Definitions volume of POSIX.1‐2008, <langinfo.h>, <locale.h>
274
276       Portions of this text are reprinted and reproduced in  electronic  form
277       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
278       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
279       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
280       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
281       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
282       event of any discrepancy between this version and the original IEEE and
283       The  Open Group Standard, the original IEEE and The Open Group Standard
284       is the referee document. The original Standard can be  obtained  online
285       at http://www.unix.org/online.html .
286
287       Any  typographical  or  formatting  errors that appear in this page are
288       most likely to have been introduced during the conversion of the source
289       files  to  man page format. To report such errors, see https://www.ker
290       nel.org/doc/man-pages/reporting_bugs.html .
291
292
293
294IEEE/The Open Group                  2013                       LOCALECONV(3P)
Impressum