man7/locale.7

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