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-03-12 "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
112 .BR LC_COLLATE_MASK ,
113 .BR LC_MESSAGES_MASK ,
114 .BR LC_MONETARY_MASK ,
115 .BR LC_NUMERIC_MASK ,
119 For each category specified in
123 will be used in the object returned by
125 If a new locale object is being created,
126 data for all categories not specified in
128 is taken from the default ("POSIX") locale.
130 The following preset values of
132 are defined for all categories that can be specified in
136 A minimal locale environment for C language programs.
139 Equivalent to "POSIX".
142 An implementation-defined native environment
143 corresponding to the values of the
147 environment variables (see
152 function deallocates the resources associated with
154 a locale object previously returned by a call to
162 or is not valid locale object handle, the results are undefined.
164 Once a locale object has been freed,
165 the program should make no further use of it.
169 returns a handle that can be used in calls to
172 and other functions that take a
181 to indicate the cause of the error.
187 do not correspond to a valid locale category.
195 is not a string pointer referring to a valid locale.
198 Insufficient memory to create a locale object.
204 functions first appeared in version 2.3 of the GNU C library.
208 Each locale object created by
210 should be deallocated using
213 The program below takes up to two command-line arguments,
214 which each identify locales.
215 The first argument is required, and is used to set the
217 category in a locale object created using
219 The second command-line argument is optional;
220 if it is present, it is used to set the
222 category of the locale object.
224 Having created and initialized the locale object,
225 the program then applies it using
227 and then tests the effect of the locale changes by:
229 Displaying a floating-point number with a fractional part.
230 This output will be affected by the
233 In many European-language locales,
234 the fractional part of the number is separated from the integer part
235 using a comma, rather than a period.
238 The format and language of the output will be affected by the
243 The following shell sessions show some example runs of this program.
253 $ \fB./a.out fr_FR\fP
255 Fri Mar 7 00:25:08 2014
272 $ \fB./a.out fr_FR it_IT\fP
274 ven 07 mar 2014 00:26:01 CET
280 setting as an empty string,
281 which causes the value to be taken from environment variable settings
282 (which, here, specify
288 $ LC_ALL=mi_NZ ./a.out fr_FR ""
290 Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET
294 #define _XOPEN_SOURCE 700
300 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
304 main(int argc, char *argv[])
313 fprintf(stderr, "Usage: %s locale1 [locale2]\\n", argv[0]);
317 /* Create a new locale object, taking the LC_NUMERIC settings
318 from the locale specified in argv[1] */
320 loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
321 if (loc == (locale_t) 0)
322 errExit("newlocale");
324 /* If a second command\-line argument was specified, modify the
325 locale object to take the LC_TIME settings from the locale
326 specified in argv[2]. We assign the result of this newlocale()
327 call to 'nloc' rather than 'loc', since in some cases, we might
328 want to preserve 'loc' if this call fails. */
331 nloc = newlocale(LC_TIME_MASK, argv[2], loc);
332 if (nloc == (locale_t) 0)
333 errExit("newlocale");
337 /* Apply the newly created locale to this thread */
341 /* Test effect of LC_NUMERIC */
343 printf("%8.3f\\n", 123456.789);
345 /* Test effect of LC_TIME */
352 s = strftime(buf, sizeof(buf), "%c", tm);
356 printf("%s\\n", buf);
358 /* Free the locale object */
373 This page is part of release 3.67 of the Linux
376 A description of the project,
377 information about reporting bugs,
378 and the latest version of this page,
380 \%http://www.kernel.org/doc/man\-pages/.