1 '\" te
2 .\"
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .\"
12 .\"
13 .\" Copyright (c) 2014 Joyent, Inc. All rights reserved.
14 .\"
15 .TH NEWLOCALE 3C "Jun 11, 2014"
16
17 .SH NAME
18
19 duplocale, freelocale, newlocale \- create, duplicate, and destroy locale objects
20
21 .SH SYNOPSIS
22
23 .LP
24 .nf
25 #include <locale.h>
26
27 .BI "locale_t newlocale(int " category_mask, " const char *" locale,
28 .BI " locale_t " base );
29 .LP
30 .BI "locale_t duplocale(locale_t " loc );
31 .LP
32 .BI "void freelocale(locale_t " loc );
33
34 .SH DESCRIPTION
35 .LP
36 These functions manipulate locale objects that can be used
37 .BR uselocale (3C)
38 and functions that take arguments of type
39 .BR locale_t .
40
41 .LP
42 The function
43 .I newlocale
44 can be used to create a new locale object. It can also be used to modify an
45 existing locale object, the new locale object will be a replacement for the
46 modified locale object. To create a new locale, the argument
47 .I base
48 should be passed the special argument
49 .RB ( locale_t )0.
50 This will use a copy of the current global locale as a starting point. To modify
51 an existing locale object, it should be passed in as the argument
52 .IR base .
53 The new locale object is constructed by taking the categories specified in
54 .I category_mask
55 from the locale specified by the string
56 .IR locale ,
57 and filling in the remaining categories from the locale
58 .IR base .
59 When
60 .B newlocale
61 returns, callers must no longer use
62 .IR base
63 and assume that
64 .BR freelocale (3C)
65 has been called on it. In addition to locales defined on the system, the
66 following three locales may always be passed in as the string
67 .IR locale :
68
69 .sp
70 .ne 2
71 .na
72 "C"
73 .ad
74 .sp .6
75 .RS 4n
76 Specifies the traditional UNIX system behavior.
77 .RE
78
79 .sp
80 .ne 2
81 .na
82 "POSIX"
83 .ad
84 .sp .6
85 .RS 4n
86 An alternate name fo the locale "C".
87 .RE
88
89 .sp
90 .ne 2
91 .na
92 ""
93 .ad
94 .sp .6
95 .RS 4n
96 Indicates that the locale should be processed based in the values in the
97 environment. See
98 .BR setlocale "(3C) and " environ (5)
99 for more information.
100 .RE
101
102
103
104 .LP
105 The value of
106 .I category_mask
107 is a bitwise-inclusive or of the following macros which correspond to categories
108 as defined in
109 .BR locale "(5) and " environ" (5):
110
111 .sp
112 .ne 2
113 .na
114 LC_CTYPE_MASK
115 .ad
116 .sp .6
117 .RS 4n
118 Character classification and case conversion.
119 .RE
120
121 .sp
122 .ne 2
123 .na
124 LC_NUMERIC_MASK
125 .ad
126 .sp .6
127 .RS 4n
128 Numeric formatting.
129 .RE
130
131 .sp
132 .ne 2
133 .na
134 LC_TIME_MASK
135 .ad
136 .sp .6
137 .RS 4n
138 Date and time formatting.
139 .RE
140
141 .sp
142 .ne 2
143 .na
144 LC_COLLATE_MASK
145 .ad
146 .sp .6
147 .RS 4n
148 Collation order.
149 .RE
150
151 .sp
152 .ne 2
153 .na
154 LC_MONETARY_MASK
155 .ad
156 .sp .6
157 .RS 4n
158 Monetary formating.
159 .RE
160
161 .sp
162 .ne 2
163 .na
164 LC_MESSAGES_MASK
165 .ad
166 .sp .6
167 .RS 4n
168 Formats of informative and diagnostic messages and interactive responses.
169 .RE
170
171 .sp
172 .ne 2
173 .na
174 LC_ALL_MASK
175 .ad
176 .sp .6
177 .RS 4n
178 Instructs that all the categories defined above, be used.
179 .RE
180
181 .LP
182 The function
183 .B duplocale()
184 duplicates the locale object specified by
185 .IR loc .
186 If the locale object passed is
187 .BR LC_GLOBAL_LOCALE ,
188 .B duplocale()
189 creates a copy of the current global locale as defined through calls to
190 .BR setlocale (3C).
191
192 .LP
193 The function
194 .B freelocale()
195 removes and releases all resources associated with the locale object
196 .IR loc .
197 Programs must not call
198 .B freelocale()
199 on
200 .BR LC_GLOBAL_LOCALE .
201
202 .SH RETURN VALUES
203
204 On success, the functions
205 .B newlocale()
206 and
207 .B duplocale()
208 return a new locale object that can be used with functions that take a
209 .BR locale_t .
210 Locale objects created this way should be freed with
211 .BR freelocale() .
212 On error, the functions
213 .B newlocale()
214 and
215 .B duplocale()
216 return
217 .BR (locale_t) 0
218 and
219 .B errno
220 is set to indicate the error. The
221 .B freelocale()
222 function does not set
223 .B errno.
224
225 .SH ERRORS
226 .LP
227 The
228 .B newlocale()
229 and
230 .B duplocale()
231 functions will fail if:
232 .sp
233 .ne 2
234 .na
235 .B ENOMEM
236 .ad
237 .RS 10n
238 Insufficient memory was available to create the locale object or to load the
239 requested locale data.
240 .RE
241
242 .LP
243 The
244 .B newlocale()
245 function will fail if:
246 .sp
247 .ne 2
248 .na
249 .B EINVAL
250 .ad
251 .RS 10n
252 An unknown bit is specified in
253 .IR category_mask .
254 .RE
255 .sp
256 .ne 2
257 .na
258 .B ENOENT
259 .ad
260 .RS 10n
261 Locale data was not found for a category specified in
262 .IR category_mask .
263 .RE
264
265 .SH ATTRIBUTES
266 .sp
267 .TS
268 box;
269 c | c
270 l | l .
271 ATTRIBUTE TYPE ATTRIBUTE VALUE
272 _
273 Interface Stability Standard
274 _
275 MT-Level Safe
276 .TE
277
278 .SH SEE ALSO
279 .BR locale (1),
280 .BR setlocale (3C),
281 .BR uselocale (3C),
282 .BR environ (5),
283 .BR locale (5)