[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.15

1.15    ! gmcgarry    1: .\"    $NetBSD: setlocale.3,v 1.14 2002/10/01 17:02:57 wiz 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.6       garbled    41: .Os
1.1       perry      42: .Sh NAME
                     43: .Nm setlocale ,
                     44: .Nm localeconv
                     45: .Nd natural language formatting for C
1.4       perry      46: .Sh LIBRARY
                     47: .Lb libc
1.1       perry      48: .Sh SYNOPSIS
1.12      ross       49: .Fd #include \*[Lt]locale.h\*[Gt]
1.1       perry      50: .Ft char *
                     51: .Fn setlocale "int category" "const char *locale"
                     52: .Ft struct lconv *
                     53: .Fn localeconv "void"
                     54: .Sh DESCRIPTION
                     55: The
                     56: .Fn setlocale
                     57: function sets the C library's notion
                     58: of natural language formatting style
                     59: for particular sets of routines.
                     60: Each such style is called a
                     61: .Sq locale
                     62: and is invoked using an appropriate name passed as a C string.
                     63: The
                     64: .Fn localeconv
                     65: routine returns the current locale's parameters
                     66: for formatting numbers.
                     67: .Pp
                     68: The
                     69: .Fn setlocale
                     70: function recognizes several categories of routines.
                     71: These are the categories and the sets of routines they select:
                     72: .Pp
                     73: .Bl -tag -width LC_MONETARY
                     74: .It Dv LC_ALL
                     75: Set the entire locale generically.
                     76: .It Dv LC_COLLATE
                     77: Set a locale for string collation routines.
                     78: This controls alphabetic ordering in
                     79: .Fn strcoll
                     80: and
                     81: .Fn strxfrm .
                     82: .It Dv LC_CTYPE
                     83: Set a locale for the
1.2       kleink     84: .Xr ctype 3
1.1       perry      85: functions.
                     86: This controls recognition of upper and lower case,
                     87: alphabetic or non-alphabetic characters,
1.14      wiz        88: and so on.
                     89: The real work is done by the
1.1       perry      90: .Fn setrunelocale
                     91: function.
                     92: .It Dv LC_MONETARY
                     93: Set a locale for formatting monetary values;
                     94: this affects the
                     95: .Fn localeconv
                     96: function.
                     97: .It Dv LC_NUMERIC
                     98: Set a locale for formatting numbers.
                     99: This controls the formatting of decimal points
                    100: in input and output of floating point numbers
                    101: in functions such as
                    102: .Fn printf
                    103: and
                    104: .Fn scanf ,
                    105: as well as values returned by
                    106: .Fn localeconv .
                    107: .It Dv LC_TIME
                    108: Set a locale for formatting dates and times using the
                    109: .Fn strftime
                    110: function.
                    111: .El
                    112: .Pp
                    113: Only three locales are defined by default,
                    114: the empty string
                    115: .Li "\&""\|""
                    116: which denotes the native environment, and the
                    117: .Li "\&""C""
                    118: and
1.5       fair      119: .Li "\&""POSIX""
1.1       perry     120: locales, which denote the C language environment.
                    121: A
                    122: .Fa locale
                    123: argument of
                    124: .Dv NULL
                    125: causes
                    126: .Fn setlocale
                    127: to return the current locale.
                    128: By default, C programs start in the
                    129: .Li "\&""C""
                    130: locale.
1.15    ! gmcgarry  131: The format of the locale string is described in
        !           132: .Xr nls 7 .
        !           133: .Pp
1.1       perry     134: The only function in the library that sets the locale is
                    135: .Fn setlocale ;
                    136: the locale is never changed as a side effect of some other routine.
                    137: .Pp
1.15    ! gmcgarry  138: .Pp
        !           139: Changing the setting of LC_MESSAGES has no effect on catalogs that
        !           140: have already been opened by
        !           141: .Xr catopen 3 .
        !           142: .Pp
1.1       perry     143: The
                    144: .Fn localeconv
                    145: function returns a pointer to a structure
                    146: which provides parameters for formatting numbers,
                    147: especially currency values:
                    148: .Bd -literal -offset indent
                    149: struct lconv {
                    150:        char    *decimal_point;
                    151:        char    *thousands_sep;
                    152:        char    *grouping;
                    153:        char    *int_curr_symbol;
                    154:        char    *currency_symbol;
                    155:        char    *mon_decimal_point;
                    156:        char    *mon_thousands_sep;
                    157:        char    *mon_grouping;
                    158:        char    *positive_sign;
                    159:        char    *negative_sign;
                    160:        char    int_frac_digits;
                    161:        char    frac_digits;
                    162:        char    p_cs_precedes;
                    163:        char    p_sep_by_space;
                    164:        char    n_cs_precedes;
                    165:        char    n_sep_by_space;
                    166:        char    p_sign_posn;
                    167:        char    n_sign_posn;
1.8       kleink    168:        char    int_p_cs_precedes;
                    169:        char    int_n_cs_precedes;
                    170:        char    int_p_sep_by_space;
                    171:        char    int_n_sep_by_space;
                    172:        char    int_p_sign_posn;
                    173:        char    int_n_sign_posn;
1.1       perry     174: };
                    175: .Ed
                    176: .Pp
                    177: The individual fields have the following meanings:
                    178: .Pp
1.8       kleink    179: .Bl -tag -width int_p_sep_by_space
1.1       perry     180: .It Fa decimal_point
1.8       kleink    181: The decimal point character, except for monetary values.
1.1       perry     182: .It Fa thousands_sep
                    183: The separator between groups of digits
1.8       kleink    184: before the decimal point, except for monetary values.
1.1       perry     185: .It Fa grouping
1.8       kleink    186: The sizes of the groups of digits, except for monetary values.
1.1       perry     187: This is a pointer to a vector of integers, each of size
                    188: .Va char ,
                    189: representing group size from low order digit groups
                    190: to high order (right to left).
                    191: The list may be terminated with 0 or
                    192: .Dv CHAR_MAX .
                    193: If the list is terminated with 0,
                    194: the last group size before the 0 is repeated to account for all the digits.
                    195: If the list is terminated with
                    196: .Dv CHAR_MAX ,
                    197: no more grouping is performed.
                    198: .It Fa int_curr_symbol
1.8       kleink    199: The standardized (ISO 4217:1995) international currency symbol.
1.1       perry     200: .It Fa currency_symbol
                    201: The local currency symbol.
                    202: .It Fa mon_decimal_point
1.8       kleink    203: The decimal point character for monetary values.
1.1       perry     204: .It Fa mon_thousands_sep
1.8       kleink    205: The separator for digit groups in monetary values.
1.1       perry     206: .It Fa mon_grouping
                    207: Like
                    208: .Fa grouping
1.8       kleink    209: but for monetary values.
1.1       perry     210: .It Fa positive_sign
1.8       kleink    211: The character used to denote nonnegative monetary values,
1.1       perry     212: usually the empty string.
                    213: .It Fa negative_sign
1.8       kleink    214: The character used to denote negative monetary values,
1.1       perry     215: usually a minus sign.
                    216: .It Fa int_frac_digits
                    217: The number of digits after the decimal point
1.8       kleink    218: in an internationally formatted monetary value.
1.1       perry     219: .It Fa frac_digits
                    220: The number of digits after the decimal point
1.8       kleink    221: in an locally formatted monetary value.
1.1       perry     222: .It Fa p_cs_precedes
1.8       kleink    223: 1 if the currency symbol precedes the monetary value
1.1       perry     224: for nonnegative values, 0 if it follows.
                    225: .It Fa p_sep_by_space
                    226: 1 if a space is inserted between the currency symbol
1.8       kleink    227: and the monetary value for nonnegative values, 0 otherwise.
1.1       perry     228: .It Fa n_cs_precedes
                    229: Like
                    230: .Fa p_cs_precedes
                    231: but for negative values.
                    232: .It Fa n_sep_by_space
                    233: Like
                    234: .Fa p_sep_by_space
                    235: but for negative values.
                    236: .It Fa p_sign_posn
                    237: The location of the
                    238: .Fa positive_sign
                    239: with respect to a nonnegative quantity and the
1.8       kleink    240: .Fa currency_symbol .
                    241: .It Fa n_sign_posn
                    242: Like
                    243: .Fa p_sign_posn
                    244: but for negative currency values.
                    245: .It Fa int_p_cs_precedes
                    246: 1 if the currency symbol precedes the internationally
                    247: formatted monetary value for nonnegative values, 0 if it follows.
                    248: .It Fa int_n_cs_precedes
                    249: Like
                    250: .Fa int_p_cs_precedes
                    251: but for negative values.
                    252: .It Fa int_p_sep_by_space
                    253: 1 if a space is inserted between the currency symbol
                    254: and the internationally formatted monetary value for
                    255: nonnegative values, 0 otherwise.
                    256: .It Fa int_n_sep_by_space
                    257: Like
                    258: .Fa int_p_sep_by_space
                    259: but for negative values.
                    260: .It Fa int_p_sign_posn
                    261: The location of the
                    262: .Fa positive_sign
                    263: with respect to a nonnegative quantity and the
1.1       perry     264: .Fa currency_symbol ,
1.8       kleink    265: for internationally formatted nonnegative monetary values.
                    266: .It Fa int_n_sign_posn
                    267: Like
                    268: .Fa int_p_sign_posn
                    269: but for negative values.
                    270: .El
                    271: .Pp
                    272: The positional parameters in
                    273: .Fa p_sign_posn ,
                    274: .Fa n_sign_posn ,
                    275: .Fa int_p_sign_posn
                    276: and
                    277: .Fa int_n_sign_posn
                    278: are encoded as follows:
1.1       perry     279: .Bl -tag -width 3n -compact
                    280: .It Li 0
                    281: Parentheses around the entire string.
                    282: .It Li 1
                    283: Before the string.
                    284: .It Li 2
                    285: After the string.
                    286: .It Li 3
                    287: Just before
                    288: .Fa currency_symbol .
                    289: .It Li 4
                    290: Just after
                    291: .Fa currency_symbol .
                    292: .El
                    293: .Pp
                    294: Unless mentioned above,
                    295: an empty string as a value for a field
                    296: indicates a zero length result or
                    297: a value that is not in the current locale.
                    298: A
                    299: .Dv CHAR_MAX
                    300: result similarly denotes an unavailable value.
1.11      uwe       301: .Sh RETURN VALUES
1.1       perry     302: The
                    303: .Fn setlocale
                    304: function returns
                    305: .Dv NULL
                    306: and fails to change the locale
                    307: if the given combination of
                    308: .Fa category
                    309: and
                    310: .Fa locale
                    311: makes no sense.
                    312: The
                    313: .Fn localeconv
                    314: function returns a pointer to a static object
                    315: which may be altered by later calls to
                    316: .Fn setlocale
                    317: or
                    318: .Fn localeconv .
1.15    ! gmcgarry  319: .Sh EXAMPLES
        !           320: The following code illustrates how a program can initialize the
        !           321: international environment for one language, while selectively
        !           322: modifying the program's locale such that regular expressions and
        !           323: string operations can be applied to text recorded in a different
        !           324: language:
        !           325: .Bd -literal
        !           326:        setlocale(LC_ALL, "de");
        !           327:        setlocale(LC_COLLATE, "fr");
        !           328: .Ed
        !           329: .Pp
        !           330: When a process is started, its current locale is set to the C or POSIX
        !           331: locale.  An internationalized program that depends on locale data not
        !           332: defined in the C or POSIX locale must invoke the setlocale subroutine
        !           333: in the following manner before using any of the locale-specific
        !           334: information:
        !           335: .Bd -literal
        !           336:        setlocale(LC_ALL, "");
        !           337: .Ed
1.2       kleink    338: .\" .Sh FILES                                                  XXX
                    339: .\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
                    340: .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP            XXX
                    341: .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP       XXX
                    342: .\" locale file for the locale \fIlocale\fP                    XXX
                    343: .\" and the category \fIcategory\fP.                           XXX
                    344: .\" .El
1.7       kleink    345: .Sh SEE ALSO
1.15    ! gmcgarry  346: .Xr catopen 3 ,
        !           347: .Xr nl_langinfo 3 ,
        !           348: .Xr nls 7
1.2       kleink    349: .\" .Xr strcoll 3 ,                                            XXX
                    350: .\" .Xr strxfrm 3                                              XXX
1.1       perry     351: .Sh STANDARDS
                    352: The
                    353: .Fn setlocale
                    354: and
                    355: .Fn localeconv
                    356: functions conform to
1.9       jdolecek  357: .St -ansiC
                    358: and
1.10      kleink    359: .St -isoC90 .
1.8       kleink    360: .Pp
                    361: The
                    362: .Fa int_p_cs_precedes ,
                    363: .Fa int_n_cs_precedes ,
                    364: .Fa int_p_sep_by_space ,
                    365: .Fa int_n_sep_by_space ,
                    366: .Fa int_p_sign_posn
                    367: and
                    368: .Fa int_n_sign_posn
                    369: members of
                    370: .Ft struct lconv
                    371: were introduced in
                    372: .St -isoC99 .
1.1       perry     373: .Sh HISTORY
                    374: The
                    375: .Fn setlocale
                    376: and
                    377: .Fn localeconv
1.2       kleink    378: functions first appeared in
                    379: .Bx 4.4 .
1.1       perry     380: .Sh BUGS
                    381: The current implementation supports only the
                    382: .Li "\&""C""
                    383: and
                    384: .Li "\&""POSIX""
                    385: locales for all but the LC_CTYPE locale.
                    386: .Pp
                    387: In spite of the gnarly currency support in
                    388: .Fn localeconv ,
                    389: the standards don't include any functions
                    390: for generalized currency formatting.
                    391: .Pp
                    392: .Dv LC_COLLATE
                    393: does not make sense for many languages.
                    394: Use of
                    395: .Dv LC_MONETARY
                    396: could lead to misleading results until we have a real time currency
                    397: conversion function.
                    398: .Dv LC_NUMERIC
                    399: and
                    400: .Dv LC_TIME
                    401: are personal choices and should not be wrapped up with the other categories.
1.13      yamt      402: .Pp
                    403: Multibyte locales aren't supported for static binaries.

CVSweb <webmaster@jp.NetBSD.org>