original/man7/locale.7

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified Sat Jul 24 17:28:34 1993 by Rik Faith <faith@cs.unc.edu>
  24 .\" Modified Sun Jun 01 17:16:34 1997 by Jochen Hein
  25 .\"   <jochen.hein@delphi.central.de>
  26 .\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible <bruno@clisp.org>
  27 .\"
  28 .\" FIXME Document LOCPATH;
  29 .\" see http://sourceware.org/bugzilla/show_bug.cgi?id=174
  30 .TH LOCALE 7  2008-12-05 "Linux" "Linux Programmer's Manual"
  31 .SH NAME
  32 locale \- Description of multilanguage support
  33 .SH SYNOPSIS
  34 .nf
  35 .B #include <locale.h>
  36 .fi
  37 .SH DESCRIPTION
  38 A locale is a set of language and cultural rules.
  39 These cover aspects
  40 such as language for messages, different character sets, lexicographic
  41 conventions, etc.
  42 A program needs to be able to determine its locale
  43 and act accordingly to be portable to different cultures.
  44 .PP
  45 The header
  46 .I <locale.h>
  47 declares data types, functions and macros which are useful in this
  48 task.
  49 .PP
  50 The functions it declares are
  51 .BR setlocale (3)
  52 to set the current locale, and
  53 .BR localeconv (3)
  54 to get information about number formatting.
  55 .PP
  56 There are different categories for local information a program might
  57 need; they are declared as macros.
  58 Using them as the first argument
  59 to the
  60 .BR setlocale (3)
  61 function, it is possible to set one of these to the desired locale:
  62 .TP
  63 .B LC_COLLATE
  64 This is used to change the behavior of the functions
  65 .BR strcoll (3)
  66 and
  67 .BR strxfrm (3),
  68 which are used to compare strings in the local alphabet.
  69 For example,
  70 the German sharp s is sorted as "ss".
  71 .TP
  72 .B LC_CTYPE
  73 This changes the behavior of the character handling and
  74 classification functions, such as
  75 .BR isupper (3)
  76 and
  77 .BR toupper (3),
  78 and the multibyte character functions such as
  79 .BR mblen (3)
  80 or
  81 .BR wctomb (3).
  82 .TP
  83 .B LC_MONETARY
  84 changes the information returned by
  85 .BR localeconv (3)
  86 which describes the way numbers are usually printed, with details such
  87 as decimal point versus decimal comma.
  88 This information is internally
  89 used by the function
  90 .BR strfmon (3).
  91 .TP
  92 .B LC_MESSAGES
  93 changes the language messages are displayed in and what an affirmative or
  94 negative answer looks like.
  95 The GNU C-library contains the
  96 .BR gettext (3),
  97 .BR ngettext (3),
  98 and
  99 .BR rpmatch (3)
 100 functions to ease the use of these information.
 101 The GNU gettext family of
 102 functions also obey the environment variable
 103 .BR LANGUAGE
 104 (containing a colon-separated list of locales)
 105 if the category is set to a valid locale other than
 106 .BR """C""" .
 107 .TP
 108 .B LC_NUMERIC
 109 changes the information used by the
 110 .BR printf (3)
 111 and
 112 .BR scanf (3)
 113 family of functions, when they are advised to use the locale-settings.
 114 This information can also be read with the
 115 .BR localeconv (3)
 116 function.
 117 .TP
 118 .B LC_TIME
 119 changes the behavior of the
 120 .BR strftime (3)
 121 function to display the current time in a locally acceptable form; for
 122 example, most of Europe uses a 24-hour clock versus the
 123 12-hour clock used in the United States.
 124 .TP
 125 .B LC_ALL
 126 All of the above.
 127 .\" FIXME glibc 2.2.2 added new nonstandard locale categories:
 128 .\" LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_NAME,
 129 .\" LC_PAPER, LC_TELEPHONE.  These need to be documented.
 130 .PP
 131 If the second argument to
 132 .BR setlocale (3)
 133 is empty string,
 134 .BR """""" ,
 135 for the default locale, it is determined using the following steps:
 136 .IP 1.
 137 If there is a non-null environment variable
 138 .BR LC_ALL ,
 139 the value of
 140 .B LC_ALL
 141 is used.
 142 .IP 2.
 143 If an environment variable with the same name as one of the categories
 144 above exists and is non-null, its value is used for that category.
 145 .IP 3.
 146 If there is a non-null environment variable
 147 .BR LANG ,
 148 the value of
 149 .B LANG
 150 is used.
 151 .PP
 152 Values about local numeric formatting is made available in a
 153 .I struct lconv
 154 returned by the
 155 .BR localeconv (3)
 156 function, which has the following declaration:
 157 .in +2n
 158 .nf
 159
 160 struct lconv {
 161
 162     /* Numeric (nonmonetary) information */
 163
 164     char *decimal_point;     /* Radix character */
 165     char *thousands_sep;     /* Separator for digit groups to left
 166                                 of radix character */
 167     char *grouping; /* Each element is the number of digits in a
 168                        group; elements with higher indices are
 169                        further left.  An element with value CHAR_MAX
 170                        means that no further grouping is done.  An
 171                        element with value 0 means that the previous
 172                        element is used for all groups further left. */
 173
 174     /* Remaining fields are for monetary information */
 175
 176     char *int_curr_symbol;   /* First three chars are a currency symbol
 177                                 from ISO 4217.  Fourth char is the
 178                                 separator.  Fifth char is \(aq\\0\(aq. */
 179     char *currency_symbol;   /* Local currency symbol */
 180     char *mon_decimal_point; /* Radix character */
 181     char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */
 182     char *mon_grouping;      /* Like \fIgrouping\fP above */
 183     char *positive_sign;     /* Sign for positive values */
 184     char *negative_sign;     /* Sign for negative values */
 185     char  int_frac_digits;   /* International fractional digits */
 186     char  frac_digits;       /* Local fractional digits */
 187     char  p_cs_precedes;     /* 1 if currency_symbol precedes a
 188                                 positive value, 0 if succeeds */
 189     char  p_sep_by_space;    /* 1 if a space separates currency_symbol
 190                                 from a positive value */
 191     char  n_cs_precedes;     /* 1 if currency_symbol precedes a
 192                                 negative value, 0 if succeeds */
 193     char  n_sep_by_space;    /* 1 if a space separates currency_symbol
 194                                 from a negative value */
 195     /* Positive and negative sign positions:
 196        0 Parentheses surround the quantity and currency_symbol.
 197        1 The sign string precedes the quantity and currency_symbol.
 198        2 The sign string succeeds the quantity and currency_symbol.
 199        3 The sign string immediately precedes the currency_symbol.
 200        4 The sign string immediately succeeds the currency_symbol. */
 201     char  p_sign_posn;
 202     char  n_sign_posn;
 203 };
 204 .fi
 205 .in
 206 .SH "CONFORMING TO"
 207 POSIX.1-2001.
 208
 209 The GNU gettext functions are specified in LI18NUX2000.
 210 .SH "SEE ALSO"
 211 .BR locale (1),
 212 .BR localedef (1),
 213 .BR gettext (3),
 214 .BR localeconv (3),
 215 .BR ngettext (3),
 216 .BR nl_langinfo (3),
 217 .BR rpmatch (3),
 218 .BR setlocale (3),
 219 .BR strcoll (3),
 220 .BR strfmon (3),
 221 .BR strftime (3),
 222 .BR strxfrm (3)