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.
  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 ()
  50 to set the current locale, and
  51 .BR localeconv ()
  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 ()
  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 behaviour of the functions
  63 .BR strcoll ()
  64 and
  65 .BR strxfrm (),
  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 behaviour of the character handling and
  72 classification functions, such as
  73 .BR isupper ()
  74 and
  75 .BR toupper (),
  76 and the multi\-byte character functions such as
  77 .BR mblen ()
  78 or
  79 .BR wctomb ().
  80 .TP
  81 .B LC_MONETARY
  82 changes the information returned by
  83 .BR localeconv ()
  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 ().
  89 .TP
  90 .B LC_MESSAGES
  91 changes the language messages are displayed in and how an affirmative or
  92 negative answer looks like.
  93 The GNU C-library contains the
  94 .BR gettext (),
  95 .BR ngettext (),
  96 and
  97 .BR rpmatch ()
  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 .TP
 103 .B LC_NUMERIC
 104 changes the information used by the
 105 .BR printf ()
 106 and
 107 .BR scanf ()
 108 family of functions, when they are advised to use the locale-settings.
 109 This information can also be read with the
 110 .BR localeconv ()
 111 function.
 112 .TP
 113 .B LC_TIME
 114 changes the behaviour of the
 115 .BR strftime ()
 116 function to display the current time in a locally acceptable form; for
 117 example, most of Europe uses a 24\-hour clock versus the
 118 12\-hour clock used in the United States.
 119 .TP
 120 .B LC_ALL
 121 All of the above.
 122 .\" FIXME glibc 2.2.2 added new non-standard locale categories:
 123 .\" LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_NAME,
 124 .\" LC_PAPER, LC_TELEPHONE.  These need to be documented.
 125 .PP
 126 If the second argument to
 127 .BR setlocale ()
 128 is empty string,
 129 .BR """""" ,
 130 for the default locale, it is determined using the following steps:
 131 .IP 1.
 132 If there is a non-null environment variable
 133 .BR LC_ALL ,
 134 the value of
 135 .B LC_ALL
 136 is used.
 137 .IP 2.
 138 If an environment variable with the same name as one of the categories
 139 above exists and is non-null, its value is used for that category.
 140 .IP 3.
 141 If there is a non-null environment variable
 142 .BR LANG ,
 143 the value of
 144 .B LANG
 145 is used.
 146 .PP
 147 Values about local numeric formatting is made available in a
 148 .I struct lconv
 149 returned by the
 150 .BR localeconv ()
 151 function, which has the following declaration:
 152 .in +0.25i
 153 .nf
 154
 155 struct lconv {
 156
 157   /* Numeric (non-monetary) information */
 158
 159   char *decimal_point;     /* Radix character */
 160   char *thousands_sep;     /* Separator for digit groups to left
 161                               of radix character */
 162   char *grouping; /* Each element is the number of digits in a
 163                      group; elements with higher indices are
 164                      further left.  An element with value CHAR_MAX
 165                      means that no further grouping is done.  An
 166                      element with value 0 means that the previous
 167                      element is used for all groups further left. */
 168
 169   /* Remaining fields are for monetary information */
 170
 171   char *int_curr_symbol;   /* First three chars are a currency symbol
 172                                from ISO 4217.  Fourth char is the
 173                                separator.  Fifth char is '\0'. */
 174   char *currency_symbol;   /* Local currency symbol */
 175   char *mon_decimal_point; /* Radix character */
 176   char *mon_thousands_sep; /* Like `thousands_sep' above */
 177   char *mon_grouping;      /* Like `grouping' above */
 178   char *positive_sign;     /* Sign for positive values */
 179   char *negative_sign;     /* Sign for negative values */
 180   char  int_frac_digits;   /* Int'l fractional digits */
 181   char  frac_digits;       /* Local fractional digits */
 182   char  p_cs_precedes;     /* 1 if currency_symbol precedes a
 183                               positive value, 0 if succeeds */
 184   char  p_sep_by_space;    /* 1 if a space separates currency_symbol
 185                               from a positive value */
 186   char  n_cs_precedes;     /* 1 if currency_symbol precedes a
 187                               negative value, 0 if succeeds */
 188   char  n_sep_by_space;    /* 1 if a space separates currency_symbol
 189                               from a negative value */
 190   /* Positive and negative sign positions:
 191      0 Parentheses surround the quantity and currency_symbol.
 192      1 The sign string precedes the quantity and currency_symbol.
 193      2 The sign string succeeds the quantity and currency_symbol.
 194      3 The sign string immediately precedes the currency_symbol.
 195      4 The sign string immediately succeeds the currency_symbol. */
 196   char  p_sign_posn;
 197   char  n_sign_posn;
 198 };
 199 .fi
 200 .in +0.25i
 201 .SH "CONFORMING TO"
 202 POSIX.1-2001.
 203
 204 The GNU gettext functions are specified in LI18NUX2000.
 205 .SH "SEE ALSO"
 206 .BR locale (1),
 207 .BR localedef (1),
 208 .BR gettext (3),
 209 .BR localeconv (3),
 210 .BR ngettext (3),
 211 .BR nl_langinfo (3),
 212 .BR rpmatch (3),
 213 .BR setlocale (3),
 214 .BR strcoll (3),
 215 .BR strfmon (3),
 216 .BR strftime (3),
 217 .BR strxfrm (3)