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