Debian Codegraph @

upstream/debian-unstable/man3/newlocale.3

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