[BACK]Return to setlocale.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / locale

Annotation of src/lib/libc/locale/setlocale.3, Revision 1.3

1.3     ! kleink      1: .\"    $NetBSD: setlocale.3,v 1.2 1997/07/12 19:13:12 kleink Exp $
1.2       kleink      2: .\"
1.1       perry       3: .\" Copyright (c) 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to Berkeley by
                      7: .\" Donn Seeley at BSDI.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\" 3. All advertising materials mentioning features or use of this software
                     18: .\"    must display the following acknowledgement:
                     19: .\"    This product includes software developed by the University of
                     20: .\"    California, Berkeley and its contributors.
                     21: .\" 4. Neither the name of the University nor the names of its contributors
                     22: .\"    may be used to endorse or promote products derived from this software
                     23: .\"    without specific prior written permission.
                     24: .\"
                     25: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     26: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     27: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     28: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     29: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     30: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     31: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     32: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     33: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     34: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     35: .\" SUCH DAMAGE.
                     36: .\"
                     37: .\"    @(#)setlocale.3 8.1 (Berkeley) 6/9/93
                     38: .\"
                     39: .Dd June 9, 1993
                     40: .Dt SETLOCALE 3
1.3     ! kleink     41: .Os NetBSD
1.1       perry      42: .Sh NAME
                     43: .Nm setlocale ,
                     44: .Nm localeconv
                     45: .Nd natural language formatting for C
                     46: .Sh SYNOPSIS
                     47: .Fd #include <locale.h>
                     48: .Ft char *
                     49: .Fn setlocale "int category" "const char *locale"
                     50: .Ft struct lconv *
                     51: .Fn localeconv "void"
                     52: .Sh DESCRIPTION
                     53: The
                     54: .Fn setlocale
                     55: function sets the C library's notion
                     56: of natural language formatting style
                     57: for particular sets of routines.
                     58: Each such style is called a
                     59: .Sq locale
                     60: and is invoked using an appropriate name passed as a C string.
                     61: The
                     62: .Fn localeconv
                     63: routine returns the current locale's parameters
                     64: for formatting numbers.
                     65: .Pp
                     66: The
                     67: .Fn setlocale
                     68: function recognizes several categories of routines.
                     69: These are the categories and the sets of routines they select:
                     70: .Pp
                     71: .Bl -tag -width LC_MONETARY
                     72: .It Dv LC_ALL
                     73: Set the entire locale generically.
                     74: .It Dv LC_COLLATE
                     75: Set a locale for string collation routines.
                     76: This controls alphabetic ordering in
                     77: .Fn strcoll
                     78: and
                     79: .Fn strxfrm .
                     80: .It Dv LC_CTYPE
                     81: Set a locale for the
1.2       kleink     82: .Xr ctype 3
1.1       perry      83: functions.
                     84: This controls recognition of upper and lower case,
                     85: alphabetic or non-alphabetic characters,
                     86: and so on.  The real work is done by the
                     87: .Fn setrunelocale
                     88: function.
                     89: .It Dv LC_MONETARY
                     90: Set a locale for formatting monetary values;
                     91: this affects the
                     92: .Fn localeconv
                     93: function.
                     94: .It Dv LC_NUMERIC
                     95: Set a locale for formatting numbers.
                     96: This controls the formatting of decimal points
                     97: in input and output of floating point numbers
                     98: in functions such as
                     99: .Fn printf
                    100: and
                    101: .Fn scanf ,
                    102: as well as values returned by
                    103: .Fn localeconv .
                    104: .It Dv LC_TIME
                    105: Set a locale for formatting dates and times using the
                    106: .Fn strftime
                    107: function.
                    108: .El
                    109: .Pp
                    110: Only three locales are defined by default,
                    111: the empty string
                    112: .Li "\&""\|""
                    113: which denotes the native environment, and the
                    114: .Li "\&""C""
                    115: and
                    116: .LI "\&""POSIX""
                    117: locales, which denote the C language environment.
                    118: A
                    119: .Fa locale
                    120: argument of
                    121: .Dv NULL
                    122: causes
                    123: .Fn setlocale
                    124: to return the current locale.
                    125: By default, C programs start in the
                    126: .Li "\&""C""
                    127: locale.
                    128: The only function in the library that sets the locale is
                    129: .Fn setlocale ;
                    130: the locale is never changed as a side effect of some other routine.
                    131: .Pp
                    132: The
                    133: .Fn localeconv
                    134: function returns a pointer to a structure
                    135: which provides parameters for formatting numbers,
                    136: especially currency values:
                    137: .Bd -literal -offset indent
                    138: struct lconv {
                    139:        char    *decimal_point;
                    140:        char    *thousands_sep;
                    141:        char    *grouping;
                    142:        char    *int_curr_symbol;
                    143:        char    *currency_symbol;
                    144:        char    *mon_decimal_point;
                    145:        char    *mon_thousands_sep;
                    146:        char    *mon_grouping;
                    147:        char    *positive_sign;
                    148:        char    *negative_sign;
                    149:        char    int_frac_digits;
                    150:        char    frac_digits;
                    151:        char    p_cs_precedes;
                    152:        char    p_sep_by_space;
                    153:        char    n_cs_precedes;
                    154:        char    n_sep_by_space;
                    155:        char    p_sign_posn;
                    156:        char    n_sign_posn;
                    157: };
                    158: .Ed
                    159: .Pp
                    160: The individual fields have the following meanings:
                    161: .Pp
                    162: .Bl -tag -width mon_decimal_point
                    163: .It Fa decimal_point
                    164: The decimal point character, except for currency values.
                    165: .It Fa thousands_sep
                    166: The separator between groups of digits
                    167: before the decimal point, except for currency values.
                    168: .It Fa grouping
                    169: The sizes of the groups of digits, except for currency values.
                    170: This is a pointer to a vector of integers, each of size
                    171: .Va char ,
                    172: representing group size from low order digit groups
                    173: to high order (right to left).
                    174: The list may be terminated with 0 or
                    175: .Dv CHAR_MAX .
                    176: If the list is terminated with 0,
                    177: the last group size before the 0 is repeated to account for all the digits.
                    178: If the list is terminated with
                    179: .Dv CHAR_MAX ,
                    180: no more grouping is performed.
                    181: .It Fa int_curr_symbol
                    182: The standardized international currency symbol.
                    183: .It Fa currency_symbol
                    184: The local currency symbol.
                    185: .It Fa mon_decimal_point
                    186: The decimal point character for currency values.
                    187: .It Fa mon_thousands_sep
                    188: The separator for digit groups in currency values.
                    189: .It Fa mon_grouping
                    190: Like
                    191: .Fa grouping
                    192: but for currency values.
                    193: .It Fa positive_sign
                    194: The character used to denote nonnegative currency values,
                    195: usually the empty string.
                    196: .It Fa negative_sign
                    197: The character used to denote negative currency values,
                    198: usually a minus sign.
                    199: .It Fa int_frac_digits
                    200: The number of digits after the decimal point
                    201: in an international-style currency value.
                    202: .It Fa frac_digits
                    203: The number of digits after the decimal point
                    204: in the local style for currency values.
                    205: .It Fa p_cs_precedes
                    206: 1 if the currency symbol precedes the currency value
                    207: for nonnegative values, 0 if it follows.
                    208: .It Fa p_sep_by_space
                    209: 1 if a space is inserted between the currency symbol
                    210: and the currency value for nonnegative values, 0 otherwise.
                    211: .It Fa n_cs_precedes
                    212: Like
                    213: .Fa p_cs_precedes
                    214: but for negative values.
                    215: .It Fa n_sep_by_space
                    216: Like
                    217: .Fa p_sep_by_space
                    218: but for negative values.
                    219: .It Fa p_sign_posn
                    220: The location of the
                    221: .Fa positive_sign
                    222: with respect to a nonnegative quantity and the
                    223: .Fa currency_symbol ,
                    224: coded as follows:
                    225: .Bl -tag -width 3n -compact
                    226: .It Li 0
                    227: Parentheses around the entire string.
                    228: .It Li 1
                    229: Before the string.
                    230: .It Li 2
                    231: After the string.
                    232: .It Li 3
                    233: Just before
                    234: .Fa currency_symbol .
                    235: .It Li 4
                    236: Just after
                    237: .Fa currency_symbol .
                    238: .El
                    239: .It Fa n_sign_posn
                    240: Like
                    241: .Fa p_sign_posn
                    242: but for negative currency values.
                    243: .El
                    244: .Pp
                    245: Unless mentioned above,
                    246: an empty string as a value for a field
                    247: indicates a zero length result or
                    248: a value that is not in the current locale.
                    249: A
                    250: .Dv CHAR_MAX
                    251: result similarly denotes an unavailable value.
                    252: .Sh "RETURN VALUES
                    253: The
                    254: .Fn setlocale
                    255: function returns
                    256: .Dv NULL
                    257: and fails to change the locale
                    258: if the given combination of
                    259: .Fa category
                    260: and
                    261: .Fa locale
                    262: makes no sense.
                    263: The
                    264: .Fn localeconv
                    265: function returns a pointer to a static object
                    266: which may be altered by later calls to
                    267: .Fn setlocale
                    268: or
                    269: .Fn localeconv .
1.2       kleink    270: .\" .Sh FILES                                                  XXX
                    271: .\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
                    272: .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP            XXX
                    273: .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP       XXX
                    274: .\" locale file for the locale \fIlocale\fP                    XXX
                    275: .\" and the category \fIcategory\fP.                           XXX
                    276: .\" .El
                    277: .\" .Sh "SEE ALSO
                    278: .\" .Xr strcoll 3 ,                                            XXX
                    279: .\" .Xr strxfrm 3                                              XXX
1.1       perry     280: .Sh STANDARDS
                    281: The
                    282: .Fn setlocale
                    283: and
                    284: .Fn localeconv
                    285: functions conform to
                    286: .St -ansiC .
                    287: .Sh HISTORY
                    288: The
                    289: .Fn setlocale
                    290: and
                    291: .Fn localeconv
1.2       kleink    292: functions first appeared in
                    293: .Bx 4.4 .
1.1       perry     294: .Sh BUGS
                    295: The current implementation supports only the
                    296: .Li "\&""C""
                    297: and
                    298: .Li "\&""POSIX""
                    299: locales for all but the LC_CTYPE locale.
                    300: .Pp
                    301: In spite of the gnarly currency support in
                    302: .Fn localeconv ,
                    303: the standards don't include any functions
                    304: for generalized currency formatting.
                    305: .Pp
                    306: .Dv LC_COLLATE
                    307: does not make sense for many languages.
                    308: Use of
                    309: .Dv LC_MONETARY
                    310: could lead to misleading results until we have a real time currency
                    311: conversion function.
                    312: .Dv LC_NUMERIC
                    313: and
                    314: .Dv LC_TIME
                    315: are personal choices and should not be wrapped up with the other categories.

CVSweb <webmaster@jp.NetBSD.org>