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