Debian Codegraph @

upstream/debian-trixie/man3/newlocale.3

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