1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Donn Seeley at BSDI. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 4. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" From @(#)setlocale.3 8.1 (Berkeley) 6/9/93 32.\" From FreeBSD: src/lib/libc/locale/setlocale.3,v 1.28 2003/11/15 02:26:04 tjr Exp 33.\" $FreeBSD$ 34.\" 35.Dd November 21, 2003 36.Dt LOCALECONV 3 37.Os 38.Sh NAME 39.Nm localeconv 40.Nd natural language formatting for C 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In locale.h 45.Ft struct lconv * 46.Fn localeconv "void" 47.In xlocale.h 48.Ft struct lconv * 49.Fn localeconv_l "locale_t locale" 50.Sh DESCRIPTION 51The 52.Fn localeconv 53function returns a pointer to a structure 54which provides parameters for formatting numbers, 55especially currency values: 56.Bd -literal -offset indent 57struct lconv { 58 char *decimal_point; 59 char *thousands_sep; 60 char *grouping; 61 char *int_curr_symbol; 62 char *currency_symbol; 63 char *mon_decimal_point; 64 char *mon_thousands_sep; 65 char *mon_grouping; 66 char *positive_sign; 67 char *negative_sign; 68 char int_frac_digits; 69 char frac_digits; 70 char p_cs_precedes; 71 char p_sep_by_space; 72 char n_cs_precedes; 73 char n_sep_by_space; 74 char p_sign_posn; 75 char n_sign_posn; 76 char int_p_cs_precedes; 77 char int_n_cs_precedes; 78 char int_p_sep_by_space; 79 char int_n_sep_by_space; 80 char int_p_sign_posn; 81 char int_n_sign_posn; 82}; 83.Ed 84.Pp 85The individual fields have the following meanings: 86.Bl -tag -width mon_decimal_point 87.It Va decimal_point 88The decimal point character, except for currency values, 89cannot be an empty string. 90.It Va thousands_sep 91The separator between groups of digits 92before the decimal point, except for currency values. 93.It Va grouping 94The sizes of the groups of digits, except for currency values. 95This is a pointer to a vector of integers, each of size 96.Vt char , 97representing group size from low order digit groups 98to high order (right to left). 99The list may be terminated with 0 or 100.Dv CHAR_MAX . 101If the list is terminated with 0, 102the last group size before the 0 is repeated to account for all the digits. 103If the list is terminated with 104.Dv CHAR_MAX , 105no more grouping is performed. 106.It Va int_curr_symbol 107The standardized international currency symbol. 108.It Va currency_symbol 109The local currency symbol. 110.It Va mon_decimal_point 111The decimal point character for currency values. 112.It Va mon_thousands_sep 113The separator for digit groups in currency values. 114.It Va mon_grouping 115Like 116.Va grouping 117but for currency values. 118.It Va positive_sign 119The character used to denote nonnegative currency values, 120usually the empty string. 121.It Va negative_sign 122The character used to denote negative currency values, 123usually a minus sign. 124.It Va int_frac_digits 125The number of digits after the decimal point 126in an international-style currency value. 127.It Va frac_digits 128The number of digits after the decimal point 129in the local style for currency values. 130.It Va p_cs_precedes 1311 if the currency symbol precedes the currency value 132for nonnegative values, 0 if it follows. 133.It Va p_sep_by_space 1341 if a space is inserted between the currency symbol 135and the currency value for nonnegative values, 0 otherwise. 136.It Va n_cs_precedes 137Like 138.Va p_cs_precedes 139but for negative values. 140.It Va n_sep_by_space 141Like 142.Va p_sep_by_space 143but for negative values. 144.It Va p_sign_posn 145The location of the 146.Va positive_sign 147with respect to a nonnegative quantity and the 148.Va currency_symbol , 149coded as follows: 150.Pp 151.Bl -tag -width 3n -compact 152.It Li 0 153Parentheses around the entire string. 154.It Li 1 155Before the string. 156.It Li 2 157After the string. 158.It Li 3 159Just before 160.Va currency_symbol . 161.It Li 4 162Just after 163.Va currency_symbol . 164.El 165.It Va n_sign_posn 166Like 167.Va p_sign_posn 168but for negative currency values. 169.It Va int_p_cs_precedes 170Same as 171.Va p_cs_precedes , 172but for internationally formatted monetary quantities. 173.It Va int_n_cs_precedes 174Same as 175.Va n_cs_precedes , 176but for internationally formatted monetary quantities. 177.It Va int_p_sep_by_space 178Same as 179.Va p_sep_by_space , 180but for internationally formatted monetary quantities. 181.It Va int_n_sep_by_space 182Same as 183.Va n_sep_by_space , 184but for internationally formatted monetary quantities. 185.It Va int_p_sign_posn 186Same as 187.Va p_sign_posn , 188but for internationally formatted monetary quantities. 189.It Va int_n_sign_posn 190Same as 191.Va n_sign_posn , 192but for internationally formatted monetary quantities. 193.El 194.Pp 195Unless mentioned above, 196an empty string as a value for a field 197indicates a zero length result or 198a value that is not in the current locale. 199A 200.Dv CHAR_MAX 201result similarly denotes an unavailable value. 202.Pp 203The 204.Fn localeconv_l 205function takes an explicit locale parameter. For more information, see 206.Xr xlocale 3 . 207.Sh RETURN VALUES 208The 209.Fn localeconv 210function returns a pointer to a static object 211which may be altered by later calls to 212.Xr setlocale 3 213or 214.Fn localeconv . 215The return value for 216.Fn localeconv_l 217is stored with the locale. 218It will remain valid until a subsequent call to 219.Xr freelocale 3 . 220If a thread-local locale is in effect then the return value from 221.Fn localeconv 222will remain valid until the locale is destroyed. 223.Sh ERRORS 224No errors are defined. 225.Sh SEE ALSO 226.Xr setlocale 3 , 227.Xr strfmon 3 228.Sh STANDARDS 229The 230.Fn localeconv 231function conforms to 232.St -isoC-99 . 233.Sh HISTORY 234The 235.Fn localeconv 236function first appeared in 237.Bx 4.4 . 238