1localeconv(3C)           Standard C Library Functions           localeconv(3C)
2
3
4

NAME

6       localeconv - get numeric formatting information
7

SYNOPSIS

9       #include <locale.h>
10
11       struct lconv *localeconv(void);
12
13

DESCRIPTION

15       The  localeconv()  function  sets the components of an object with type
16       struct lconv (defined in <locale.h>) with the  values  appropriate  for
17       the formatting of numeric quantities (monetary and otherwise) according
18       to the rules of the current locale (see setlocale(3C)). The  definition
19       of  struct  lconv is given  below (the values for the fields in the "C"
20       locale are given in comments).
21
22         char *decimal_point;        /* "." */
23         char *thousands_sep;        /* "" (zero length string) */
24         char *grouping;             /* "" */
25         char *int_curr_symbol;      /* "" */
26         char *currency_symbol;      /* "" */
27         char *mon_decimal_point;    /* "" */
28         char *mon_thousands_sep;    /* "" */
29         char *mon_grouping;         /* "" */
30         char *positive_sign;        /* "" */
31         char *negative_sign;        /* "" */
32         char int_frac_digits;       /* CHAR_MAX */
33         char frac_digits;           /* CHAR_MAX */
34         char p_cs_precedes;         /* CHAR_MAX */
35         char p_sep_by_space;        /* CHAR_MAX */
36         char n_cs_precedes;         /* CHAR_MAX */
37         char n_sep_by_space;        /* CHAR_MAX */
38         char p_sign_posn;           /* CHAR_MAX*/
39         char n_sign_posn;           /* CHAR_MAX */
40
41
42
43       The following members are also available to  SUSv3-conforming  applica‐
44       tions. See standards(5)
45
46         char int_p_cs_precedes;     /* CHAR_MAX */
47         char int_p_sep_by_space;    /* CHAR_MAX */
48         char int_n_cs_precedes;     /* CHAR_MAX */
49         char int_n_sep_by_space;    /* CHAR_MAX */
50         char int_p_sign_posn;       /* CHAR_MAX */
51         char int_n_sign_posn;       /* CHAR_MAX */
52
53
54
55       The members of the structure with type char * are strings, any of which
56       (except decimal_point) can point to a null  string  (""),  to  indicate
57       that  the  value  is  not available in the current locale or is of zero
58       length. The members with type char are  non-negative  numbers,  any  of
59       which  can  be  CHAR_MAX (defined in the <limits.h> header) to indicate
60       that the value is not available in the current locale. The members  are
61       the following:
62
63       char *decimal_point        The  decimal-point  character used to format
64                                  non-monetary quantities.
65
66
67       char *thousands_sep        The character used  to  separate  groups  of
68                                  digits  to  the  left  of  the decimal-point
69                                  character in formatted non-monetary  quanti‐
70                                  ties.
71
72
73       char *grouping             A  string  whose  elements taken as one-byte
74                                  integer values indicate  the  size  of  each
75                                  group  of  digits  in formatted non-monetary
76                                  quantities.
77
78
79       char *int_curr_symbol      The international currency symbol applicable
80                                  to the current locale. The first three char‐
81                                  acters contain the alphabetic  international
82                                  currency  symbol  in  accordance  with those
83                                  specified in the ISO  4217:  1995  standard.
84                                  The  fourth character (immediately preceding
85                                  the null byte) is the character used to sep‐
86                                  arate the international currency symbol from
87                                  the monetary quantity.
88
89
90       char *currency_symbol      The local currency symbol applicable to  the
91                                  current locale.
92
93
94       char *mon_decimal_point    The  decimal  point  used to format monetary
95                                  quantities.
96
97
98       char *mon_thousands_sep    The separator for groups of  digits  to  the
99                                  left of the decimal point in formatted mone‐
100                                  tary quantities.
101
102
103       char *mon_grouping         A string whose elements  taken  as  one-byte
104                                  integer  values  indicate  the  size of each
105                                  group of digits in formatted monetary  quan‐
106                                  tities.
107
108
109       char *positive_sign        The  string used to indicate a non-negative-
110                                  valued formatted monetary quantity.
111
112
113       char *negative_sign        The string used to indicate a  negative-val‐
114                                  ued formatted monetary quantity.
115
116
117       char int_frac_digits       The  number  of  fractional digits (those to
118                                  the right of the decimal point) to  be  dis‐
119                                  played in an internationally formatted mone‐
120                                  tary quantity.
121
122
123       char frac_digits           The number of fractional  digits  (those  to
124                                  the  right  of the decimal point) to be dis‐
125                                  played in a formatted monetary quantity.
126
127
128       char p_cs_precedes         Set to 1 or 0 if the currency_symbol respec‐
129                                  tively  precedes or succeeds the value for a
130                                  non-negative formatted monetary quantity.
131
132
133       char p_sep_by_space        Set to 0 if  no  space  separates  the  cur‐
134                                  rency_symbol  or  int_curr_symbol  from  the
135                                  value for a non-negative formatted  monetary
136                                  quantity.  Set to 1 if a space separates the
137                                  symbol from the value; and set  to  2  if  a
138                                  space  separates  the  symbol  and  the sign
139                                  string, if adjacent.
140
141
142       char n_cs_precedes         Set to 1 or 0 if the currency_symbol respec‐
143                                  tively  precedes or succeeds the value for a
144                                  negative formatted monetary quantity.
145
146
147       char n_sep_by_space        Set to 0 if  no  space  separates  the  cur‐
148                                  rency_symbol  or  int_curr_symbol  from  the
149                                  value  for  a  negative  formatted  monetary
150                                  quantity.  Set to 1 if a space separates the
151                                  symbol from the value; and set  to  2  if  a
152                                  space  separates  the  symbol  and  the sign
153                                  string, if adjacent.
154
155
156       char p_sign_posn           Set to a value indicating the positioning of
157                                  the positive_sign for a non-negative format‐
158                                  ted monetary quantity.
159
160
161       char n_sign_posn           Set to a value indicating the positioning of
162                                  the  negative_sign  for a negative formatted
163                                  monetary quantity.
164
165
166       char int_p_cs_precedes     Set to 1 or 0 if the int_curr_symbol respec‐
167                                  tively  precedes or succeeds the value for a
168                                  non-negative internationally formatted mone‐
169                                  tary quantity.
170
171
172       char int_n_cs_precedes     Set to 1 or 0 if the int_curr_symbol respec‐
173                                  tively precedes or succeeds the value for  a
174                                  negative  internationally formatted monetary
175                                  quantity.
176
177
178       char int_p_sep_by_space    Set to a value indicating the separation  of
179                                  the  int_curr_symbol,  the  sign string, and
180                                  the value for a non-negative internationally
181                                  formatted monetary quantity.
182
183
184       char int_n_sep_by_space    Set  to a value indicating the separation of
185                                  the int_curr_symbol, the  sign  string,  and
186                                  the  value  for  a  negative internationally
187                                  formatted monetary quantity.
188
189
190       char int_p_sign_posn       Set to a value indicating the positioning of
191                                  the  positive_sign for a non-negative inter‐
192                                  nationally formatted monetary quantity.
193
194
195       char int_n_sign_posn       Set to a value indicating the positioning of
196                                  the  negative_sign  for  a negative interna‐
197                                  tionally formatted monetary quantity.
198
199
200
201       The elements of grouping and mon_grouping are interpreted according  to
202       the following:
203
204       {CHAR_MAX}    No further grouping is to be performed.
205
206
207       0             The  previous  element  is  to be repeatedly used for the
208                     remainder of the digits.
209
210
211       other         The integer value is the number of digits  that  comprise
212                     the current group. The next element is examined to deter‐
213                     mine the size of the next group of digits before the cur‐
214                     rent group.
215
216
217
218       The  values  of p_sep_by_space, n_sep_by_space, int_p_sep_by_space, and
219       int_n_sep_by_space are interpreted according to the following:
220
221       0    No space separates the currency symbol and value.
222
223
224       1    If the currency symbol and sign string are adjacent, a space sepa‐
225            rates  them  from the value; otherwise, a space separates the cur‐
226            rency symbol from the value.
227
228
229       2    If the currency symbol and sign string are adjacent, a space sepa‐
230            rates  them; otherwise, a space separates the sign string from the
231            value.
232
233
234
235       In  an  SUSv3-conforming  application,   for   int_p_sep_by_space   and
236       int_n_sep_by_space,  the  fourth  character  of int_curr_symbol is used
237       instead of a space.
238
239
240       The  values   of   p_sign_posn,   n_sign_posn,   int_p_sign_posn,   and
241       int_n_sign_posn are interpreted according to the following:
242
243       0    Parentheses   surround   the   quantity   and  currency_symbol  or
244            int_curr_symbol.
245
246
247       1    The sign string  precedes  the  quantity  and  currency_symbol  or
248            int_curr_symbol.
249
250
251       2    The  sign  string  succeeds  the  quantity  and currency_symbol or
252            int_curr_symbol.
253
254
255       3    The  sign  string  immediately  precedes  the  currency_symbol  or
256            int_curr_symbol.
257
258
259       4    The  sign  string  immediately  succeeds  the  currency_symbol  or
260            int_curr_symbol.
261
262

RETURN VALUES

264       The localeconv() function returns a pointer to  the  filled-in  object.
265       The  structure  pointed to by the return value may be overwritten  by a
266       subsequent call to localeconv().
267

EXAMPLES

269       Example 1 Rules used by four countries to format monetary quantities.
270
271
272       The following table illustrates the rules used  by  four  countries  to
273       format monetary quantities.
274
275
276
277
278                        │                │                │
279       Country          Positive       Negative       International
280       ─────────────────┼────────────────┼────────────────┼────────────────
281       Italy (IT)       │ L.1.234        │ −L.1.234       │ ITL.1.234
282       ─────────────────┼────────────────┼────────────────┼────────────────
283       Netherlands (NE) │ F 1.234,56     │ F −1.234,56    │ NLG 1.234,56
284       ─────────────────┼────────────────┼────────────────┼────────────────
285       Norway (NO)      │ kr1.234,56     │ kr1.234,56−    │ NOK 1.234,56
286       ─────────────────┼────────────────┼────────────────┼────────────────
287       Switzerland (SW) │ SFrs.1,234.56  │ SFrs.1,234.56C │ CHF 1,234.56
288
289
290
291       For  these  four countries, the respective values for the monetary mem‐
292       bers of the structure returned by localeconv() are as follows:
293
294
295
296
297
298                                                                 IT       NE       NO       SW
299       int_curr_symbol                                           "ITL."   "NLG "   "NOK "   "CHF "
300       currency_symbol                                           "L."     "F"      "kr"     "SFrs."
301       mon_decimal_point                                         ""       ","      ","      "."
302       mon_thousands_sep                                         "."      "."      "."      ","
303       mon_grouping                                              "\3"     "\3"     "\3"     "\3"
304       positive_sign                                             ""       ""       ""       ""
305       negative_sign                                             "-"      "-"      "-"      "C"
306       int_frac_digits                                           0        2        2        2
307       frac_digits                                               0        2        2        2
308       p_cs_precedes                                             1        1        1        1
309       p_sep_by_space                                            0        1        0        0
310       n_cs_precedes                                             1        1        1        1
311       n_sep_by_space                                            0        1        0        0
312       p_sign_posn                                               1        1        1        1
313       n_sign_posn                                               1        4        2        2
314       int_p_cs_precedes                                         1        1        1        1
315       int_n_cs_precedes                                         1        1        1        1
316       int_p_sep_by_space                                        0        0        0        0
317       int_n_sep_by_space                                        0        0        0        0
318       int_p_sign_posn                                           1        1        1        1
319       int_n_sign_posn                                           1        4        4        2
320
321

ATTRIBUTES

323       See attributes(5) for descriptions of the following attributes:
324
325
326
327
328       ┌─────────────────────────────┬─────────────────────────────┐
329       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
330       ├─────────────────────────────┼─────────────────────────────┤
331       │CSI                          │Enabled                      │
332       ├─────────────────────────────┼─────────────────────────────┤
333       │Interface Stability          │Standard                     │
334       ├─────────────────────────────┼─────────────────────────────┤
335       │MT-Level                     │MT-Safe with exceptions      │
336       └─────────────────────────────┴─────────────────────────────┘
337
338
339       The localeconv() function can be used safely in multithreaded  applica‐
340       tions,  as  long  as  setlocale(3C)  is  not being called to change the
341       locale.
342

SEE ALSO

344       setlocale(3C), attributes(5), environ(5), standards(5)
345
346
347
348SunOS 5.11                        12 Dec 2003                   localeconv(3C)
Impressum