]>
Commit | Line | Data |
---|---|---|
3d9156a7 A |
1 | .Dd March 11, 2005 |
2 | .Dt XLOCALE 3 | |
3 | .Os | |
4 | .Sh NAME | |
5 | .Nm xlocale | |
6 | .Nd Extended locale support. | |
7 | .Sh LIBRARY | |
8 | .Lb libc | |
9 | .Sh DESCRIPTION | |
10 | Include | |
11 | .Aq xlocale.h | |
12 | for extended locale support. | |
13 | It can be used alone or with the POSIX locale API in | |
14 | .Aq locale.h . | |
15 | .Pp | |
224c7076 A |
16 | The extended locale, or "xlocale" API consists of five basic routines, |
17 | which are documented separately: | |
3d9156a7 A |
18 | .Xr duplocale 3 , |
19 | .Xr freelocale 3 , | |
20 | .Xr newlocale 3 , | |
21 | .Xr querylocale 3 , | |
22 | and | |
23 | .Xr uselocale 3 . | |
24 | For each of these routines, if a NULL | |
25 | .Vt locale_t | |
26 | is given, the current locale is used. | |
27 | .Pp | |
28 | In addition, | |
29 | .Aq xlocale.h | |
30 | defines a few macros: | |
31 | .Pp | |
32 | .Bl -dash | |
33 | .It | |
34 | LC_GLOBAL_LOCALE - A special | |
35 | .Vt locale_t | |
36 | value that corresponds to the global, process-wide locale. | |
37 | .It | |
224c7076 A |
38 | MB_CUR_MAX - This macro is traditionally defined as an integer |
39 | containing the value of the longest multi-byte string | |
40 | that a single-wide character in the global locale can translate into. | |
41 | With extended locales, this macro is replaced with a function | |
42 | that returns the value of the longest multi-byte string | |
43 | that a single-wide character in the current locale (per-thread or global) | |
3d9156a7 | 44 | can translate into. |
3d9156a7 | 45 | .It |
224c7076 A |
46 | MB_CUR_MAX_L(loc) - This macro is equivalent to MB_CUR_MAX, |
47 | except that it may be passed a specific locale directly. | |
3d9156a7 A |
48 | .El |
49 | .Sh CAVEATS | |
50 | The POSIX | |
51 | .Xr setlocale 3 | |
224c7076 A |
52 | function only affects the global locale, |
53 | so using it when a per-thread locale is in effect | |
54 | will not change locale behavior for that thread. | |
55 | However, it will change behavior for threads | |
56 | with no per-thread locale in effect. | |
b5d655f7 | 57 | #ifdef UNIFDEF_LEGACY_RUNE_APIS |
3d9156a7 A |
58 | .Pp |
59 | The routines defined in | |
60 | .Aq rune.h | |
61 | are deprecated, and may not be fully consistent with the xlocale API. | |
62 | Of particular note is | |
63 | .Fn setinvalidrune , | |
64 | which would normally modify the value in the global locale. | |
65 | Since this value resides in a sub-structure of | |
66 | .Vt locale_t | |
67 | and sub-structures may be shared by multiple locales, | |
68 | .Fn setinvalidrune | |
69 | has been modified to make a copy of the sub-structure. | |
70 | This prevents it from affecting other locales. | |
b5d655f7 | 71 | #endif /* UNIFDEF_LEGACY_RUNE_APIS */ |
3d9156a7 | 72 | .Sh SEE ALSO |
3d9156a7 A |
73 | .Xr duplocale 3 , |
74 | .Xr freelocale 3 , | |
224c7076 | 75 | .Xr localeconv 3 , |
3d9156a7 A |
76 | .Xr newlocale 3 , |
77 | .Xr querylocale 3 , | |
78 | .Xr uselocale 3 | |
79 | .Sh CONVENIENCE FUNCTIONS | |
224c7076 A |
80 | The xlocale API also includes "convenience functions": |
81 | functions that can be executed using a given locale, | |
82 | rather than the current locale. | |
83 | These functions all take one extra | |
3d9156a7 | 84 | .Vt locale_t |
224c7076 A |
85 | argument at the end of the traditional argument list, |
86 | except in the case of variable-argument functions, | |
87 | in which case the extra argument comes before the format string. | |
3d9156a7 A |
88 | If a NULL |
89 | .Vt locale_t | |
90 | is passed, the C locale will be used. | |
91 | .Pp | |
92 | For completeness, | |
224c7076 A |
93 | the convenience functions are listed here |
94 | (organized by the header file that contains the original function). | |
3d9156a7 A |
95 | .Pp |
96 | .Bl -tag -width monetary.h | |
97 | .It Aq _wctype.h | |
98 | .Xr iswalnum_l 3 , | |
99 | .Xr iswalpha_l 3 , | |
100 | .Xr iswcntrl_l 3 , | |
101 | .Xr iswctype_l 3 , | |
102 | .Xr iswdigit_l 3 , | |
103 | .Xr iswgraph_l 3 , | |
104 | .Xr iswlower_l 3 , | |
105 | .Xr iswprint_l 3 , | |
106 | .Xr iswpunct_l 3 , | |
107 | .Xr iswspace_l 3 , | |
108 | .Xr iswupper_l 3 , | |
109 | .Xr iswxdigit_l 3 , | |
110 | .Xr towlower_l 3 , | |
111 | .Xr towupper_l 3 , | |
112 | .Xr wctype_l 3 | |
113 | .It Aq ctype.h | |
114 | .Xr digittoint_l 3 , | |
115 | .Xr isalnum_l 3 , | |
116 | .Xr isalpha_l 3 , | |
117 | .Xr isblank_l 3 , | |
118 | .Xr iscntrl_l 3 , | |
119 | .Xr isdigit_l 3 , | |
120 | .Xr isgraph_l 3 , | |
121 | .Xr ishexnumber_l 3 , | |
122 | .Xr isideogram_l 3 , | |
123 | .Xr islower_l 3 , | |
124 | .Xr isnumber_l 3 , | |
125 | .Xr isphonogram_l 3 , | |
126 | .Xr isprint_l 3 , | |
127 | .Xr ispunct_l 3 , | |
128 | .Xr isrune_l 3 , | |
129 | .Xr isspace_l 3 , | |
130 | .Xr isspecial_l 3 , | |
131 | .Xr isupper_l 3 , | |
132 | .Xr isxdigit_l 3 , | |
133 | .Xr tolower_l 3 , | |
134 | .Xr toupper_l 3 | |
135 | .It Aq inttypes.h | |
136 | .Xr strtoimax_l 3 , | |
137 | .Xr strtoumax_l 3 , | |
138 | .Xr wcstoimax_l 3 , | |
139 | .Xr wcstoumax_l 3 | |
140 | .It Aq langinfo.h | |
141 | .Xr nl_langinfo_l 3 | |
142 | .It Aq monetary.h | |
143 | .Xr strfmon_l 3 | |
144 | .It Aq stdio.h | |
145 | .Xr asprintf_l 3 , | |
146 | .Xr fprintf_l 3 , | |
147 | .Xr fscanf_l 3 , | |
148 | .Xr printf_l 3 , | |
149 | .Xr scanf_l 3 , | |
150 | .Xr snprintf_l 3 , | |
151 | .Xr sprintf_l 3 , | |
152 | .Xr sscanf_l 3 , | |
153 | .Xr vasprintf_l 3 , | |
154 | .Xr vfprintf_l 3 , | |
155 | .Xr vfscanf_l 3 , | |
156 | .Xr vprintf_l 3 , | |
157 | .Xr vscanf_l 3 , | |
158 | .Xr vsnprintf_l 3 , | |
159 | .Xr vsprintf_l 3 , | |
160 | .Xr vsscanf_l 3 | |
161 | .It Aq stdlib.h | |
162 | .Xr atof_l 3 , | |
163 | .Xr atoi_l 3 , | |
164 | .Xr atol_l 3 , | |
165 | .Xr atoll_l 3 , | |
166 | .Xr mblen_l 3 , | |
167 | .Xr mbstowcs_l 3 , | |
168 | .Xr mbtowc_l 3 , | |
169 | .Xr strtod_l 3 , | |
170 | .Xr strtof_l 3 , | |
171 | .Xr strtol_l 3 , | |
172 | .Xr strtold_l 3 , | |
173 | .Xr strtoll_l 3 , | |
174 | .Xr strtoq_l 3 , | |
175 | .Xr strtoul_l 3 , | |
176 | .Xr strtoull_l 3 , | |
177 | .Xr strtouq_l 3 , | |
178 | .Xr wcstombs_l 3 , | |
179 | .Xr wctomb_l 3 | |
180 | .It Aq string.h | |
181 | .Xr strcoll_l 3 , | |
182 | .Xr strxfrm_l 3 , | |
183 | .Xr strcasecmp_l 3 , | |
184 | .Xr strcasestr_l 3 , | |
185 | .Xr strncasecmp_l 3 | |
186 | .It Aq time.h | |
187 | .Xr strftime_l 3 , | |
188 | .Xr strptime_l 3 | |
189 | .It Aq wchar.h | |
190 | .Xr btowc_l 3 , | |
191 | .Xr fgetwc_l 3 , | |
192 | .Xr *fgetws_l 3 , | |
193 | .Xr fputwc_l 3 , | |
194 | .Xr fputws_l 3 , | |
195 | .Xr fwprintf_l 3 , | |
196 | .Xr fwscanf_l 3 , | |
197 | .Xr getwc_l 3 , | |
198 | .Xr getwchar_l 3 , | |
199 | .Xr mbrlen_l 3 , | |
200 | .Xr mbrtowc_l 3 , | |
201 | .Xr mbsinit_l 3 , | |
202 | .Xr mbsnrtowcs_l 3 , | |
203 | .Xr mbsrtowcs_l 3 , | |
204 | .Xr putwc_l 3 , | |
205 | .Xr putwchar_l 3 , | |
206 | .Xr swprintf_l 3 , | |
207 | .Xr swscanf_l 3 , | |
208 | .Xr ungetwc_l 3 , | |
209 | .Xr vfwprintf_l 3 , | |
210 | .Xr vfwscanf_l 3 , | |
211 | .Xr vswprintf_l 3 , | |
212 | .Xr vswscanf_l 3 , | |
213 | .Xr vwprintf_l 3 , | |
214 | .Xr vwscanf_l 3 , | |
215 | .Xr wcrtomb_l 3 , | |
216 | .Xr wcscoll_l 3 , | |
217 | .Xr wcsftime_l 3 , | |
218 | .Xr wcsnrtombs_l 3 , | |
219 | .Xr wcsrtombs_l 3 , | |
220 | .Xr wcstod_l 3 , | |
221 | .Xr wcstof_l 3 , | |
222 | .Xr wcstol_l 3 , | |
223 | .Xr wcstold_l 3 , | |
224 | .Xr wcstoll_l 3 , | |
225 | .Xr wcstoul_l 3 , | |
226 | .Xr wcstoull_l 3 , | |
227 | .Xr wcswidth_l 3 , | |
228 | .Xr wcsxfrm_l 3 , | |
229 | .Xr wctob_l 3 , | |
230 | .Xr wcwidth_l 3 , | |
231 | .Xr wprintf_l 3 , | |
232 | .Xr wscanf_l 3 | |
233 | .It Aq wctype.h | |
234 | .Xr iswblank_l 3 , | |
235 | .Xr iswhexnumber_l 3 , | |
236 | .Xr iswideogram_l 3 , | |
237 | .Xr iswnumber_l 3 , | |
238 | .Xr iswphonogram_l 3 , | |
239 | .Xr iswrune_l 3 , | |
240 | .Xr iswspecial_l 3 , | |
241 | .Xr nextwctype_l 3 , | |
242 | .Xr towctrans_l 3 , | |
243 | .Xr wctrans_l 3 | |
244 | .It Aq xlocale.h | |
245 | .Xr localeconv_l 3 | |
246 | .El |