Initial revision
[kopensolaris-gnu/glibc.git] / manual / locale.texi
1 @node Localization
2 @chapter Localization
3 @pindex <locale.h>
4 @cindex locale
5
6 There are a number of features of the run-time library whose exact
7 behavior is specific to the @dfn{locale} or local language and cultural
8 conventions.  Examples of these features include:
9
10 @itemize @bullet
11 @item
12 The collating sequence for the local language and character set
13 (@pxref{Collation Functions}).
14
15 @item
16 Classification of which characters in the local character set are
17 considered alphabetic, and upper- and lower-case conversion conventions
18 (@pxref{Character Handling}).
19
20 @item
21 Formatting of numbers and currency amounts.
22
23 @item
24 Formatting of the date and time (@pxref{Formatting Date and Time}).
25
26 @item
27 What multibyte character sequences are valid, and how they are
28 interpreted (@pxref{Extended Characters}).
29 @end itemize
30
31 This chapter discusses the mechanism by which you can modify the
32 current locale.  This mechanism is declared in the header file
33 @file{<locale.h>}.  The effects of the current locale on specific
34 library functions are discussed in more detail in the descriptions of
35 those functions.
36
37 @menu
38 * Attributes of a Locale::              The attributes of a locale are grouped
39                                          into categories.
40 * Locale Names::                        How locales are named; about the
41                                          standard locales.
42 * Changing the Locale::                 How to specify which locale to use.
43 * Numeric and Monetary Formatting::     Inquiries about the current locale.
44 @end menu
45
46 @node Attributes of a Locale
47 @section Attributes of a Locale
48
49 @cindex categories, of locale attributes
50 @cindex locale, attribute categories
51 The current locale is modified by selecting groups or categories
52 of attributes from other locales, rather than by specifying values for
53 individual parameters.  You can mix different attribute categories
54 from different locales.
55
56 These locale attribute categories are defined as preprocessor
57 macros in @file{<locale.h>}.  The value of each of these macros
58 is an integer constant expression.
59
60 @defvr Macro LC_ALL
61 Selects all attributes.
62 @end defvr
63
64 @defvr Macro LC_COLLATE
65 Selects attributes affecting the collation sequence (functions @code{strcoll}
66 and @code{strxfrm}; @pxref{Collation Functions}.
67 @end defvr
68
69 @defvr Macro LC_CTYPE
70 Selects attributes affecting classification and conversion of characters;
71 @pxref{Character Handling}.
72 @end defvr
73
74 @defvr Macro LC_MONETARY
75 Selects attributes affecting how monetary values should be formatted,
76 returned by the @code{localeconv} function; @pxref{Numeric and Monetary
77 Formatting}.
78 @end defvr
79
80 @defvr Macro LC_NUMERIC
81 Selects attributes affecting formatting of numeric values;
82 @pxref{Numeric and Monetary Formatting}.
83 @end defvr
84
85 @defvr Macro LC_TIME
86 Selects attributes affecting formatting of date and time values;
87 @pxref{Formatting Date and Time}.
88 @end defvr
89
90 The ANSI C standard permits implementations to define additional attribute
91 categories.  You should consider all names that begin with the characters
92 @samp{LC_} as being reserved for this purpose.
93
94 @strong{Incomplete:}  Does the GNU library define any additional
95 attributes?
96
97 @node Locale Names
98 @section Locale Names
99
100 @cindex locale names
101 Locales are referred to by names, which are strings.  There are three
102 built-in locales that are always available:
103
104 @table @code
105 @item "C"
106 This is the standard C locale.  The attributes and behavior it provides
107 are specified in the ANSI C standard.  When your program starts up, it
108 initially uses this locale by default.
109
110 @item "POSIX"
111 This is the standard POSIX locale.  It behaves the same way as the
112 @code{"C"} locale for most things.  Eventually, other parts of the POSIX
113 standard may specify additional requirements for this locale.
114
115 @item ""
116 The locale representing the local conventions, with
117 implementation-defined attributes.  
118 @end table
119
120 There might also be additional, non-standard locales available on the
121 particular machine you are using.  Defining and installing named locales
122 is normally a responsibility of the system administrator at your site
123 (or the person who installed the GNU C Library).  @xref{Locale Writing},
124 for information about what this involves.
125
126 You cannot readily define the attributes of new, named locales in the
127 programs you write.  You can only select attribute categories from named
128 locales that are already installed.
129
130 Likewise, individual users of your program cannot easily define new
131 named locales for it to use, either.  However, users @emph{can}
132 customize the attributes of the @code{""} locale by means of environment
133 variables.  These are discussed in more detail in @ref{Standard
134 Environment Variables}.  
135
136 These environment variables affect the @code{""} environment as follows.
137
138 @itemize @bullet
139 @item
140 If the @code{LC_ALL} environment variable has a value, the attributes are
141 taken from that locale.
142
143 @item
144 If the environment variable corresponding to the particular attribute
145 category (@code{LC_COLLATE}, @code{LC_CTYPE}, @code{LC_MONETARY},
146 @code{LC_NUMERIC}, and @code{LC_TIME}) has a value, the attributes are
147 taken from that locale.
148
149 @item
150 If the @code{LANG} environment variable is defined, the attributes are
151 taken from that locale.
152 @end itemize
153
154 If your program needs to use something other than the @code{"C"} locale,
155 it will be more portable if you use the @code{""} locale and leave it up
156 to users of your program to customize its attributes, than if you
157 specify some non-standard locale name explicitly.  Remember, different
158 machines might have different sets of locales installed.
159
160 @node Changing the Locale
161 @section Changing the Locale
162
163 @cindex changing the locale
164 @cindex locale, changing
165 To actually change attributes of the current locale, use the
166 @code{setlocale} function.  The prototype for this function is declared
167 in the header file @file{<locale.h>}.
168
169 @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
170 The function @code{setlocale} sets the current locale to use the attributes in
171 category @var{category} from the locale named @var{locale}.
172
173 The value of @var{category} should correspond to one of the symbolic
174 constants listed in @ref{Attributes of a Locale}; for example,
175 @code{LC_ALL} specifies all attribute categories.
176
177 You can also use this function to inquire about the current locale by
178 passing a null pointer as the @var{locale} argument.  In this case,
179 @code{setlocale} returns a string that specifies the corresponding part
180 of the current locale.  This is useful if you want to temporarily change
181 the locale from its current value, perform some computations, and then
182 restore the locale to its original state.  However, the string returned
183 by @code{setlocale} can be overwritten by subsequent calls, so you
184 should make a copy of the string (@pxref{Copying and Concatenation})
185 before making any further calls if you plan to use it for this purpose.
186 (The standard library is guaranteed never to call @code{setlocale}
187 itself.)  You should not modify the string returned by @code{setlocale}.
188
189 If the @var{locale} argument is not a null pointer, the string returned
190 by @code{setlocale} reflects the newly modified locale.  If it's not
191 possible to honor the selection for some reason (perhaps because the
192 locale name is not recognized), @code{setlocale} returns a null
193 pointer and leave the current locale unchanged.
194 @end deftypefun
195
196 Here is an example showing how you might use @code{setlocale} to
197 temporarily switch to a new locale.
198
199 @strong{Incomplete}:  This example hasn't been tested at all.
200
201 @example
202 #include <stddef.h>
203 #include <locale.h>
204 #include <stdlib.h>
205 #include <string.h>
206
207 char *old_locale, *saved_locale;
208
209 @dots{}
210
211   /* @r{Get the name of the current locale.}  */
212   old_locale = setlocale (LC_ALL, NULL);
213   
214   /* @r{If} setlocale @r{failed, give up.}  */
215   if (old_locale == NULL)  @{
216     @dots{}
217     exit (EXIT_FAILURE);
218     @}
219   
220   /* @r{Otherwise save the name of the locale.} */
221   saved_locale = malloc (strlen(old_locale));
222   strcpy (saved_locale, old_locale);
223   
224   /* @r{Now change the locale and do some stuff with it.} */
225   setlocale (LC_ALL, "")
226   @dots{}
227   
228   /* @r{Restore the original locale.} */
229   setlocale (LC_ALL, saved_locale);
230   free (saved_locale);
231 @end example
232
233 @node Numeric and Monetary Formatting
234 @section Numeric and Monetary Formatting
235
236 Sometimes your programs have need to know about the specific formatting
237 conventions for numeric quantities that are appropriate for the current
238 locale.  In particular, if your program deals with monetary quantities,
239 you'll need to know about the local conventions regarding currency
240 symbols, digit grouping and separation, and so on, which vary widely
241 from country to country.  The function @code{localeconv} is provided for
242 this purpose.  The prototype for this function is in the header file
243 @file{<locale.h>}.
244 @cindex monetary value formatting
245 @cindex numeric value formatting
246
247 @deftypefun {struct lconv *} localeconv (void)
248 The @code{localeconv} function returns a pointer to a structure whose
249 components contain information about how numeric and monetary values
250 should be formatted in the current locale.
251
252 You shouldn't modify the structure or its contents.  The structure might
253 be overwritten by subsequent calls to @code{localeconv}, or by calling
254 @code{setlocale} to alter the @code{LC_ALL}, @code{LC_MONETARY}, or
255 @code{LC_NUMERIC} categories of the current environment, but it's
256 guaranteed that no other function in the library overwrites its
257 contents.
258 @end deftypefun
259
260 @deftp {Data Type} {struct lconv}
261 This structure type contains information which defines rules for how
262 numeric and monetary values should be formatted.  It has at least the
263 following members (which, implementationally, can appear in any order):
264
265 @table @code
266 @item {char *decimal_point}
267 @itemx {char *mon_decimal_point}
268 These are the decimal-point separators used in formatting non-monetary
269 and monetary quantities, respectively.  In the @code{"C"} locale, 
270 the @code{decimal_point} member has a value of @code{"."}, and the
271 @code{mon_decimal_point} member has a value of @code{""}.
272 @cindex decimal-point separator
273
274 @item {char *thousands_sep}
275 @itemx {char *mon_thousands_sep}
276 These are the separators used to delimit groups of digits to the left of
277 the decimal point in formatting non-monetary and monetary quantities,
278 respectively.  In the @code{"C"} locale, both members have a value of
279 @code{""} (the empty string).
280
281 @item {char *grouping}
282 @itemx {char *mon_grouping}
283 These are strings whose elements indicate the size of each group of 
284 digits to the left of the decimal point in formatting non-monetary
285 and monetary quantities, respectively.
286 @cindex grouping of digits
287
288 The elements of this string are actually interpreted as numbers, not as
289 characters.  A null character (which marks the end of a string)
290 indicates that the previous grouping value is to be used repeatedly for
291 the remaining digits.  A character @code{CHAR_MAX} indicates that no
292 further grouping is to be performed.  Any other value indicates the size
293 of the next group to the left of the decimal point (the first integer
294 for the first group to the left, the second for the next group to the
295 left, and so on).  For example, a value of @code{"\3"} (a character with
296 value @code{3} followed by a character with value @code{0}) indicates
297 repeated groups of three digits.
298
299 In the standard @code{"C"} locale, both @code{grouping} and
300 @code{mon_grouping} have a value of @code{""}, indicating that no
301 grouping of digits is performed.
302
303 @item {char *int_curr_symbol}
304 @itemx {char *currency_symbol}
305 These members have values which are strings representing the currency
306 symbol for the locale.  The difference between them is that
307 @code{currency_symbol} is the symbol commonly used locally within a
308 particular country, while @code{int_curr_symbol} is used internationally
309 to refer to that country's currency.  
310
311 For example, many countries use the dollar as their monetary unit, and
312 when dealing with international currencies it's important to specify
313 that one is dealing with (say) Canadian dollars instead of U.S. dollars
314 or Australian dollars.  But locally within Canada, dollar amounts are
315 implicitly assumed to be in Canadian dollars.
316 @cindex currency symbols
317
318 In the default @code{"C"} locale, the @code{int_curr_symbol} member has
319 a value of @code{""} (the empty string).  Other possible values for this
320 string consist of a three-letter abbreviation determined by the
321 international standard @cite{ISO 4217 Codes for the Representation of
322 Currency and Funds}, followed by a one-character separator that appears
323 between the currency symbol and the monetary quantity.
324
325 The @code{currency_symbol} member has a value of @code{""} in the
326 default @code{"C"} locale.
327
328 @item {char *positive_sign}
329 @itemx {char *negative_sign}
330 These are strings used to indicate nonnegative and negative
331 (respectively) monetary quantities.  In the @code{"C"} locale, both
332 members have a value of @code{""}.
333
334 @item {char int_frac_digits}
335 @itemx {char frac_digits}
336 These are small integers indicating how many fractional digits (to
337 the right of the decimal point) should be displayed in a monetary
338 value in international and local formats, respectively.  (Normally,
339 both members have the same value.)  In the standard @code{"C"} locale,
340 they both have the value of the constant @code{CHAR_MAX}.
341
342 @item {char p_cs_precedes}
343 @itemx {char n_cs_precedes}
344 These members have a value of @code{1} if the currency symbol should
345 precede the value of a monetary quantity, or a value of @code{0} if the
346 currency symbol should be placed after the value.  The
347 @code{p_cs_precedes} member applies to nonnegative quantities, and the
348 @code{n_cs_precedes} member applies to negative quantities.
349
350 Both members have a value of @code{CHAR_MAX} in the standard @code{"C"}
351 locale.
352
353 @strong{Incomplete:}  I don't have a clue as to what the value in
354 the standard locale is supposed to mean.
355
356
357 @item {char p_sep_by_space}
358 @itemx {char n_sep_by_space}
359 These members have a value of @code{1} if a space should appear between
360 the currency symbol and the value of monetary quantity, or a value of
361 @code{0} if no space should appear.  The @code{p_sep_by_space} member
362 applies to nonnegative quantities, and the @code{n_sep_by_space} member
363 applies to negative quantities.
364
365 Both members have a value of @code{CHAR_MAX} in the standard @code{"C"}
366 locale.
367
368 @strong{Incomplete:}  I don't have a clue as to what the value in
369 the standard locale is supposed to mean.
370
371 @item {char p_sign_posn}
372 @itemx {char n_sign_posn}
373 These members have values that are small integers indicating positioning
374 of the @code{positive_sign} or @code{negative_sign} for nonnegative
375 and negative monetary quantities, respectively.  The possible values are
376 as follows:
377
378 @table @code
379 @item 0
380 The currency symbol and quantity should be surrounded by parentheses.
381
382 @item 1
383 The sign string should be placed before the quantity and currency symbol.
384
385 @item 2
386 The sign string should be placed after the quantity and currency symbol.
387
388 @item 3
389 The sign string should be placed immediately before the currency symbol.
390
391 @item 4
392 The sign string should be placed immediately after the currency symbol.
393 @end table
394
395 Both members have a value of @code{CHAR_MAX} in the standard @code{"C"}
396 locale.
397
398 @strong{Incomplete:}  I don't have a clue as to what the value in
399 the standard locale is supposed to mean.
400 @end table
401 @end deftp
402
403