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 .TH LOCALE 7  2008-12-05 "Linux" "Linux Programmer's Manual"
  29 .SH NAME
  30 locale \- Description of multilanguage support
  31 .SH SYNOPSIS
  32 .nf
  33 .B #include <locale.h>
  34 .fi
  35 .SH DESCRIPTION
  36 A locale is a set of language and cultural rules.
  37 These cover aspects
  38 such as language for messages, different character sets, lexicographic
  39 conventions, etc.
  40 A program needs to be able to determine its locale
  41 and act accordingly to be portable to different cultures.
  42 .PP
  43 The header
  44 .I <locale.h>
  45 declares data types, functions and macros which are useful in this
  46 task.
  47 .PP
  48 The functions it declares are
  49 .BR setlocale (3)
  50 to set the current locale, and
  51 .BR localeconv (3)
  52 to get information about number formatting.
  53 .PP
  54 There are different categories for local information a program might
  55 need; they are declared as macros.
  56 Using them as the first argument
  57 to the
  58 .BR setlocale (3)
  59 function, it is possible to set one of these to the desired locale:
  60 .TP
  61 .B LC_COLLATE
  62 This is used to change the behavior of the functions
  63 .BR strcoll (3)
  64 and
  65 .BR strxfrm (3),
  66 which are used to compare strings in the local alphabet.
  67 For example,
  68 the German sharp s is sorted as "ss".
  69 .TP
  70 .B LC_CTYPE
  71 This changes the behavior of the character handling and
  72 classification functions, such as
  73 .BR isupper (3)
  74 and
  75 .BR toupper (3),
  76 and the multibyte character functions such as
  77 .BR mblen (3)
  78 or
  79 .BR wctomb (3).
  80 .TP
  81 .B LC_MONETARY
  82 changes the information returned by
  83 .BR localeconv (3)
  84 which describes the way numbers are usually printed, with details such
  85 as decimal point versus decimal comma.
  86 This information is internally
  87 used by the function
  88 .BR strfmon (3).
  89 .TP
  90 .B LC_MESSAGES
  91 changes the language messages are displayed in and what an affirmative or
  92 negative answer looks like.
  93 The GNU C-library contains the
  94 .BR gettext (3),
  95 .BR ngettext (3),
  96 and
  97 .BR rpmatch (3)
  98 functions to ease the use of these information.
  99 The GNU gettext family of
 100 functions also obey the environment variable
 101 .BR LANGUAGE
 102 (containing a colon-separated list of locales)
 103 if the category is set to a valid locale other than
 104 .BR """C""" .
 105 .TP
 106 .B LC_NUMERIC
 107 changes the information used by the
 108 .BR printf (3)
 109 and
 110 .BR scanf (3)
 111 family of functions, when they are advised to use the locale-settings.
 112 This information can also be read with the
 113 .BR localeconv (3)
 114 function.
 115 .TP
 116 .B LC_TIME
 117 changes the behavior of the
 118 .BR strftime (3)
 119 function to display the current time in a locally acceptable form; for
 120 example, most of Europe uses a 24-hour clock versus the
 121 12-hour clock used in the United States.
 122 .TP
 123 .B LC_ALL
 124 All of the above.
 125 .\" FIXME glibc 2.2.2 added new nonstandard locale categories:
 126 .\" LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_NAME,
 127 .\" LC_PAPER, LC_TELEPHONE.  These need to be documented.
 128 .PP
 129 If the second argument to
 130 .BR setlocale (3)
 131 is empty string,
 132 .BR """""" ,
 133 for the default locale, it is determined using the following steps:
 134 .IP 1.
 135 If there is a non-null environment variable
 136 .BR LC_ALL ,
 137 the value of
 138 .B LC_ALL
 139 is used.
 140 .IP 2.
 141 If an environment variable with the same name as one of the categories
 142 above exists and is non-null, its value is used for that category.
 143 .IP 3.
 144 If there is a non-null environment variable
 145 .BR LANG ,
 146 the value of
 147 .B LANG
 148 is used.
 149 .PP
 150 Values about local numeric formatting is made available in a
 151 .I struct lconv
 152 returned by the
 153 .BR localeconv (3)
 154 function, which has the following declaration:
 155 .in +2n
 156 .nf
 157
 158 struct lconv {
 159
 160     /* Numeric (nonmonetary) information */
 161
 162     char *decimal_point;     /* Radix character */
 163     char *thousands_sep;     /* Separator for digit groups to left
 164                                 of radix character */
 165     char *grouping; /* Each element is the number of digits in a
 166                        group; elements with higher indices are
 167                        further left.  An element with value CHAR_MAX
 168                        means that no further grouping is done.  An
 169                        element with value 0 means that the previous
 170                        element is used for all groups further left. */
 171
 172     /* Remaining fields are for monetary information */
 173
 174     char *int_curr_symbol;   /* First three chars are a currency symbol
 175                                 from ISO 4217.  Fourth char is the
 176                                 separator.  Fifth char is \(aq\\0\(aq. */
 177     char *currency_symbol;   /* Local currency symbol */
 178     char *mon_decimal_point; /* Radix character */
 179     char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */
 180     char *mon_grouping;      /* Like \fIgrouping\fP above */
 181     char *positive_sign;     /* Sign for positive values */
 182     char *negative_sign;     /* Sign for negative values */
 183     char  int_frac_digits;   /* International fractional digits */
 184     char  frac_digits;       /* Local fractional digits */
 185     char  p_cs_precedes;     /* 1 if currency_symbol precedes a
 186                                 positive value, 0 if succeeds */
 187     char  p_sep_by_space;    /* 1 if a space separates currency_symbol
 188                                 from a positive value */
 189     char  n_cs_precedes;     /* 1 if currency_symbol precedes a
 190                                 negative value, 0 if succeeds */
 191     char  n_sep_by_space;    /* 1 if a space separates currency_symbol
 192                                 from a negative value */
 193     /* Positive and negative sign positions:
 194        0 Parentheses surround the quantity and currency_symbol.
 195        1 The sign string precedes the quantity and currency_symbol.
 196        2 The sign string succeeds the quantity and currency_symbol.
 197        3 The sign string immediately precedes the currency_symbol.
 198        4 The sign string immediately succeeds the currency_symbol. */
 199     char  p_sign_posn;
 200     char  n_sign_posn;
 201 };
 202 .fi
 203 .in
 204 .SH "CONFORMING TO"
 205 POSIX.1-2001.
 206
 207 The GNU gettext functions are specified in LI18NUX2000.
 208 .SH "SEE ALSO"
 209 .BR locale (1),
 210 .BR localedef (1),
 211 .BR gettext (3),
 212 .BR localeconv (3),
 213 .BR ngettext (3),
 214 .BR nl_langinfo (3),
 215 .BR rpmatch (3),
 216 .BR setlocale (3),
 217 .BR strcoll (3),
 218 .BR strfmon (3),
 219 .BR strftime (3),
 220 .BR strxfrm (3)