]>
Commit | Line | Data |
---|---|---|
bd76bcb8 MT |
1 | commit 585367266923156ac6fb789939a923641ba5aaf4 |
2 | Author: Florian Weimer <fweimer@redhat.com> | |
3 | Date: Wed May 28 14:05:03 2014 +0200 | |
4 | ||
5 | manual: Update the locale documentation | |
6 | ||
7 | commit 4e8f95a0df7c2300b830ec12c0ae1e161bc8a8a3 | |
8 | Author: Florian Weimer <fweimer@redhat.com> | |
9 | Date: Mon May 12 15:24:12 2014 +0200 | |
10 | ||
11 | _nl_find_locale: Improve handling of crafted locale names [BZ #17137] | |
12 | ||
13 | Prevent directory traversal in locale-related environment variables | |
14 | (CVE-2014-0475). | |
15 | ||
16 | commit d183645616b0533b3acee28f1a95570bffbdf50f | |
17 | Author: Florian Weimer <fweimer@redhat.com> | |
18 | Date: Wed May 28 14:41:52 2014 +0200 | |
19 | ||
20 | setlocale: Use the heap for the copy of the locale argument | |
21 | ||
22 | This avoids alloca calls with potentially large arguments. | |
23 | ||
24 | diff -pruN glibc-2.18/locale/findlocale.c glibc-2.18.patched/locale/findlocale.c | |
25 | --- glibc-2.18/locale/findlocale.c 2013-08-11 04:22:55.000000000 +0530 | |
26 | +++ glibc-2.18.patched/locale/findlocale.c 2014-08-26 16:14:50.403253778 +0530 | |
27 | @@ -17,6 +17,7 @@ | |
28 | 02111-1307 USA. */ | |
29 | ||
30 | #include <assert.h> | |
31 | +#include <errno.h> | |
32 | #include <locale.h> | |
33 | #include <stdlib.h> | |
34 | #include <string.h> | |
35 | @@ -57,6 +58,45 @@ struct loaded_l10nfile *_nl_locale_file_ | |
36 | ||
37 | const char _nl_default_locale_path[] attribute_hidden = LOCALEDIR; | |
38 | ||
39 | +/* Checks if the name is actually present, that is, not NULL and not | |
40 | + empty. */ | |
41 | +static inline int | |
42 | +name_present (const char *name) | |
43 | +{ | |
44 | + return name != NULL && name[0] != '\0'; | |
45 | +} | |
46 | + | |
47 | +/* Checks that the locale name neither extremely long, nor contains a | |
48 | + ".." path component (to prevent directory traversal). */ | |
49 | +static inline int | |
50 | +valid_locale_name (const char *name) | |
51 | +{ | |
52 | + /* Not set. */ | |
53 | + size_t namelen = strlen (name); | |
54 | + /* Name too long. The limit is arbitrary and prevents stack overflow | |
55 | + issues later. */ | |
56 | + if (__builtin_expect (namelen > 255, 0)) | |
57 | + return 0; | |
58 | + /* Directory traversal attempt. */ | |
59 | + static const char slashdot[4] = {'/', '.', '.', '/'}; | |
60 | + if (__builtin_expect (memmem (name, namelen, | |
61 | + slashdot, sizeof (slashdot)) != NULL, 0)) | |
62 | + return 0; | |
63 | + if (namelen == 2 && __builtin_expect (name[0] == '.' && name [1] == '.', 0)) | |
64 | + return 0; | |
65 | + if (namelen >= 3 | |
66 | + && __builtin_expect (((name[0] == '.' | |
67 | + && name[1] == '.' | |
68 | + && name[2] == '/') | |
69 | + || (name[namelen - 3] == '/' | |
70 | + && name[namelen - 2] == '.' | |
71 | + && name[namelen - 1] == '.')), 0)) | |
72 | + return 0; | |
73 | + /* If there is a slash in the name, it must start with one. */ | |
74 | + if (__builtin_expect (memchr (name, '/', namelen) != NULL, 0) && name[0] != '/') | |
75 | + return 0; | |
76 | + return 1; | |
77 | +} | |
78 | ||
79 | struct __locale_data * | |
80 | internal_function | |
81 | @@ -65,7 +105,7 @@ _nl_find_locale (const char *locale_path | |
82 | { | |
83 | int mask; | |
84 | /* Name of the locale for this category. */ | |
85 | - char *loc_name; | |
86 | + char *loc_name = (char *) *name; | |
87 | const char *language; | |
88 | const char *modifier; | |
89 | const char *territory; | |
90 | @@ -73,31 +113,39 @@ _nl_find_locale (const char *locale_path | |
91 | const char *normalized_codeset; | |
92 | struct loaded_l10nfile *locale_file; | |
93 | ||
94 | - if ((*name)[0] == '\0') | |
95 | + if (loc_name[0] == '\0') | |
96 | { | |
97 | /* The user decides which locale to use by setting environment | |
98 | variables. */ | |
99 | - *name = getenv ("LC_ALL"); | |
100 | - if (*name == NULL || (*name)[0] == '\0') | |
101 | - *name = getenv (_nl_category_names.str | |
102 | + loc_name = getenv ("LC_ALL"); | |
103 | + if (!name_present (loc_name)) | |
104 | + loc_name = getenv (_nl_category_names.str | |
105 | + _nl_category_name_idxs[category]); | |
106 | - if (*name == NULL || (*name)[0] == '\0') | |
107 | - *name = getenv ("LANG"); | |
108 | + if (!name_present (loc_name)) | |
109 | + loc_name = getenv ("LANG"); | |
110 | + if (!name_present (loc_name)) | |
111 | + loc_name = (char *) _nl_C_name; | |
112 | } | |
113 | ||
114 | - if (*name == NULL || (*name)[0] == '\0' | |
115 | - || (__builtin_expect (__libc_enable_secure, 0) | |
116 | - && strchr (*name, '/') != NULL)) | |
117 | - *name = (char *) _nl_C_name; | |
118 | + /* We used to fall back to the C locale if the name contains a slash | |
119 | + character '/', but we now check for directory traversal in | |
120 | + valid_locale_name, so this is no longer necessary. */ | |
121 | ||
122 | - if (__builtin_expect (strcmp (*name, _nl_C_name), 1) == 0 | |
123 | - || __builtin_expect (strcmp (*name, _nl_POSIX_name), 1) == 0) | |
124 | + if (__builtin_expect (strcmp (loc_name, _nl_C_name), 1) == 0 | |
125 | + || __builtin_expect (strcmp (loc_name, _nl_POSIX_name), 1) == 0) | |
126 | { | |
127 | /* We need not load anything. The needed data is contained in | |
128 | the library itself. */ | |
129 | *name = (char *) _nl_C_name; | |
130 | return _nl_C[category]; | |
131 | } | |
132 | + else if (!valid_locale_name (loc_name)) | |
133 | + { | |
134 | + __set_errno (EINVAL); | |
135 | + return NULL; | |
136 | + } | |
137 | + | |
138 | + *name = loc_name; | |
139 | ||
140 | /* We really have to load some data. First we try the archive, | |
141 | but only if there was no LOCPATH environment variable specified. */ | |
142 | diff -pruN glibc-2.18/locale/setlocale.c glibc-2.18.patched/locale/setlocale.c | |
143 | --- glibc-2.18/locale/setlocale.c 2013-08-11 04:22:55.000000000 +0530 | |
144 | +++ glibc-2.18.patched/locale/setlocale.c 2014-08-26 16:14:50.401253764 +0530 | |
145 | @@ -272,6 +272,8 @@ setlocale (int category, const char *loc | |
146 | of entries of the form `CATEGORY=VALUE'. */ | |
147 | const char *newnames[__LC_LAST]; | |
148 | struct __locale_data *newdata[__LC_LAST]; | |
149 | + /* Copy of the locale argument, for in-place splitting. */ | |
150 | + char *locale_copy = NULL; | |
151 | ||
152 | /* Set all name pointers to the argument name. */ | |
153 | for (category = 0; category < __LC_LAST; ++category) | |
154 | @@ -281,7 +283,13 @@ setlocale (int category, const char *loc | |
155 | if (__builtin_expect (strchr (locale, ';') != NULL, 0)) | |
156 | { | |
157 | /* This is a composite name. Make a copy and split it up. */ | |
158 | - char *np = strdupa (locale); | |
159 | + locale_copy = strdup (locale); | |
160 | + if (__builtin_expect (locale_copy == NULL, 0)) | |
161 | + { | |
162 | + __libc_rwlock_unlock (__libc_setlocale_lock); | |
163 | + return NULL; | |
164 | + } | |
165 | + char *np = locale_copy; | |
166 | char *cp; | |
167 | int cnt; | |
168 | ||
169 | @@ -299,6 +307,7 @@ setlocale (int category, const char *loc | |
170 | { | |
171 | error_return: | |
172 | __libc_rwlock_unlock (__libc_setlocale_lock); | |
173 | + free (locale_copy); | |
174 | ||
175 | /* Bogus category name. */ | |
176 | ERROR_RETURN; | |
177 | @@ -391,8 +400,9 @@ setlocale (int category, const char *loc | |
178 | /* Critical section left. */ | |
179 | __libc_rwlock_unlock (__libc_setlocale_lock); | |
180 | ||
181 | - /* Free the resources (the locale path variable). */ | |
182 | + /* Free the resources. */ | |
183 | free (locale_path); | |
184 | + free (locale_copy); | |
185 | ||
186 | return composite; | |
187 | } | |
188 | diff -pruN glibc-2.18/localedata/Makefile glibc-2.18.patched/localedata/Makefile | |
189 | --- glibc-2.18/localedata/Makefile 2014-08-26 16:15:22.656474571 +0530 | |
190 | +++ glibc-2.18.patched/localedata/Makefile 2014-08-26 16:14:50.403253778 +0530 | |
191 | @@ -77,7 +77,7 @@ locale_test_suite := tst_iswalnum tst_is | |
192 | ||
193 | tests = $(locale_test_suite) tst-digits tst-setlocale bug-iconv-trans \ | |
194 | tst-leaks tst-mbswcs6 tst-xlocale1 tst-xlocale2 bug-usesetlocale \ | |
195 | - tst-strfmon1 tst-sscanf tst-strptime | |
196 | + tst-strfmon1 tst-sscanf tst-strptime tst-setlocale3 | |
197 | ifeq (yes,$(build-shared)) | |
198 | ifneq (no,$(PERL)) | |
199 | tests: $(objpfx)mtrace-tst-leaks | |
200 | @@ -288,6 +288,7 @@ tst-strfmon1-ENV = $(TEST_MBWC_ENV) | |
201 | tst-strptime-ENV = $(TEST_MBWC_ENV) | |
202 | ||
203 | tst-setlocale-ENV = LOCPATH=$(common-objpfx)localedata LC_ALL=ja_JP.EUC-JP | |
204 | +tst-setlocale3-ENV = LOCPATH=$(common-objpfx)localedata | |
205 | ||
206 | bug-iconv-trans-ENV = LOCPATH=$(common-objpfx)localedata | |
207 | ||
208 | diff -pruN glibc-2.18/localedata/tst-setlocale3.c glibc-2.18.patched/localedata/tst-setlocale3.c | |
209 | --- glibc-2.18/localedata/tst-setlocale3.c 1970-01-01 05:30:00.000000000 +0530 | |
210 | +++ glibc-2.18.patched/localedata/tst-setlocale3.c 2014-08-26 16:14:50.403253778 +0530 | |
211 | @@ -0,0 +1,203 @@ | |
212 | +/* Regression test for setlocale invalid environment variable handling. | |
213 | + Copyright (C) 2014 Free Software Foundation, Inc. | |
214 | + This file is part of the GNU C Library. | |
215 | + | |
216 | + The GNU C Library is free software; you can redistribute it and/or | |
217 | + modify it under the terms of the GNU Lesser General Public | |
218 | + License as published by the Free Software Foundation; either | |
219 | + version 2.1 of the License, or (at your option) any later version. | |
220 | + | |
221 | + The GNU C Library is distributed in the hope that it will be useful, | |
222 | + but WITHOUT ANY WARRANTY; without even the implied warranty of | |
223 | + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
224 | + Lesser General Public License for more details. | |
225 | + | |
226 | + You should have received a copy of the GNU Lesser General Public | |
227 | + License along with the GNU C Library; if not, see | |
228 | + <http://www.gnu.org/licenses/>. */ | |
229 | + | |
230 | +#include <locale.h> | |
231 | +#include <stdio.h> | |
232 | +#include <stdlib.h> | |
233 | +#include <string.h> | |
234 | + | |
235 | +/* The result of setlocale may be overwritten by subsequent calls, so | |
236 | + this wrapper makes a copy. */ | |
237 | +static char * | |
238 | +setlocale_copy (int category, const char *locale) | |
239 | +{ | |
240 | + const char *result = setlocale (category, locale); | |
241 | + if (result == NULL) | |
242 | + return NULL; | |
243 | + return strdup (result); | |
244 | +} | |
245 | + | |
246 | +static char *de_locale; | |
247 | + | |
248 | +static void | |
249 | +setlocale_fail (const char *envstring) | |
250 | +{ | |
251 | + setenv ("LC_CTYPE", envstring, 1); | |
252 | + if (setlocale (LC_CTYPE, "") != NULL) | |
253 | + { | |
254 | + printf ("unexpected setlocale success for \"%s\" locale\n", envstring); | |
255 | + exit (1); | |
256 | + } | |
257 | + const char *newloc = setlocale (LC_CTYPE, NULL); | |
258 | + if (strcmp (newloc, de_locale) != 0) | |
259 | + { | |
260 | + printf ("failed setlocale call \"%s\" changed locale to \"%s\"\n", | |
261 | + envstring, newloc); | |
262 | + exit (1); | |
263 | + } | |
264 | +} | |
265 | + | |
266 | +static void | |
267 | +setlocale_success (const char *envstring) | |
268 | +{ | |
269 | + setenv ("LC_CTYPE", envstring, 1); | |
270 | + char *newloc = setlocale_copy (LC_CTYPE, ""); | |
271 | + if (newloc == NULL) | |
272 | + { | |
273 | + printf ("setlocale for \"%s\": %m\n", envstring); | |
274 | + exit (1); | |
275 | + } | |
276 | + if (strcmp (newloc, de_locale) == 0) | |
277 | + { | |
278 | + printf ("setlocale with LC_CTYPE=\"%s\" left locale at \"%s\"\n", | |
279 | + envstring, de_locale); | |
280 | + exit (1); | |
281 | + } | |
282 | + if (setlocale (LC_CTYPE, de_locale) == NULL) | |
283 | + { | |
284 | + printf ("restoring locale \"%s\" with LC_CTYPE=\"%s\": %m\n", | |
285 | + de_locale, envstring); | |
286 | + exit (1); | |
287 | + } | |
288 | + char *newloc2 = setlocale_copy (LC_CTYPE, newloc); | |
289 | + if (newloc2 == NULL) | |
290 | + { | |
291 | + printf ("restoring locale \"%s\" following \"%s\": %m\n", | |
292 | + newloc, envstring); | |
293 | + exit (1); | |
294 | + } | |
295 | + if (strcmp (newloc, newloc2) != 0) | |
296 | + { | |
297 | + printf ("representation of locale \"%s\" changed from \"%s\" to \"%s\"", | |
298 | + envstring, newloc, newloc2); | |
299 | + exit (1); | |
300 | + } | |
301 | + free (newloc); | |
302 | + free (newloc2); | |
303 | + | |
304 | + if (setlocale (LC_CTYPE, de_locale) == NULL) | |
305 | + { | |
306 | + printf ("restoring locale \"%s\" with LC_CTYPE=\"%s\": %m\n", | |
307 | + de_locale, envstring); | |
308 | + exit (1); | |
309 | + } | |
310 | +} | |
311 | + | |
312 | +/* Checks that a known-good locale still works if LC_ALL contains a | |
313 | + value which should be ignored. */ | |
314 | +static void | |
315 | +setlocale_ignore (const char *to_ignore) | |
316 | +{ | |
317 | + const char *fr_locale = "fr_FR.UTF-8"; | |
318 | + setenv ("LC_CTYPE", fr_locale, 1); | |
319 | + char *expected_locale = setlocale_copy (LC_CTYPE, ""); | |
320 | + if (expected_locale == NULL) | |
321 | + { | |
322 | + printf ("setlocale with LC_CTYPE=\"%s\" failed: %m\n", fr_locale); | |
323 | + exit (1); | |
324 | + } | |
325 | + if (setlocale (LC_CTYPE, de_locale) == NULL) | |
326 | + { | |
327 | + printf ("failed to restore locale: %m\n"); | |
328 | + exit (1); | |
329 | + } | |
330 | + unsetenv ("LC_CTYPE"); | |
331 | + | |
332 | + setenv ("LC_ALL", to_ignore, 1); | |
333 | + setenv ("LC_CTYPE", fr_locale, 1); | |
334 | + const char *actual_locale = setlocale (LC_CTYPE, ""); | |
335 | + if (actual_locale == NULL) | |
336 | + { | |
337 | + printf ("setlocale with LC_ALL, LC_CTYPE=\"%s\" failed: %m\n", | |
338 | + fr_locale); | |
339 | + exit (1); | |
340 | + } | |
341 | + if (strcmp (actual_locale, expected_locale) != 0) | |
342 | + { | |
343 | + printf ("setlocale under LC_ALL failed: got \"%s\", expected \"%s\"\n", | |
344 | + actual_locale, expected_locale); | |
345 | + exit (1); | |
346 | + } | |
347 | + unsetenv ("LC_CTYPE"); | |
348 | + setlocale_success (fr_locale); | |
349 | + unsetenv ("LC_ALL"); | |
350 | + free (expected_locale); | |
351 | +} | |
352 | + | |
353 | +static int | |
354 | +do_test (void) | |
355 | +{ | |
356 | + /* The glibc test harness sets this environment variable | |
357 | + uncondionally. */ | |
358 | + unsetenv ("LC_ALL"); | |
359 | + | |
360 | + de_locale = setlocale_copy (LC_CTYPE, "de_DE.UTF-8"); | |
361 | + if (de_locale == NULL) | |
362 | + { | |
363 | + printf ("setlocale (LC_CTYPE, \"de_DE.UTF-8\"): %m\n"); | |
364 | + return 1; | |
365 | + } | |
366 | + setlocale_success ("C"); | |
367 | + setlocale_success ("en_US.UTF-8"); | |
368 | + setlocale_success ("/en_US.UTF-8"); | |
369 | + setlocale_success ("//en_US.UTF-8"); | |
370 | + setlocale_ignore (""); | |
371 | + | |
372 | + setlocale_fail ("does-not-exist"); | |
373 | + setlocale_fail ("/"); | |
374 | + setlocale_fail ("/../localedata/en_US.UTF-8"); | |
375 | + setlocale_fail ("en_US.UTF-8/"); | |
376 | + setlocale_fail ("en_US.UTF-8/.."); | |
377 | + setlocale_fail ("en_US.UTF-8/../en_US.UTF-8"); | |
378 | + setlocale_fail ("../localedata/en_US.UTF-8"); | |
379 | + { | |
380 | + size_t large_length = 1024; | |
381 | + char *large_name = malloc (large_length + 1); | |
382 | + if (large_name == NULL) | |
383 | + { | |
384 | + puts ("malloc failure"); | |
385 | + return 1; | |
386 | + } | |
387 | + memset (large_name, '/', large_length); | |
388 | + const char *suffix = "en_US.UTF-8"; | |
389 | + strcpy (large_name + large_length - strlen (suffix), suffix); | |
390 | + setlocale_fail (large_name); | |
391 | + free (large_name); | |
392 | + } | |
393 | + { | |
394 | + size_t huge_length = 64 * 1024 * 1024; | |
395 | + char *huge_name = malloc (huge_length + 1); | |
396 | + if (huge_name == NULL) | |
397 | + { | |
398 | + puts ("malloc failure"); | |
399 | + return 1; | |
400 | + } | |
401 | + memset (huge_name, 'X', huge_length); | |
402 | + huge_name[huge_length] = '\0'; | |
403 | + /* Construct a composite locale specification. */ | |
404 | + const char *prefix = "LC_CTYPE=de_DE.UTF-8;LC_TIME="; | |
405 | + memcpy (huge_name, prefix, strlen (prefix)); | |
406 | + setlocale_fail (huge_name); | |
407 | + free (huge_name); | |
408 | + } | |
409 | + | |
410 | + return 0; | |
411 | +} | |
412 | + | |
413 | +#define TEST_FUNCTION do_test () | |
414 | +#include "../test-skeleton.c" | |
415 | diff -pruN glibc-2.18/manual/locale.texi glibc-2.18.patched/manual/locale.texi | |
416 | --- glibc-2.18/manual/locale.texi 2013-08-11 04:22:55.000000000 +0530 | |
417 | +++ glibc-2.18.patched/manual/locale.texi 2014-08-26 16:14:50.404253785 +0530 | |
418 | @@ -29,6 +29,7 @@ will follow the conventions preferred by | |
419 | * Setting the Locale:: How a program specifies the locale | |
420 | with library functions. | |
421 | * Standard Locales:: Locale names available on all systems. | |
422 | +* Locale Names:: Format of system-specific locale names. | |
423 | * Locale Information:: How to access the information for the locale. | |
424 | * Formatting Numbers:: A dedicated function to format numbers. | |
425 | * Yes-or-No Questions:: Check a Response against the locale. | |
426 | @@ -99,14 +100,16 @@ locale named @samp{espana-castellano} to | |
427 | most of Spain. | |
428 | ||
429 | The set of locales supported depends on the operating system you are | |
430 | -using, and so do their names. We can't make any promises about what | |
431 | -locales will exist, except for one standard locale called @samp{C} or | |
432 | -@samp{POSIX}. Later we will describe how to construct locales. | |
433 | -@comment (@pxref{Building Locale Files}). | |
434 | +using, and so do their names, except that the standard locale called | |
435 | +@samp{C} or @samp{POSIX} always exist. @xref{Locale Names}. | |
436 | + | |
437 | +In order to force the system to always use the default locale, the | |
438 | +user can set the @code{LC_ALL} environment variable to @samp{C}. | |
439 | ||
440 | @cindex combining locales | |
441 | -A user also has the option of specifying different locales for different | |
442 | -purposes---in effect, choosing a mixture of multiple locales. | |
443 | +A user also has the option of specifying different locales for | |
444 | +different purposes---in effect, choosing a mixture of multiple | |
445 | +locales. @xref{Locale Categories}. | |
446 | ||
447 | For example, the user might specify the locale @samp{espana-castellano} | |
448 | for most purposes, but specify the locale @samp{usa-english} for | |
449 | @@ -120,7 +123,7 @@ which locales apply. However, the user | |
450 | for a particular subset of those purposes. | |
451 | ||
452 | @node Locale Categories, Setting the Locale, Choosing Locale, Locales | |
453 | -@section Categories of Activities that Locales Affect | |
454 | +@section Locale Categories | |
455 | @cindex categories for locales | |
456 | @cindex locale categories | |
457 | ||
458 | @@ -128,7 +131,11 @@ The purposes that locales serve are grou | |
459 | that a user or a program can choose the locale for each category | |
460 | independently. Here is a table of categories; each name is both an | |
461 | environment variable that a user can set, and a macro name that you can | |
462 | -use as an argument to @code{setlocale}. | |
463 | +use as the first argument to @code{setlocale}. | |
464 | + | |
465 | +The contents of the environment variable (or the string in the second | |
466 | +argument to @code{setlocale}) has to be a valid locale name. | |
467 | +@xref{Locale Names}. | |
468 | ||
469 | @vtable @code | |
470 | @comment locale.h | |
471 | @@ -172,7 +179,7 @@ for affirmative and negative responses. | |
472 | @comment locale.h | |
473 | @comment ISO | |
474 | @item LC_ALL | |
475 | -This is not an environment variable; it is only a macro that you can use | |
476 | +This is not a category; it is only a macro that you can use | |
477 | with @code{setlocale} to set a single locale for all purposes. Setting | |
478 | this environment variable overwrites all selections by the other | |
479 | @code{LC_*} variables or @code{LANG}. | |
480 | @@ -225,13 +232,7 @@ The symbols in this section are defined | |
481 | @comment ISO | |
482 | @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale}) | |
483 | The function @code{setlocale} sets the current locale for category | |
484 | -@var{category} to @var{locale}. A list of all the locales the system | |
485 | -provides can be created by running | |
486 | - | |
487 | -@pindex locale | |
488 | -@smallexample | |
489 | - locale -a | |
490 | -@end smallexample | |
491 | +@var{category} to @var{locale}. | |
492 | ||
493 | If @var{category} is @code{LC_ALL}, this specifies the locale for all | |
494 | purposes. The other possible values of @var{category} specify an | |
495 | @@ -256,10 +257,9 @@ is passed in as @var{locale} parameter. | |
496 | ||
497 | When you read the current locale for category @code{LC_ALL}, the value | |
498 | encodes the entire combination of selected locales for all categories. | |
499 | -In this case, the value is not just a single locale name. In fact, we | |
500 | -don't make any promises about what it looks like. But if you specify | |
501 | -the same ``locale name'' with @code{LC_ALL} in a subsequent call to | |
502 | -@code{setlocale}, it restores the same combination of locale selections. | |
503 | +If you specify the same ``locale name'' with @code{LC_ALL} in a | |
504 | +subsequent call to @code{setlocale}, it restores the same combination | |
505 | +of locale selections. | |
506 | ||
507 | To be sure you can use the returned string encoding the currently selected | |
508 | locale at a later time, you must make a copy of the string. It is not | |
509 | @@ -275,6 +275,11 @@ for @var{category}. | |
510 | If a nonempty string is given for @var{locale}, then the locale of that | |
511 | name is used if possible. | |
512 | ||
513 | +The effective locale name (either the second argument to | |
514 | +@code{setlocale}, or if the argument is an empty string, the name | |
515 | +obtained from the process environment) must be valid locale name. | |
516 | +@xref{Locale Names}. | |
517 | + | |
518 | If you specify an invalid locale name, @code{setlocale} returns a null | |
519 | pointer and leaves the current locale unchanged. | |
520 | @end deftypefun | |
521 | @@ -328,7 +323,7 @@ locale categories, and future versions o | |
522 | portability, assume that any symbol beginning with @samp{LC_} might be | |
523 | defined in @file{locale.h}. | |
524 | ||
525 | -@node Standard Locales, Locale Information, Setting the Locale, Locales | |
526 | +@node Standard Locales, Locale Names, Setting the Locale, Locales | |
527 | @section Standard Locales | |
528 | ||
529 | The only locale names you can count on finding on all operating systems | |
530 | @@ -362,7 +357,94 @@ with the environment, rather than trying | |
531 | locale explicitly by name. Remember, different machines might have | |
532 | different sets of locales installed. | |
533 | ||
534 | -@node Locale Information, Formatting Numbers, Standard Locales, Locales | |
535 | +@node Locale Names, Locale Information, Standard Locales, Locales | |
536 | +@section Locale Names | |
537 | + | |
538 | +The following command prints a list of locales supported by the | |
539 | +system: | |
540 | + | |
541 | +@pindex locale | |
542 | +@smallexample | |
543 | + locale -a | |
544 | +@end smallexample | |
545 | + | |
546 | +@strong{Portability Note:} With the notable exception of the standard | |
547 | +locale names @samp{C} and @samp{POSIX}, locale names are | |
548 | +system-specific. | |
549 | + | |
550 | +Most locale names follow XPG syntax and consist of up to four parts: | |
551 | + | |
552 | +@smallexample | |
553 | +@var{language}[_@var{territory}[.@var{codeset}]][@@@var{modifier}] | |
554 | +@end smallexample | |
555 | + | |
556 | +Beside the first part, all of them are allowed to be missing. If the | |
557 | +full specified locale is not found, less specific ones are looked for. | |
558 | +The various parts will be stripped off, in the following order: | |
559 | + | |
560 | +@enumerate | |
561 | +@item | |
562 | +codeset | |
563 | +@item | |
564 | +normalized codeset | |
565 | +@item | |
566 | +territory | |
567 | +@item | |
568 | +modifier | |
569 | +@end enumerate | |
570 | + | |
571 | +For example, the locale name @samp{de_AT.iso885915@@euro} denotes a | |
572 | +German-language locale for use in Austria, using the ISO-8859-15 | |
573 | +(Latin-9) character set, and with the Euro as the currency symbol. | |
574 | + | |
575 | +In addition to locale names which follow XPG syntax, systems may | |
576 | +provide aliases such as @samp{german}. Both categories of names must | |
577 | +not contain the slash character @samp{/}. | |
578 | + | |
579 | +If the locale name starts with a slash @samp{/}, it is treated as a | |
580 | +path relative to the configured locale directories; see @code{LOCPATH} | |
581 | +below. The specified path must not contain a component @samp{..}, or | |
582 | +the name is invalid, and @code{setlocale} will fail. | |
583 | + | |
584 | +@strong{Portability Note:} POSIX suggests that if a locale name starts | |
585 | +with a slash @samp{/}, it is resolved as an absolute path. However, | |
586 | +the GNU C Library treats it as a relative path under the directories listed | |
587 | +in @code{LOCPATH} (or the default locale directory if @code{LOCPATH} | |
588 | +is unset). | |
589 | + | |
590 | +Locale names which are longer than an implementation-defined limit are | |
591 | +invalid and cause @code{setlocale} to fail. | |
592 | + | |
593 | +As a special case, locale names used with @code{LC_ALL} can combine | |
594 | +several locales, reflecting different locale settings for different | |
595 | +categories. For example, you might want to use a U.S. locale with ISO | |
596 | +A4 paper format, so you set @code{LANG} to @samp{en_US.UTF-8}, and | |
597 | +@code{LC_PAPER} to @samp{de_DE.UTF-8}. In this case, the | |
598 | +@code{LC_ALL}-style combined locale name is | |
599 | + | |
600 | +@smallexample | |
601 | +LC_CTYPE=en_US.UTF-8;LC_TIME=en_US.UTF-8;LC_PAPER=de_DE.UTF-8;@dots{} | |
602 | +@end smallexample | |
603 | + | |
604 | +followed by other category settings not shown here. | |
605 | + | |
606 | +@vindex LOCPATH | |
607 | +The path used for finding locale data can be set using the | |
608 | +@code{LOCPATH} environment variable. This variable lists the | |
609 | +directories in which to search for locale definitions, separated by a | |
610 | +colon @samp{:}. | |
611 | + | |
612 | +The default path for finding locale data is system specific. A typical | |
613 | +value for the @code{LOCPATH} default is: | |
614 | + | |
615 | +@smallexample | |
616 | +/usr/share/locale | |
617 | +@end smallexample | |
618 | + | |
619 | +The value of @code{LOCPATH} is ignored by privileged programs for | |
620 | +security reasons, and only the default directory is used. | |
621 | + | |
622 | +@node Locale Information, Formatting Numbers, Locale Names, Locales | |
623 | @section Accessing Locale Information | |
624 | ||
625 | There are several ways to access locale information. The simplest |