Print this page
Add locale.h ref
Ensured various XPG7 stuff are declared properly in sys/stat.h (and cleanup)
New documentation for wcslen, wcsnlen, wcscasecmp (and friends), wcsdup.
Various other tweaks and markup improvements.
Note standards conformance for newlocale, convert to mdocml.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/newlocale.3c
+++ new/usr/src/man/man3c/newlocale.3c
1 -'\" te
2 1 .\"
3 2 .\" This file and its contents are supplied under the terms of the
4 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 4 .\" You may only use this file in accordance with the terms of version
6 5 .\" 1.0 of the CDDL.
7 6 .\"
8 7 .\" A full copy of the text of the CDDL should have accompanied this
9 8 .\" source. A copy of the CDDL is also available via the Internet at
10 9 .\" http://www.illumos.org/license/CDDL.
11 10 .\"
12 11 .\"
13 12 .\" Copyright (c) 2014 Joyent, Inc. All rights reserved.
14 13 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
15 14 .\"
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)
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
39 45 and functions that take arguments of type
40 -.BR locale_t .
41 -.LP
42 -The function
43 -.B newlocale()
46 +.Vt locale_t .
47 +.Lp
48 +The
49 +.Fn newlocale
50 +function
44 51 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
52 +existing locale object; the new locale object will be a replacement for the
46 53 modified locale object. To create a new locale, the argument
47 -.I base
54 +.Fa base
48 55 should be passed the special argument
49 -.RB ( locale_t )0.
56 +.Po Vt locale_t Pc 0.
50 57 This will use a copy of the current global locale as a starting point. To modify
51 58 an existing locale object, it should be passed in as the argument
52 -.IR base .
59 +.Fa base .
53 60 The new locale object is constructed by taking the categories specified in
54 -.I category_mask
61 +.Fa category_mask
55 62 from the locale specified by the string
56 -.IR locale ,
63 +.Fa locale ,
57 64 and filling in the remaining categories from the locale
58 -.IR base .
65 +.Fa base .
59 66 When
60 -.B newlocale()
67 +.Fn newlocale
61 68 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
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
66 75 following three locales may always be passed in as the string
67 -.IR locale :
68 -.TP
69 -"C"
76 +.Fa locale :
77 +.Bl -tag -offset indent -width Dq
78 +.It \\"C\\"
70 79 Specifies the traditional UNIX system behavior.
71 -.TP
72 -"POSIX"
80 +.It \\"POSIX\\"
73 81 An alternate name fo the locale "C".
74 -.TP
75 -""
82 +.It \\"\\"
76 83 Indicates that the locale should be processed based in the values in the
77 84 environment. See
78 -.BR setlocale (3C)
85 +.Xr setlocale 3C
79 86 and
80 -.BR environ (5)
87 +.Xr environ 5
81 88 for more information.
82 -.LP
89 +.El
90 +.Lp
83 91 The value of
84 -.I category_mask
92 +.Fa category_mask
85 93 is a bitwise-inclusive or of the following macros which correspond to categories
86 94 as defined in
87 -.BR locale (5)
95 +.Xr locale 5
88 96 and
89 -.BR environ (5):
90 -.TP
91 -.B LC_CTYPE_MASK
97 +.Xr environ 5 :
98 +.Bl -tag -offset indent -width Dv
99 +.It Dv LC_CTYPE_MASK
92 100 Character classification and case conversion.
93 -.TP
94 -.B LC_NUMERIC_MASK
101 +.It Dv LC_NUMERIC_MASK
95 102 Numeric formatting.
96 -.TP
97 -.B LC_TIME_MASK
103 +.It Dv LC_TIME_MASK
98 104 Date and time formatting.
99 -.TP
100 -.B LC_COLLATE_MASK
105 +.It Dv LC_COLLATE_MASK
101 106 Collation order.
102 -.TP
103 -.B LC_MONETARY_MASK
107 +.It Dv LC_MONETARY_MASK
104 108 Monetary formatting.
105 -.TP
106 -.B LC_MESSAGES_MASK
109 +.It Dv LC_MESSAGES_MASK
107 110 Formats of informative and diagnostic messages and interactive responses.
108 -.TP
109 -.B LC_ALL_MASK
111 +.It Dv LC_ALL_MASK
110 112 Mask of all categories.
111 -.LP
112 -The function
113 -.B duplocale()
114 -duplicates the locale object specified by
115 -.IR loc .
113 +.El
114 +.Lp
115 +The
116 +.Fn duplocale
117 +function duplicates the locale object specified by
118 +.Fa loc .
116 119 If the locale object passed is
117 -.BR LC_GLOBAL_LOCALE ,
118 -.B duplocale()
120 +.Dv LC_GLOBAL_LOCALE ,
121 +.Fn duplocale
119 122 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 .
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 .
126 129 Programs must not call
127 -.B freelocale()
130 +.Fn freelocale
128 131 on
129 -.BR LC_GLOBAL_LOCALE .
130 -.SH RETURN VALUES
131 -.LP
132 +.Dv LC_GLOBAL_LOCALE .
133 +.Sh RETURN VALUES
132 134 On success, the functions
133 -.B newlocale()
135 +.Fn newlocale
134 136 and
135 -.B duplocale()
137 +.Fn duplocale
136 138 return a new locale object that can be used with functions that take a
137 -.BR locale_t .
139 +.Vt locale_t .
138 140 Locale objects created this way should be freed with
139 -.BR freelocale() .
141 +.Fn freelocale .
140 142 On error, the functions
141 -.B newlocale()
143 +.Fn newlocale
142 144 and
143 -.B duplocale()
145 +.Fn duplocale
144 146 return
145 -.BR (locale_t) 0
147 +.Po Vt locale_t Pc 0
146 148 and
147 -.B errno
149 +.Va errno
148 150 is set to indicate the error. The
149 -.B freelocale()
151 +.Fn freelocale
150 152 function does not set
151 -.B errno.
152 -.SH ERRORS
153 -.LP
153 +.Va errno .
154 +.Sh ERRORS
154 155 The
155 -.B newlocale()
156 +.Fn newlocale
156 157 and
157 -.B duplocale()
158 +.Fn duplocale
158 159 functions will fail if:
159 -.TP
160 -.B ENOMEM
160 +.Bl -tag -width Er
161 +.It Er ENOMEM
161 162 Insufficient memory was available to create the locale object or to load the
162 163 requested locale data.
163 -.LP
164 +.El
165 +.Lp
164 166 The
165 -.B newlocale()
167 +.Fn newlocale
166 168 function will fail if:
167 -.TP
168 -.B EINVAL
169 +.Bl -tag -width Er
170 +.It Er EINVAL
169 171 An unknown bit is specified in
170 -.IR category_mask .
171 -.TP
172 -.B ENOENT
172 +.Fa category_mask .
173 +.It Er ENOENT
173 174 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)
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 .
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX