| blob | 5879be5dc3f68ad174031fa6e63496627bb7b25a |
1 '\" te
2 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .TH LOCALECONV 3C "Dec 12, 2003"
13 .SH NAME
14 localeconv \- get numeric formatting information
15 .SH SYNOPSIS
16 .LP
17 .nf
18 #include <locale.h>
20 \fBstruct lconv *\fR\fBlocaleconv\fR(\fBvoid\fR);
21 .fi
23 .SH DESCRIPTION
24 .sp
25 .LP
26 The \fBlocaleconv()\fR function sets the components of an object with type
27 \fBstruct lconv\fR (defined in \fB<locale.h>\fR) with the values appropriate
28 for the formatting of numeric quantities (monetary and otherwise) according to
29 the rules of the current locale (see \fBsetlocale\fR(3C)). The definition of
30 \fBstruct lconv\fR is given below (the values for the fields in the "C" locale
31 are given in comments).
32 .sp
33 .in +2
34 .nf
35 char *decimal_point; /* "." */
36 char *thousands_sep; /* "" (zero length string) */
37 char *grouping; /* "" */
38 char *int_curr_symbol; /* "" */
39 char *currency_symbol; /* "" */
40 char *mon_decimal_point; /* "" */
41 char *mon_thousands_sep; /* "" */
42 char *mon_grouping; /* "" */
43 char *positive_sign; /* "" */
44 char *negative_sign; /* "" */
45 char int_frac_digits; /* CHAR_MAX */
46 char frac_digits; /* CHAR_MAX */
47 char p_cs_precedes; /* CHAR_MAX */
48 char p_sep_by_space; /* CHAR_MAX */
49 char n_cs_precedes; /* CHAR_MAX */
50 char n_sep_by_space; /* CHAR_MAX */
51 char p_sign_posn; /* CHAR_MAX*/
52 char n_sign_posn; /* CHAR_MAX */
53 .fi
54 .in -2
56 .sp
57 .LP
58 The following members are also available to SUSv3-conforming applications. See
59 \fBstandards\fR(5)
60 .sp
61 .in +2
62 .nf
63 char int_p_cs_precedes; /* CHAR_MAX */
64 char int_p_sep_by_space; /* CHAR_MAX */
65 char int_n_cs_precedes; /* CHAR_MAX */
66 char int_n_sep_by_space; /* CHAR_MAX */
67 char int_p_sign_posn; /* CHAR_MAX */
68 char int_n_sign_posn; /* CHAR_MAX */
69 .fi
70 .in -2
72 .sp
73 .LP
74 The members of the structure with type \fBchar *\fR are strings, any of which
75 (except \fBdecimal_point\fR) can point to a null string (""), to indicate that
76 the value is not available in the current locale or is of zero length. The
77 members with type \fBchar\fR are non-negative numbers, any of which can be
78 \fBCHAR_MAX\fR (defined in the \fB<limits.h>\fR header) to indicate that the
79 value is not available in the current locale. The members are the following:
80 .sp
81 .ne 2
82 .na
83 \fB\fBchar *decimal_point\fR\fR
84 .ad
85 .RS 27n
86 The decimal-point character used to format non-monetary quantities.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fBchar *thousands_sep\fR\fR
93 .ad
94 .RS 27n
95 The character used to separate groups of digits to the left of the
96 decimal-point character in formatted non-monetary quantities.
97 .RE
99 .sp
100 .ne 2
101 .na
102 \fB\fBchar *grouping\fR\fR
103 .ad
104 .RS 27n
105 A string whose elements taken as one-byte integer values indicate the size of
106 each group of digits in formatted non-monetary quantities.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fBchar *int_curr_symbol\fR\fR
113 .ad
114 .RS 27n
115 The international currency symbol applicable to the current locale. The first
116 three characters contain the alphabetic international currency symbol in
117 accordance with those specified in the ISO 4217: 1995 standard. The fourth
118 character (immediately preceding the null byte) is the character used to
119 separate the international currency symbol from the monetary quantity.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fBchar *currency_symbol\fR\fR
126 .ad
127 .RS 27n
128 The local currency symbol applicable to the current locale.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fBchar *mon_decimal_point\fR\fR
135 .ad
136 .RS 27n
137 The decimal point used to format monetary quantities.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fBchar *mon_thousands_sep\fR\fR
144 .ad
145 .RS 27n
146 The separator for groups of digits to the left of the decimal point in
147 formatted monetary quantities.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fBchar *mon_grouping\fR\fR
154 .ad
155 .RS 27n
156 A string whose elements taken as one-byte integer values indicate the size of
157 each group of digits in formatted monetary quantities.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fBchar *positive_sign\fR\fR
164 .ad
165 .RS 27n
166 The string used to indicate a non-negative-valued formatted monetary quantity.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fBchar *negative_sign\fR\fR
173 .ad
174 .RS 27n
175 The string used to indicate a negative-valued formatted monetary quantity.
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fBchar int_frac_digits\fR\fR
182 .ad
183 .RS 27n
184 The number of fractional digits (those to the right of the decimal point) to be
185 displayed in an internationally formatted monetary quantity.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fBchar frac_digits\fR\fR
192 .ad
193 .RS 27n
194 The number of fractional digits (those to the right of the decimal point) to be
195 displayed in a formatted monetary quantity.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fBchar p_cs_precedes\fR\fR
202 .ad
203 .RS 27n
204 Set to 1 or 0 if the \fBcurrency_symbol\fR respectively precedes or succeeds
205 the value for a non-negative formatted monetary quantity.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fBchar p_sep_by_space\fR\fR
212 .ad
213 .RS 27n
214 Set to 0 if no space separates the \fBcurrency_symbol\fR or
215 \fBint_curr_symbol\fR from the value for a non-negative formatted monetary
216 quantity. Set to 1 if a space separates the symbol from the value; and set to 2
217 if a space separates the symbol and the sign string, if adjacent.
218 .RE
220 .sp
221 .ne 2
222 .na
223 \fB\fBchar n_cs_precedes\fR\fR
224 .ad
225 .RS 27n
226 Set to 1 or 0 if the \fBcurrency_symbol\fR respectively precedes or succeeds
227 the value for a negative formatted monetary quantity.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBchar n_sep_by_space\fR\fR
234 .ad
235 .RS 27n
236 Set to 0 if no space separates the \fBcurrency_symbol\fR or
237 \fBint_curr_symbol\fR from the value for a negative formatted monetary
238 quantity. Set to 1 if a space separates the symbol from the value; and set to 2
239 if a space separates the symbol and the sign string, if adjacent.
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fB\fBchar p_sign_posn\fR\fR
246 .ad
247 .RS 27n
248 Set to a value indicating the positioning of the \fBpositive_sign\fR for a
249 non-negative formatted monetary quantity.
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB\fBchar n_sign_posn\fR\fR
256 .ad
257 .RS 27n
258 Set to a value indicating the positioning of the \fBnegative_sign\fR for a
259 negative formatted monetary quantity.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBchar int_p_cs_precedes\fR\fR
266 .ad
267 .RS 27n
268 Set to 1 or 0 if the \fBint_curr_symbol\fR respectively precedes or succeeds
269 the value for a non-negative internationally formatted monetary quantity.
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fBchar int_n_cs_precedes\fR\fR
276 .ad
277 .RS 27n
278 Set to 1 or 0 if the \fBint_curr_symbol\fR respectively precedes or succeeds
279 the value for a negative internationally formatted monetary quantity.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBchar int_p_sep_by_space\fR\fR
286 .ad
287 .RS 27n
288 Set to a value indicating the separation of the \fBint_curr_symbol\fR, the sign
289 string, and the value for a non-negative internationally formatted monetary
290 quantity.
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fB\fBchar int_n_sep_by_space\fR\fR
297 .ad
298 .RS 27n
299 Set to a value indicating the separation of the \fBint_curr_symbol\fR, the sign
300 string, and the value for a negative internationally formatted monetary
301 quantity.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBchar int_p_sign_posn\fR\fR
308 .ad
309 .RS 27n
310 Set to a value indicating the positioning of the \fBpositive_sign\fR for a
311 non-negative internationally formatted monetary quantity.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBchar int_n_sign_posn\fR\fR
318 .ad
319 .RS 27n
320 Set to a value indicating the positioning of the \fBnegative_sign\fR for a
321 negative internationally formatted monetary quantity.
322 .RE
324 .sp
325 .LP
326 The elements of \fBgrouping\fR and \fBmon_grouping\fR are interpreted according
327 to the following:
328 .sp
329 .ne 2
330 .na
331 \fB{\fBCHAR_MAX\fR}\fR
332 .ad
333 .RS 14n
334 No further grouping is to be performed.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB0\fR
341 .ad
342 .RS 14n
343 The previous element is to be repeatedly used for the remainder of the digits.
344 .RE
346 .sp
347 .ne 2
348 .na
349 \fB\fIother\fR\fR
350 .ad
351 .RS 14n
352 The integer value is the number of digits that comprise the current group. The
353 next element is examined to determine the size of the next group of digits
354 before the current group.
355 .RE
357 .sp
358 .LP
359 The values of \fBp_sep_by_space\fR, \fBn_sep_by_space\fR,
360 \fBint_p_sep_by_space\fR, and \fBint_n_sep_by_space\fR are interpreted
361 according to the following:
362 .sp
363 .ne 2
364 .na
365 \fB0\fR
366 .ad
367 .RS 5n
368 No space separates the currency symbol and value.
369 .RE
371 .sp
372 .ne 2
373 .na
374 \fB1\fR
375 .ad
376 .RS 5n
377 If the currency symbol and sign string are adjacent, a space separates them
378 from the value; otherwise, a space separates the currency symbol from the
379 value.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fB2\fR
386 .ad
387 .RS 5n
388 If the currency symbol and sign string are adjacent, a space separates them;
389 otherwise, a space separates the sign string from the value.
390 .RE
392 .sp
393 .LP
394 In an SUSv3-conforming application, for \fBint_p_sep_by_space\fR and
395 \fBint_n_sep_by_space\fR, the fourth character of \fBint_curr_symbol\fR is used
396 instead of a space.
397 .sp
398 .LP
399 The values of \fBp_sign_posn\fR, \fBn_sign_posn\fR, \fBint_p_sign_posn\fR, and
400 \fBint_n_sign_posn\fR are interpreted according to the following:
401 .sp
402 .ne 2
403 .na
404 \fB0\fR
405 .ad
406 .RS 5n
407 Parentheses surround the quantity and \fBcurrency_symbol\fR or
408 \fBint_curr_symbol\fR.
409 .RE
411 .sp
412 .ne 2
413 .na
414 \fB1\fR
415 .ad
416 .RS 5n
417 The sign string precedes the quantity and \fBcurrency_symbol\fR or
418 \fBint_curr_symbol\fR.
419 .RE
421 .sp
422 .ne 2
423 .na
424 \fB2\fR
425 .ad
426 .RS 5n
427 The sign string succeeds the quantity and \fBcurrency_symbol\fR or
428 \fBint_curr_symbol\fR.
429 .RE
431 .sp
432 .ne 2
433 .na
434 \fB3\fR
435 .ad
436 .RS 5n
437 The sign string immediately precedes the \fBcurrency_symbol\fR or
438 \fBint_curr_symbol\fR.
439 .RE
441 .sp
442 .ne 2
443 .na
444 \fB4\fR
445 .ad
446 .RS 5n
447 The sign string immediately succeeds the \fBcurrency_symbol\fR or
448 \fBint_curr_symbol\fR.
449 .RE
451 .SH RETURN VALUES
452 .sp
453 .LP
454 The \fBlocaleconv()\fR function returns a pointer to the filled-in object. The
455 structure pointed to by the return value may be overwritten by a subsequent
456 call to \fBlocaleconv()\fR.
457 .SH EXAMPLES
458 .LP
459 \fBExample 1 \fRRules used by four countries to format monetary quantities.
460 .sp
461 .LP
462 The following table illustrates the rules used by four countries to format
463 monetary quantities.
465 .sp
467 .sp
468 .TS
469 l | l | l | l
470 l | l | l | l .
471 \fBCountry\fR \fBPositive\fR \fBNegative\fR \fBInternational\fR
472 _
473 Italy (IT) L.1.234 \(miL.1.234 ITL.1.234
474 _
475 Netherlands (NE) F 1.234,56 F \(mi1.234,56 NLG 1.234,56
476 _
477 Norway (NO) kr1.234,56 kr1.234,56\(mi NOK 1.234,56
478 _
479 Switzerland (SW) SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56
480 .TE
482 .sp
483 .LP
484 For these four countries, the respective values for the monetary members of the
485 structure returned by \fBlocaleconv()\fR are as follows:
487 .sp
489 .sp
490 .TS
491 l l l l l
492 l l l l l .
493 \fBIT\fR \fBNE\fR \fBNO\fR \fBSW\fR
494 \fBint_curr_symbol\fR "ITL." "NLG " "NOK " "CHF "
495 \fBcurrency_symbol\fR "L." "F" "kr" "SFrs."
496 \fBmon_decimal_point\fR "" "," "," "."
497 \fBmon_thousands_sep\fR "." "." "." ","
498 \fBmon_grouping\fR "\e3" "\e3" "\e3" "\e3"
499 \fBpositive_sign\fR "" "" "" ""
500 \fBnegative_sign\fR "-" "-" "-" "C"
501 \fBint_frac_digits\fR 0 2 2 2
502 \fBfrac_digits\fR 0 2 2 2
503 \fBp_cs_precedes\fR 1 1 1 1
504 \fBp_sep_by_space\fR 0 1 0 0
505 \fBn_cs_precedes\fR 1 1 1 1
506 \fBn_sep_by_space\fR 0 1 0 0
507 \fBp_sign_posn\fR 1 1 1 1
508 \fBn_sign_posn\fR 1 4 2 2
509 \fBint_p_cs_precedes\fR 1 1 1 1
510 \fBint_n_cs_precedes\fR 1 1 1 1
511 \fBint_p_sep_by_space\fR 0 0 0 0
512 \fBint_n_sep_by_space\fR 0 0 0 0
513 \fBint_p_sign_posn\fR 1 1 1 1
514 \fBint_n_sign_posn\fR 1 4 4 2
515 .TE
517 .SH ATTRIBUTES
518 .sp
519 .LP
520 See \fBattributes\fR(5) for descriptions of the following attributes:
521 .sp
523 .sp
524 .TS
525 box;
526 c | c
527 l | l .
528 ATTRIBUTE TYPE ATTRIBUTE VALUE
529 _
530 CSI Enabled
531 _
532 Interface Stability Standard
533 _
534 MT-Level MT-Safe with exceptions
535 .TE
537 .sp
538 .LP
539 The \fBlocaleconv()\fR function can be used safely in multithreaded
540 applications, as long as \fBsetlocale\fR(3C) is not being called to change the
541 locale.
542 .SH SEE ALSO
543 .sp
544 .LP
545 \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)