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