]>
Commit | Line | Data |
---|---|---|
9849e584 MK |
1 | '\" t -*- coding: UTF-8 -*- |
2 | .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
8660ef9f | 26 | .TH NEWLOCALE 3 2014-05-28 "Linux" "Linux Programmer's Manual" |
9849e584 MK |
27 | .SH NAME |
28 | newlocale, freelocale \- create, modify, and free a locale object | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <locale.h> | |
f90f031e | 32 | .PP |
9849e584 MK |
33 | .BI "locale_t newlocale(int " category_mask ", const char *" locale ", |
34 | .BI " locale_t " base ); | |
f90f031e | 35 | .PP |
9849e584 MK |
36 | .BI "void freelocale(locale_t " locobj ); |
37 | .fi | |
68e4db0a | 38 | .PP |
9849e584 MK |
39 | .in -4n |
40 | Feature Test Macro Requirements for glibc (see | |
41 | .BR feature_test_macros (7)): | |
42 | .in | |
68e4db0a | 43 | .PP |
9849e584 MK |
44 | .BR newlocale (), |
45 | .BR freelocale (): | |
46 | .PD 0 | |
47 | .RS 4 | |
48 | .TP | |
49 | Since glibc 2.10: | |
50 | _XOPEN_SOURCE\ >=\ 700 | |
51 | .TP | |
52 | Before glibc 2.10: | |
53 | _GNU_SOURCE | |
54 | .RE | |
55 | .PD | |
56 | .SH DESCRIPTION | |
57 | The | |
58 | .BR newlocale () | |
59 | function creates a new locale object, or modifies an existing object, | |
60 | returning a reference to the new or modified object as the function result. | |
61 | Whether the call creates a new object or modifies an existing object | |
62 | is determined by the value of | |
63 | .IR base : | |
64 | .IP * 3 | |
65 | If | |
66 | .I base | |
67 | is | |
68 | .IR "(locale_t)\ 0" , | |
69 | a new object is created. | |
70 | .IP * | |
89851a00 | 71 | If |
9849e584 MK |
72 | .I base |
73 | refers to valid existing locale object | |
74 | (i.e., an object returned by a previous call to | |
75 | .BR newlocale () | |
76 | or | |
77 | .BR duplocale (3)), | |
78 | then that object is modified by the call. | |
79 | If the call is successful, the contents of | |
80 | .I base | |
81 | are unspecified (in particular, the object referred to by | |
82 | .I base | |
83 | may be freed, and a new object created). | |
84 | Therefore, the caller should ensure that it stops using | |
85 | .I base | |
86 | before the call to | |
87 | .BR newlocale (), | |
88 | and should subsequently refer to the modified object via the | |
89 | reference returned as the function result. | |
90 | If the call fails, the contents of | |
91 | .I base | |
92 | remain valid and unchanged. | |
93 | .PP | |
900b13de MK |
94 | If |
95 | .I base | |
96 | is the special locale object | |
97 | .BR LC_GLOBAL_LOCALE | |
98 | (see | |
99 | .BR duplocale (3)), | |
100 | or is not | |
101 | .IR "(locale_t)\ 0" | |
102 | and is not a valid locale object handle, | |
103 | the behavior is undefined. | |
847e0d88 | 104 | .PP |
9849e584 MK |
105 | The |
106 | .I category_mask | |
107 | argument is a bit mask that specifies the locale categories | |
108 | that are to be set in a newly created locale object | |
109 | or modified in an existing object. | |
110 | The mask is constructed by a bitwise OR of the constants | |
4de4d201 | 111 | .BR LC_ADDRESS_MASK , |
9849e584 MK |
112 | .BR LC_CTYPE_MASK , |
113 | .BR LC_COLLATE_MASK , | |
4de4d201 MM |
114 | .BR LC_IDENTIFICATION_MASK , |
115 | .BR LC_MEASUREMENT_MASK , | |
9849e584 MK |
116 | .BR LC_MESSAGES_MASK , |
117 | .BR LC_MONETARY_MASK , | |
118 | .BR LC_NUMERIC_MASK , | |
4de4d201 MM |
119 | .BR LC_NAME_MASK , |
120 | .BR LC_PAPER_MASK , | |
121 | .BR LC_TELEPHONE_MASK , | |
9849e584 MK |
122 | and |
123 | .BR LC_TIME_MASK . | |
99a2c329 MK |
124 | Alternatively, the mask can be specified as |
125 | .BR LC_ALL_MASK , | |
126 | which is equivalent to ORing all of the preceding constants. | |
847e0d88 | 127 | .PP |
9849e584 MK |
128 | For each category specified in |
129 | .IR category_mask , | |
130 | the locale data from | |
131 | .I locale | |
132 | will be used in the object returned by | |
133 | .BR newlocale (). | |
134 | If a new locale object is being created, | |
135 | data for all categories not specified in | |
136 | .IR category_mask | |
137 | is taken from the default ("POSIX") locale. | |
847e0d88 | 138 | .PP |
9849e584 MK |
139 | The following preset values of |
140 | .I locale | |
141 | are defined for all categories that can be specified in | |
142 | .IR category_mask : | |
143 | .TP | |
144 | "POSIX" | |
145 | A minimal locale environment for C language programs. | |
146 | .TP | |
147 | "C" | |
148 | Equivalent to "POSIX". | |
149 | .TP | |
150 | "" | |
151 | An implementation-defined native environment | |
152 | corresponding to the values of the | |
153 | .BR LC_* | |
154 | and | |
155 | .B LANG | |
156 | environment variables (see | |
157 | .BR locale (7)). | |
9849e584 MK |
158 | .SS freelocale() |
159 | The | |
160 | .BR freelocale () | |
161 | function deallocates the resources associated with | |
162 | .IR locobj , | |
163 | a locale object previously returned by a call to | |
164 | .BR newlocale () | |
165 | or | |
166 | .BR duplocale (3). | |
167 | If | |
168 | .I locobj | |
169 | is | |
170 | .BR LC_GLOBAL_LOCALE | |
171 | or is not valid locale object handle, the results are undefined. | |
847e0d88 | 172 | .PP |
9849e584 MK |
173 | Once a locale object has been freed, |
174 | the program should make no further use of it. | |
175 | .SH RETURN VALUE | |
176 | On success, | |
177 | .BR newlocale () | |
178 | returns a handle that can be used in calls to | |
179 | .BR duplocale (3), | |
180 | .BR freelocale (), | |
181 | and other functions that take a | |
182 | .I locale_t | |
183 | argument. | |
184 | On error, | |
185 | .BR newlocale () | |
186 | returns | |
187 | .IR "(locale_t)\ 0", | |
188 | and sets | |
189 | .I errno | |
190 | to indicate the cause of the error. | |
191 | .SH ERRORS | |
192 | .TP | |
193 | .B EINVAL | |
194 | One or more bits in | |
195 | .I category_mask | |
900b13de | 196 | do not correspond to a valid locale category. |
9849e584 MK |
197 | .TP |
198 | .B EINVAL | |
199 | .I locale | |
200 | is NULL. | |
201 | .TP | |
202 | .B ENOENT | |
203 | .I locale | |
204 | is not a string pointer referring to a valid locale. | |
205 | .TP | |
206 | .B ENOMEM | |
207 | Insufficient memory to create a locale object. | |
208 | .SH VERSIONS | |
209 | The | |
210 | .BR newlocale () | |
211 | and | |
212 | .BR freelocale () | |
213 | functions first appeared in version 2.3 of the GNU C library. | |
214 | .SH CONFORMING TO | |
215 | POSIX.1-2008. | |
216 | .SH NOTES | |
217 | Each locale object created by | |
218 | .BR newlocale () | |
219 | should be deallocated using | |
09c8844a | 220 | .BR freelocale (). |
9849e584 MK |
221 | .SH EXAMPLE |
222 | The program below takes up to two command-line arguments, | |
223 | which each identify locales. | |
224 | The first argument is required, and is used to set the | |
225 | .B LC_NUMERIC | |
226 | category in a locale object created using | |
227 | .BR newlocale (). | |
228 | The second command-line argument is optional; | |
229 | if it is present, it is used to set the | |
230 | .B LC_TIME | |
231 | category of the locale object. | |
847e0d88 | 232 | .PP |
9849e584 MK |
233 | Having created and initialized the locale object, |
234 | the program then applies it using | |
900b13de | 235 | .BR uselocale (3), |
9849e584 MK |
236 | and then tests the effect of the locale changes by: |
237 | .IP 1. 3 | |
238 | Displaying a floating-point number with a fractional part. | |
239 | This output will be affected by the | |
240 | .B LC_NUMERIC | |
241 | setting. | |
242 | In many European-language locales, | |
243 | the fractional part of the number is separated from the integer part | |
244 | using a comma, rather than a period. | |
245 | .IP 2. | |
246 | Displaying the date. | |
247 | The format and language of the output will be affected by the | |
248 | .B LC_TIME | |
249 | setting. | |
9849e584 MK |
250 | .PP |
251 | The following shell sessions show some example runs of this program. | |
847e0d88 | 252 | .PP |
9849e584 MK |
253 | Set the |
254 | .B LC_NUMERIC | |
255 | category to | |
256 | .IR fr_FR | |
257 | (French): | |
258 | .in +4n | |
259 | .nf | |
260 | ||
261 | $ \fB./a.out fr_FR\fP | |
262 | 123456,789 | |
263 | Fri Mar 7 00:25:08 2014 | |
264 | .fi | |
265 | .in | |
847e0d88 | 266 | .PP |
9849e584 MK |
267 | Set the |
268 | .B LC_NUMERIC | |
269 | category to | |
270 | .IR fr_FR | |
271 | (French), | |
272 | and the | |
273 | .B LC_TIME | |
274 | category to | |
275 | .IR it_IT | |
276 | (Italian): | |
277 | .in +4n | |
278 | .nf | |
279 | ||
280 | $ \fB./a.out fr_FR it_IT\fP | |
281 | 123456,789 | |
282 | ven 07 mar 2014 00:26:01 CET | |
283 | .fi | |
284 | .in | |
847e0d88 | 285 | .PP |
9849e584 MK |
286 | Specify the |
287 | .B LC_TIME | |
288 | setting as an empty string, | |
289 | which causes the value to be taken from environment variable settings | |
290 | (which, here, specify | |
291 | .IR mi_NZ , | |
292 | New Zealand Māori): | |
293 | .in +4n | |
294 | .nf | |
295 | ||
296 | $ LC_ALL=mi_NZ ./a.out fr_FR "" | |
297 | 123456,789 | |
298 | Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET | |
299 | .fi | |
9849e584 MK |
300 | .SS Program source |
301 | .nf | |
302 | #define _XOPEN_SOURCE 700 | |
303 | #include <stdio.h> | |
304 | #include <stdlib.h> | |
305 | #include <locale.h> | |
306 | #include <time.h> | |
307 | ||
308 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ | |
309 | } while (0) | |
310 | ||
311 | int | |
312 | main(int argc, char *argv[]) | |
313 | { | |
900b13de | 314 | char buf[100]; |
9849e584 MK |
315 | time_t t; |
316 | size_t s; | |
317 | struct tm *tm; | |
318 | locale_t loc, nloc; | |
319 | ||
320 | if (argc < 2) { | |
321 | fprintf(stderr, "Usage: %s locale1 [locale2]\\n", argv[0]); | |
322 | exit(EXIT_FAILURE); | |
323 | } | |
324 | ||
325 | /* Create a new locale object, taking the LC_NUMERIC settings | |
326 | from the locale specified in argv[1] */ | |
327 | ||
328 | loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0); | |
329 | if (loc == (locale_t) 0) | |
330 | errExit("newlocale"); | |
331 | ||
332 | /* If a second command\-line argument was specified, modify the | |
333 | locale object to take the LC_TIME settings from the locale | |
900b13de MK |
334 | specified in argv[2]. We assign the result of this newlocale() |
335 | call to 'nloc' rather than 'loc', since in some cases, we might | |
336 | want to preserve 'loc' if this call fails. */ | |
9849e584 MK |
337 | |
338 | if (argc > 2) { | |
339 | nloc = newlocale(LC_TIME_MASK, argv[2], loc); | |
900b13de | 340 | if (nloc == (locale_t) 0) |
9849e584 MK |
341 | errExit("newlocale"); |
342 | loc = nloc; | |
343 | } | |
344 | ||
345 | /* Apply the newly created locale to this thread */ | |
346 | ||
347 | uselocale(loc); | |
348 | ||
349 | /* Test effect of LC_NUMERIC */ | |
350 | ||
351 | printf("%8.3f\\n", 123456.789); | |
352 | ||
353 | /* Test effect of LC_TIME */ | |
354 | ||
355 | t = time(NULL); | |
356 | tm = localtime(&t); | |
357 | if (tm == NULL) | |
358 | errExit("time"); | |
359 | ||
900b13de | 360 | s = strftime(buf, sizeof(buf), "%c", tm); |
9849e584 MK |
361 | if (s == 0) |
362 | errExit("strftime"); | |
363 | ||
364 | printf("%s\\n", buf); | |
365 | ||
366 | /* Free the locale object */ | |
367 | ||
368 | freelocale(loc); | |
369 | ||
370 | exit(EXIT_SUCCESS); | |
371 | } | |
372 | .fi | |
373 | .SH SEE ALSO | |
374 | .BR locale (1), | |
375 | .BR duplocale (3), | |
376 | .BR setlocale (3), | |
377 | .BR uselocale (3), | |
378 | .BR locale (5), | |
379 | .BR locale (7) |