man7/locale.7

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