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