1 '\" t -*- coding: UTF-8 -*-
2 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH NEWLOCALE 3 2014-05-28 "Linux" "Linux Programmer's Manual"
28 newlocale, freelocale \- create, modify, and free a locale object
31 .B #include <locale.h>
33 .BI "locale_t newlocale(int " category_mask ", const char *" locale ",
34 .BI " locale_t " base );
36 .BI "void freelocale(locale_t " locobj );
40 Feature Test Macro Requirements for glibc (see
41 .BR feature_test_macros (7)):
50 _XOPEN_SOURCE\ >=\ 700
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
69 a new object is created.
73 refers to valid existing locale object
74 (i.e., an object returned by a previous call to
78 then that object is modified by the call.
79 If the call is successful, the contents of
81 are unspecified (in particular, the object referred to by
83 may be freed, and a new object created).
84 Therefore, the caller should ensure that it stops using
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
92 remain valid and unchanged.
96 is the special locale object
102 and is not a valid locale object handle,
103 the behavior is undefined.
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
111 .BR LC_ADDRESS_MASK ,
113 .BR LC_COLLATE_MASK ,
114 .BR LC_IDENTIFICATION_MASK ,
115 .BR LC_MEASUREMENT_MASK ,
116 .BR LC_MESSAGES_MASK ,
117 .BR LC_MONETARY_MASK ,
118 .BR LC_NUMERIC_MASK ,
121 .BR LC_TELEPHONE_MASK ,
124 Alternatively, the mask can be specified as
126 which is equivalent to ORing all of the preceding constants.
128 For each category specified in
132 will be used in the object returned by
134 If a new locale object is being created,
135 data for all categories not specified in
137 is taken from the default ("POSIX") locale.
139 The following preset values of
141 are defined for all categories that can be specified in
145 A minimal locale environment for C language programs.
148 Equivalent to "POSIX".
151 An implementation-defined native environment
152 corresponding to the values of the
156 environment variables (see
161 function deallocates the resources associated with
163 a locale object previously returned by a call to
171 or is not valid locale object handle, the results are undefined.
173 Once a locale object has been freed,
174 the program should make no further use of it.
178 returns a handle that can be used in calls to
181 and other functions that take a
190 to indicate the cause of the error.
196 do not correspond to a valid locale category.
204 is not a string pointer referring to a valid locale.
207 Insufficient memory to create a locale object.
213 functions first appeared in version 2.3 of the GNU C library.
217 Each locale object created by
219 should be deallocated using
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
226 category in a locale object created using
228 The second command-line argument is optional;
229 if it is present, it is used to set the
231 category of the locale object.
233 Having created and initialized the locale object,
234 the program then applies it using
236 and then tests the effect of the locale changes by:
238 Displaying a floating-point number with a fractional part.
239 This output will be affected by the
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.
247 The format and language of the output will be affected by the
252 The following shell sessions show some example runs of this program.
262 $ \fB./a.out fr_FR\fP
264 Fri Mar 7 00:25:08 2014
281 $ \fB./a.out fr_FR it_IT\fP
283 ven 07 mar 2014 00:26:01 CET
289 setting as an empty string,
290 which causes the value to be taken from environment variable settings
291 (which, here, specify
297 $ LC_ALL=mi_NZ ./a.out fr_FR ""
299 Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET
303 #define _XOPEN_SOURCE 700
309 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
313 main(int argc, char *argv[])
322 fprintf(stderr, "Usage: %s locale1 [locale2]\\n", argv[0]);
326 /* Create a new locale object, taking the LC_NUMERIC settings
327 from the locale specified in argv[1] */
329 loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
330 if (loc == (locale_t) 0)
331 errExit("newlocale");
333 /* If a second command\-line argument was specified, modify the
334 locale object to take the LC_TIME settings from the locale
335 specified in argv[2]. We assign the result of this newlocale()
336 call to 'nloc' rather than 'loc', since in some cases, we might
337 want to preserve 'loc' if this call fails. */
340 nloc = newlocale(LC_TIME_MASK, argv[2], loc);
341 if (nloc == (locale_t) 0)
342 errExit("newlocale");
346 /* Apply the newly created locale to this thread */
350 /* Test effect of LC_NUMERIC */
352 printf("%8.3f\\n", 123456.789);
354 /* Test effect of LC_TIME */
361 s = strftime(buf, sizeof(buf), "%c", tm);
365 printf("%s\\n", buf);
367 /* Free the locale object */