1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH NEWLOCALE 3 2021-03-22 "Linux man-pages (unreleased)"
7 newlocale, freelocale \- create, modify, and free a locale object
10 .RI ( libc ", " \-lc )
13 .B #include <locale.h>
15 .BI "locale_t newlocale(int " category_mask ", const char *" locale ,
16 .BI " locale_t " base );
17 .BI "void freelocale(locale_t " locobj );
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
36 function creates a new locale object, or modifies an existing object,
37 returning a reference to the new or modified object as the function result.
38 Whether the call creates a new object or modifies an existing object
39 is determined by the value of
46 a new object is created.
50 refers to valid existing locale object
51 (i.e., an object returned by a previous call to
55 then that object is modified by the call.
56 If the call is successful, the contents of
58 are unspecified (in particular, the object referred to by
60 may be freed, and a new object created).
61 Therefore, the caller should ensure that it stops using
65 and should subsequently refer to the modified object via the
66 reference returned as the function result.
67 If the call fails, the contents of
69 remain valid and unchanged.
73 is the special locale object
79 and is not a valid locale object handle,
80 the behavior is undefined.
84 argument is a bit mask that specifies the locale categories
85 that are to be set in a newly created locale object
86 or modified in an existing object.
87 The mask is constructed by a bitwise OR of the constants
91 .BR LC_IDENTIFICATION_MASK ,
92 .BR LC_MEASUREMENT_MASK ,
93 .BR LC_MESSAGES_MASK ,
94 .BR LC_MONETARY_MASK ,
98 .BR LC_TELEPHONE_MASK ,
101 Alternatively, the mask can be specified as
103 which is equivalent to ORing all of the preceding constants.
105 For each category specified in
109 will be used in the object returned by
111 If a new locale object is being created,
112 data for all categories not specified in
114 is taken from the default ("POSIX") locale.
116 The following preset values of
118 are defined for all categories that can be specified in
122 A minimal locale environment for C language programs.
125 Equivalent to "POSIX".
128 An implementation-defined native environment
129 corresponding to the values of the
133 environment variables (see
138 function deallocates the resources associated with
140 a locale object previously returned by a call to
148 or is not valid locale object handle, the results are undefined.
150 Once a locale object has been freed,
151 the program should make no further use of it.
155 returns a handle that can be used in calls to
158 and other functions that take a
167 to indicate the error.
173 do not correspond to a valid locale category.
181 is not a string pointer referring to a valid locale.
184 Insufficient memory to create a locale object.
190 functions first appeared in version 2.3 of the GNU C library.
194 Each locale object created by
196 should be deallocated using
199 The program below takes up to two command-line arguments,
200 which each identify locales.
201 The first argument is required, and is used to set the
203 category in a locale object created using
205 The second command-line argument is optional;
206 if it is present, it is used to set the
208 category of the locale object.
210 Having created and initialized the locale object,
211 the program then applies it using
213 and then tests the effect of the locale changes by:
215 Displaying a floating-point number with a fractional part.
216 This output will be affected by the
219 In many European-language locales,
220 the fractional part of the number is separated from the integer part
221 using a comma, rather than a period.
224 The format and language of the output will be affected by the
228 The following shell sessions show some example runs of this program.
238 $ \fB./a.out fr_FR\fP
240 Fri Mar 7 00:25:08 2014
257 $ \fB./a.out fr_FR it_IT\fP
259 ven 07 mar 2014 00:26:01 CET
265 setting as an empty string,
266 which causes the value to be taken from environment variable settings
267 (which, here, specify
273 $ LC_ALL=mi_NZ ./a.out fr_FR ""
275 Te Paraire, te 07 o Poutū\-te\-rangi, 2014 00:38:44 CET
280 #define _XOPEN_SOURCE 700
286 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
290 main(int argc, char *argv[])
299 fprintf(stderr, "Usage: %s locale1 [locale2]\en", argv[0]);
303 /* Create a new locale object, taking the LC_NUMERIC settings
304 from the locale specified in argv[1]. */
306 loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
307 if (loc == (locale_t) 0)
308 errExit("newlocale");
310 /* If a second command\-line argument was specified, modify the
311 locale object to take the LC_TIME settings from the locale
312 specified in argv[2]. We assign the result of this newlocale()
313 call to \(aqnloc\(aq rather than \(aqloc\(aq, since in some cases, we might
314 want to preserve \(aqloc\(aq if this call fails. */
317 nloc = newlocale(LC_TIME_MASK, argv[2], loc);
318 if (nloc == (locale_t) 0)
319 errExit("newlocale");
323 /* Apply the newly created locale to this thread. */
327 /* Test effect of LC_NUMERIC. */
329 printf("%8.3f\en", 123456.789);
331 /* Test effect of LC_TIME. */
338 s = strftime(buf, sizeof(buf), "%c", tm);
342 printf("%s\en", buf);
344 /* Free the locale object. */
346 uselocale(LC_GLOBAL_LOCALE); /* So \(aqloc\(aq is no longer in use */