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 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
15 .\"
16 .TH NEWLOCALE 3C "Jun 23, 2014"
17 .SH NAME
18 duplocale, freelocale, newlocale \- create, duplicate, and destroy locale objects
19 .SH SYNOPSIS
20 .LP
21 .nf
22 #include <locale.h>
23
24 \fBlocale_t\fR \fBnewlocale\fR(\fBint\fR \fIcategory_mask\fR, \fBconst char *\fR \fIlocale\fR,
25 \fBlocale_t\fR \fIbase\fR);
26 .fi
27 .LP
28 .nf
29 \fBlocale_t\fR \fBduplocale\fR(\fBlocale_t\fR \fIloc\fR);
30 .fi
31 .LP
32 .nf
33 \fBvoid\fR \fBfreelocale\fR(\fBlocale_t\fR \fIloc\fR);
34 .fi
35 .SH DESCRIPTION
36 .LP
37 These functions manipulate locale objects that can be used
38 .BR uselocale (3C)
39 and functions that take arguments of type
40 .BR locale_t .
41 .LP
42 The function
43 .B 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 .TP
69 "C"
70 Specifies the traditional UNIX system behavior.
71 .TP
72 "POSIX"
73 An alternate name fo the locale "C".
74 .TP
75 ""
76 Indicates that the locale should be processed based in the values in the
77 environment. See
78 .BR setlocale (3C)
79 and
80 .BR environ (5)
81 for more information.
82 .LP
83 The value of
84 .I category_mask
85 is a bitwise-inclusive or of the following macros which correspond to categories
86 as defined in
87 .BR locale (5)
88 and
89 .BR environ (5):
90 .TP
91 .B LC_CTYPE_MASK
92 Character classification and case conversion.
93 .TP
94 .B LC_NUMERIC_MASK
95 Numeric formatting.
96 .TP
97 .B LC_TIME_MASK
98 Date and time formatting.
99 .TP
100 .B LC_COLLATE_MASK
101 Collation order.
102 .TP
103 .B LC_MONETARY_MASK
104 Monetary formatting.
105 .TP
106 .B LC_MESSAGES_MASK
107 Formats of informative and diagnostic messages and interactive responses.
108 .TP
109 .B LC_ALL_MASK
110 Mask of all categories.
111 .LP
112 The function
113 .B duplocale()
114 duplicates the locale object specified by
115 .IR loc .
116 If the locale object passed is
117 .BR LC_GLOBAL_LOCALE ,
118 .B duplocale()
119 creates a copy of the current global locale as defined through calls to
120 .BR setlocale (3C).
121 .LP
122 The function
123 .B freelocale()
124 removes and releases all resources associated with the locale object
125 .IR loc .
126 Programs must not call
127 .B freelocale()
128 on
129 .BR LC_GLOBAL_LOCALE .
130 .SH RETURN VALUES
131 .LP
132 On success, the functions
133 .B newlocale()
134 and
135 .B duplocale()
136 return a new locale object that can be used with functions that take a
137 .BR locale_t .
138 Locale objects created this way should be freed with
139 .BR freelocale() .
140 On error, the functions
141 .B newlocale()
142 and
143 .B duplocale()
144 return
145 .BR (locale_t) 0
146 and
147 .B errno
148 is set to indicate the error. The
149 .B freelocale()
150 function does not set
151 .B errno.
152 .SH ERRORS
153 .LP
154 The
155 .B newlocale()
156 and
157 .B duplocale()
158 functions will fail if:
159 .TP
160 .B ENOMEM
161 Insufficient memory was available to create the locale object or to load the
162 requested locale data.
163 .LP
164 The
165 .B newlocale()
166 function will fail if:
167 .TP
168 .B EINVAL
169 An unknown bit is specified in
170 .IR category_mask .
171 .TP
172 .B ENOENT
173 Locale data was not found for a category specified in
174 .SH ATTRIBUTES
175 .TS
176 box;
177 c | c
178 l | l .
179 ATTRIBUTE TYPE ATTRIBUTE VALUE
180 _
181 Interface Stability Standard
182 _
183 MT-Level Safe
184 .TE
185
186 .SH SEE ALSO
187 .BR locale (1),
188 .BR setlocale (3C),
189 .BR uselocale (3C),
190 .BR environ (5),
191 .BR locale (5)
|
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright (c) 2014 Joyent, Inc. All rights reserved.
13 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
14 .\"
15 .Dd "Jul 23, 2014"
16 .Dt NEWLOCALE 3C
17 .Os
18 .Sh NAME
19 .Nm duplocale ,
20 .Nm freelocale ,
21 .Nm newlocale
22 .Nd create, duplicate, and destroy locale objects
23 .Sh SYNOPSIS
24 .In locale.h
25 .
26 .Ft locale_t
27 .Fo newlocale
28 .Fa "int category_mask"
29 .Fa "const char *locale"
30 .Fa "locale_t base"
31 .Fc
32 .
33 .Ft locale_t
34 .Fo duplocale
35 .Fa "locale_t loc"
36 .Fc
37 .
38 .Ft void
39 .Fo freelocale
40 .Fa "locale_t loc"
41 .Fc
42 .Sh DESCRIPTION
43 These functions manipulate locale objects that can be used with
44 .Xr uselocale 3C
45 and functions that take arguments of type
46 .Vt locale_t .
47 .Lp
48 The
49 .Fn newlocale
50 function
51 can be used to create a new locale object. It can also be used to modify an
52 existing locale object; the new locale object will be a replacement for the
53 modified locale object. To create a new locale, the argument
54 .Fa base
55 should be passed the special argument
56 .Po Vt locale_t Pc 0.
57 This will use a copy of the current global locale as a starting point. To modify
58 an existing locale object, it should be passed in as the argument
59 .Fa base .
60 The new locale object is constructed by taking the categories specified in
61 .Fa category_mask
62 from the locale specified by the string
63 .Fa locale ,
64 and filling in the remaining categories from the locale
65 .Fa base .
66 When
67 .Fn newlocale
68 returns, callers must no longer use
69 .Fa base .
70 They should assume that
71 .Fn freelocale
72 has been called on it.
73 .Lp
74 In addition to locales defined on the system, the
75 following three locales may always be passed in as the string
76 .Fa locale :
77 .Bl -tag -offset indent -width Dq
78 .It \\"C\\"
79 Specifies the traditional UNIX system behavior.
80 .It \\"POSIX\\"
81 An alternate name fo the locale "C".
82 .It \\"\\"
83 Indicates that the locale should be processed based in the values in the
84 environment. See
85 .Xr setlocale 3C
86 and
87 .Xr environ 5
88 for more information.
89 .El
90 .Lp
91 The value of
92 .Fa category_mask
93 is a bitwise-inclusive or of the following macros which correspond to categories
94 as defined in
95 .Xr locale 5
96 and
97 .Xr environ 5 :
98 .Bl -tag -offset indent -width Dv
99 .It Dv LC_CTYPE_MASK
100 Character classification and case conversion.
101 .It Dv LC_NUMERIC_MASK
102 Numeric formatting.
103 .It Dv LC_TIME_MASK
104 Date and time formatting.
105 .It Dv LC_COLLATE_MASK
106 Collation order.
107 .It Dv LC_MONETARY_MASK
108 Monetary formatting.
109 .It Dv LC_MESSAGES_MASK
110 Formats of informative and diagnostic messages and interactive responses.
111 .It Dv LC_ALL_MASK
112 Mask of all categories.
113 .El
114 .Lp
115 The
116 .Fn duplocale
117 function duplicates the locale object specified by
118 .Fa loc .
119 If the locale object passed is
120 .Dv LC_GLOBAL_LOCALE ,
121 .Fn duplocale
122 creates a copy of the current global locale as defined through calls to
123 .Xr setlocale 3C .
124 .Lp
125 The
126 .Fn freelocale
127 function removes and releases all resources associated with the locale object
128 .Fa loc .
129 Programs must not call
130 .Fn freelocale
131 on
132 .Dv LC_GLOBAL_LOCALE .
133 .Sh RETURN VALUES
134 On success, the functions
135 .Fn newlocale
136 and
137 .Fn duplocale
138 return a new locale object that can be used with functions that take a
139 .Vt locale_t .
140 Locale objects created this way should be freed with
141 .Fn freelocale .
142 On error, the functions
143 .Fn newlocale
144 and
145 .Fn duplocale
146 return
147 .Po Vt locale_t Pc 0
148 and
149 .Va errno
150 is set to indicate the error. The
151 .Fn freelocale
152 function does not set
153 .Va errno .
154 .Sh ERRORS
155 The
156 .Fn newlocale
157 and
158 .Fn duplocale
159 functions will fail if:
160 .Bl -tag -width Er
161 .It Er ENOMEM
162 Insufficient memory was available to create the locale object or to load the
163 requested locale data.
164 .El
165 .Lp
166 The
167 .Fn newlocale
168 function will fail if:
169 .Bl -tag -width Er
170 .It Er EINVAL
171 An unknown bit is specified in
172 .Fa category_mask .
173 .It Er ENOENT
174 Locale data was not found for a category specified in
175 .Fa category_mask .
176 .El
177 .Sh INTERFACE STABILITY
178 .Sy Standard .
179 .Sh MT-LEVEL
180 .Sy MT-Safe .
181 .Sh SEE ALSO
182 .Xr locale 1 ,
183 .Xr setlocale 3C ,
184 .Xr uselocale 3C ,
185 .Xr locale.h 3HEAD ,
186 .Xr environ 5 ,
187 .Xr locale 5
188 .Sh STANDARDS
189 The
190 .Fn newlocale ,
191 .Fn duplocale ,
192 and
193 .Fn freelocale
194 functions were introduced in
195 .St -p1003.1-2008 .
|