1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH WCSTRING 3C "Aug 14, 2002"
11 .SH NAME
12 wcstring, wcscat, wscat, wcsncat, wsncat, wcscmp, wscmp, wcsncmp, wsncmp,
13 wcscpy, wscpy, wcsncpy, wsncpy, wcslen, wslen, wcschr, wschr, wcsrchr, wsrchr,
14 windex, wrindex, wcspbrk, wspbrk, wcswcs, wcsspn, wsspn, wcscspn, wscspn,
15 wcstok, wstok \- wide-character string operations
16 .SH SYNOPSIS
17 .LP
18 .nf
19 #include <wchar.h>
20
21 \fBwchar_t *\fR\fBwcscat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBwchar_t *\fR\fBwcsncat\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR,
27 \fBsize_t\fR \fIn\fR);
28 .fi
29
30 .LP
31 .nf
32 \fBint\fR \fBwcscmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
33 .fi
34
35 .LP
36 .nf
37 \fBint\fR \fBwcsncmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
38 .fi
39
40 .LP
41 .nf
42 \fBwchar_t *\fR\fBwcscpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
43 .fi
44
45 .LP
46 .nf
47 \fBwchar_t *\fR\fBwcsncpy\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR,
48 \fBsize_t\fR \fIn\fR);
49 .fi
50
51 .LP
52 .nf
53 \fBsize_t\fR \fBwcslen\fR(\fBconst wchar_t *\fR\fIws\fR);
54 .fi
55
56 .LP
57 .nf
58 \fBwchar_t *\fR\fBwcschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
59 .fi
60
61 .LP
62 .nf
63 \fBwchar_t *\fR\fBwcsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
64 .fi
65
66 .LP
67 .nf
68 \fBwchar_t *\fR\fBwcspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
69 .fi
70
71 .LP
72 .nf
73 \fBwchar_t *\fR\fBwcswcs\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
74 .fi
75
76 .LP
77 .nf
78 \fBsize_t\fR \fBwcsspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
79 .fi
80
81 .LP
82 .nf
83 \fBsize_t\fR \fBwcscspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
84 .fi
85
86 .SS "XPG4, SUS, SUSv2, SUSv3"
87 .LP
88 .nf
89 \fBwchar_t *\fR\fBwcstok\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR);
90 .fi
91
92 .SS "Default and other standards"
93 .LP
94 .nf
95 \fBwchar_t *\fR\fBwcstok\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBwchar_t **\fR\fIptr\fR);
96 .fi
97
98 .LP
99 .nf
100 #include <widec.h>
101
102 \fBwchar_t *\fR\fBwscat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
103 .fi
104
105 .LP
106 .nf
107 \fBwchar_t *\fR\fBwsncat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
108 .fi
109
110 .LP
111 .nf
112 \fBint\fR \fBwscmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
113 .fi
114
115 .LP
116 .nf
117 \fBint\fR \fBwsncmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
118 .fi
119
120 .LP
121 .nf
122 \fBwchar_t *\fR\fBwscpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
123 .fi
124
125 .LP
126 .nf
127 \fBwchar_t *\fR\fBwsncpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
128 .fi
129
130 .LP
131 .nf
132 \fBsize_t\fR \fBwslen\fR(\fBconst wchar_t *\fR\fIws\fR);
133 .fi
134
135 .LP
136 .nf
137 \fBwchar_t *\fR\fBwschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchat_t\fR \fIwc\fR);
138 .fi
139
140 .LP
141 .nf
142 \fBwchar_t *\fR\fBwsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchat_t\fR \fIwc\fR);
143 .fi
144
145 .LP
146 .nf
147 \fBwchar_t *\fR\fBwspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
148 .fi
149
150 .LP
151 .nf
152 \fBsize_t\fR \fBwsspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
153 .fi
154
155 .LP
156 .nf
157 \fBsize_t\fR \fBwscspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
158 .fi
159
160 .LP
161 .nf
162 \fBwchar_t *\fR\fBwstok\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
163 .fi
164
165 .LP
166 .nf
167 \fBwchar_t *\fR\fBwindex\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
168 .fi
169
170 .LP
171 .nf
172 \fBwchar_t *\fR\fBwrindex\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
173 .fi
174
175 .SS "ISO C++"
176 .LP
177 .nf
178 #include <wchar.h>
179
180 \fBconst wchar_t *\fR\fBwcschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
181 .fi
182
183 .LP
184 .nf
185 \fBconst wchar_t *\fR\fBwcspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
186 .fi
187
188 .LP
189 .nf
190 \fBconst wchar_t *\fR\fBwcsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
191 .fi
192
193 .LP
194 .nf
195 #include <cwchar>
196
197 \fBwchar_t *std::\fR\fBwcschr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
198 .fi
199
200 .LP
201 .nf
202 \fBwchar_t *std::\fR\fBwcspbrk\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
203 .fi
204
205 .LP
206 .nf
207 \fBwchar_t *std::\fR\fBwcsrchr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
208 .fi
209
210 .SH DESCRIPTION
211 .sp
212 .LP
213 These functions operate on wide-character strings terminated by \fBwchar_t\fR
214 \fINULL\fR characters. During appending or copying, these routines do not check
215 for an overflow condition of the receiving string. In the following, \fIws\fR,
216 \fIws1\fR, and \fIws2\fR point to wide-character strings terminated by a
217 \fBwchar_t NULL\fR.
218 .SS "wcscat(\|), wscat(\|)"
219 .sp
220 .LP
221 The \fBwcscat()\fR and \fBwscat()\fR functions append a copy of the
222 wide-character string pointed to by \fIws2\fR (including the terminating null
223 wide-character code) to the end of the wide-character string pointed to by
224 \fIws1\fR. The initial wide-character code of \fIws2\fR overwrites the null
225 wide-character code at the end of \fIws1\fR. If copying takes place between
226 objects that overlap, the behavior is undefined. Both functions return
227 \fIs1\fR; no return value is reserved to indicate an error.
228 .SS "wcsncat(\|), wsncat(\|)"
229 .sp
230 .LP
231 The \fBwcsncat()\fR and \fBwsncat()\fR functions append not more than \fIn\fR
232 wide-character codes (a null wide-character code and wide-character codes that
233 follow it are not appended) from the array pointed to by \fIws2\fR to the end
234 of the wide-character string pointed to by \fIws1\fR. The initial
235 wide-character code of \fIws2\fR overwrites the null wide-character code at the
236 end of \fIws1\fR. A terminating null wide-character code is always appended to
237 the result. Both functions return \fIws1\fR; no return value is reserved to
238 indicate an error.
239 .SS "wcscmp(\|), wscmp(\|)"
240 .sp
241 .LP
242 The \fBwcscmp()\fR and \fBwscmp()\fR functions compare the wide-character
243 string pointed to by \fIws1\fR to the wide-character string pointed to by
244 \fIws2\fR. The sign of a non-zero return value is determined by the sign of the
245 difference between the values of the first pair of wide-character codes that
246 differ in the objects being compared. Upon completion, both functions return an
247 integer greater than, equal to, or less than zero, if the wide-character string
248 pointed to by \fIws1\fR is greater than, equal to, or less than the
249 wide-character string pointed to by \fIws2\fR.
250 .SS "wcsncmp(\|), wsncmp(\|)"
251 .sp
252 .LP
253 The \fBwcsncmp()\fR and \fBwsncmp()\fR functions compare not more than \fIn\fR
254 wide-character codes (wide-character codes that follow a null wide character
255 code are not compared) from the array pointed to by \fIws1\fR to the array
256 pointed to by \fIws2\fR. The sign of a non-zero return value is determined by
257 the sign of the difference between the values of the first pair of
258 wide-character codes that differ in the objects being compared. Upon successful
259 completion, both functions return an integer greater than, equal to, or less
260 than zero, if the possibly null-terminated array pointed to by \fIws1\fR is
261 greater than, equal to, or less than the possibly null-terminated array pointed
262 to by \fIws2\fR.
263 .SS "wcscpy(\|), wscpy(\|)"
264 .sp
265 .LP
266 The \fBwcscpy()\fR and \fBwscpy()\fR functions copy the wide-character string
267 pointed to by \fIws2\fR (including the terminating null wide-character code)
268 into the array pointed to by \fIws1\fR. If copying takes place between objects
269 that overlap, the behavior is undefined. Both functions return \fIws1\fR; no
270 return value is reserved to indicate an error.
271 .SS "wcsncpy(\|), wsncpy(\|)"
272 .sp
273 .LP
274 The \fBwcsncpy()\fR and \fBwsncpy()\fR functions copy not more than \fIn\fR
275 wide-character codes (wide-character codes that follow a null wide character
276 code are not copied) from the array pointed to by \fIws2\fR to the array
277 pointed to by \fIws1\fR. If copying takes place between objects that overlap,
278 the behavior is undefined. If the array pointed to by \fIws2\fR is a
279 wide-character string that is shorter than \fIn\fR wide-character codes, null
280 wide-character codes are appended to the copy in the array pointed to by
281 \fIws1\fR, until a total \fIn\fR wide-character codes are written. Both
282 functions return \fI ws1\fR; no return value is reserved to indicate an error.
283 .SS "wcslen(\|), wslen(\|)"
284 .sp
285 .LP
286 The \fBwcslen()\fR and \fBwslen()\fR functions compute the number of
287 wide-character codes in the wide-character string to which \fIws\fR points, not
288 including the terminating null wide-character code. Both functions return
289 \fIws\fR; no return value is reserved to indicate an error.
290 .SS "wcschr(\|), wschr(\|)"
291 .sp
292 .LP
293 The \fBwcschr()\fR and \fBwschr()\fR functions locate the first occurrence of
294 \fIwc\fR in the wide-character string pointed to by \fIws\fR. The value of
295 \fIwc\fR must be a character representable as a type \fBwchar_t\fR and must be
296 a wide-character code corresponding to a valid character in the current locale.
297 The terminating null wide-character code is considered to be part of the
298 wide-character string. Upon completion, both functions return a pointer to the
299 wide-character code, or a null pointer if the wide-character code is not found.
300 .SS "wcsrchr(\|), wsrchr(\|)"
301 .sp
302 .LP
303 The \fBwcsrchr()\fR and \fBwsrchr()\fR functions locate the last occurrence of
304 \fIwc\fR in the wide-character string pointed to by \fIws\fR. The value of
305 \fIwc\fR must be a character representable as a type \fBwchar_t\fR and must be
306 a wide-character code corresponding to a valid character in the current locale.
307 The terminating null wide-character code is considered to be part of the
308 wide-character string. Upon successful completion, both functions return a
309 pointer to the wide-character code, or a null pointer if \fIwc\fR does not
310 occur in the wide-character string.
311 .SS "windex(\|), wrindex(\|)"
312 .sp
313 .LP
314 The \fBwindex()\fR and \fBwrindex()\fR functions behave the same as
315 \fBwschr()\fR and \fBwsrchr()\fR, respectively.
316 .SS "wcspbrk(\|), wspbrk(\|)"
317 .sp
318 .LP
319 The \fBwcspbrk()\fR and \fBwspbrk()\fR functions locate the first occurrence in
320 the wide character string pointed to by \fIws1\fR of any wide-character code
321 from the wide-character string pointed to by \fIws2\fR. Upon successful
322 completion, the function returns a pointer to the wide-character code, or a
323 null pointer if no wide-character code from \fIws2\fR occurs in \fIws1\fR.
324 .SS "wcswcs(\|)"
325 .sp
326 .LP
327 The \fBwcswcs()\fR function locates the first occurrence in the wide-character
328 string pointed to by \fIws1\fR of the sequence of wide-character codes
329 (excluding the terminating null wide-character code) in the wide-character
330 string pointed to by \fIws2\fR. Upon successful completion, the function
331 returns a pointer to the located wide-character string, or a null pointer if
332 the wide-character string is not found. If \fIws2\fR points to a wide-character
333 string with zero length, the function returns \fIws1\fR.
334 .SS "wcsspn(\|), wsspn(\|)"
335 .sp
336 .LP
337 The \fBwcsspn()\fR and \fBwsspn()\fR functions compute the length of the
338 maximum initial segment of the wide-character string pointed to by \fIws1\fR
339 which consists entirely of wide-character codes from the wide-character string
340 pointed to by \fIws2\fR. Both functions return the length \fIws1\fR; no return
341 value is reserved to indicate an error.
342 .SS "wcscspn(\|), wscspn(\|)"
343 .sp
344 .LP
345 The \fBwcscspn()\fR and \fBwscspn()\fR functions compute the length of the
346 maximum initial segment of the wide-character string pointed to by \fIws1\fR
347 which consists entirely of wide-character codes \fInot\fR from the
348 wide-character string pointed to by \fIws2\fR. Both functions return the length
349 of the initial substring of \fIws1\fR; no return value is reserved to indicate
350 an error.
351 .SS "wcstok(\|), wstok(\|)"
352 .sp
353 .LP
354 A sequence of calls to the \fBwcstok()\fR and \fBwstok()\fR functions break the
355 wide-character string pointed to by \fIws1\fR into a sequence of tokens, each
356 of which is delimited by a wide-character code from the wide-character string
357 pointed to by \fIws2\fR.
358 .SS "Default and other standards"
359 .sp
360 .LP
361 The third argument points to a caller-provided \fBwchar_t\fR pointer into which
362 the \fBwcstok()\fR function stores information necessary for it to continue
363 scanning the same wide-character string. This argument is not available with
364 the XPG4 and SUS versions of \fBwcstok()\fR, nor is it available with the
365 \fBwstok()\fR function. See \fBstandards\fR(5).
366 .sp
367 .LP
368 The first call in the sequence has \fIws1\fR as its first argument, and is
369 followed by calls with a null pointer as their first argument. The separator
370 string pointed to by \fIws2\fR may be different from call to call.
371 .sp
372 .LP
373 The first call in the sequence searches the wide-character string pointed to by
374 \fIws1\fR for the first wide-character code that is \fInot\fR contained in the
375 current separator string pointed to by \fIws2\fR. If no such wide-character
376 code is found, then there are no tokens in the wide-character string pointed to
377 by \fIws1\fR, and \fBwcstok()\fR and \fBwstok()\fR return a null pointer. If
378 such a wide-character code is found, it is the start of the first token.
379 .sp
380 .LP
381 The \fBwcstok()\fR and \fBwstok()\fR functions then search from that point for
382 a wide-character code that \fIis\fR contained in the current separator string.
383 If no such wide-character code is found, the current token extends to the end
384 of the wide-character string pointed to by \fIws1\fR, and subsequent searches
385 for a token will return a null pointer. If such a wide-character code is found,
386 it is overwritten by a null wide character, which terminates the current token.
387 The \fBwcstok()\fR and \fBwstok()\fR functions save a pointer to the following
388 wide-character code, from which the next search for a token will start.
389 .sp
390 .LP
391 Each subsequent call, with a null pointer as the value of the first argument,
392 starts searching from the saved pointer and behaves as described above.
393 .sp
394 .LP
395 Upon successful completion, both functions return a pointer to the first
396 wide-character code of a token. Otherwise, if there is no token, a null pointer
397 is returned.
398 .SH ATTRIBUTES
399 .sp
400 .LP
401 See \fBattributes\fR(5) for descriptions of the following attributes:
402 .sp
403
404 .sp
405 .TS
406 box;
407 c | c
408 l | l .
409 ATTRIBUTE TYPE ATTRIBUTE VALUE
410 _
411 CSI Enabled
412 _
413 Interface Stability See NOTES.
414 _
415 MT-Level MT-Safe
416 .TE
417
418 .SH SEE ALSO
419 .sp
420 .LP
421 \fBmalloc\fR(3C), \fBstring\fR(3C), \fBwcswidth\fR(3C), \fBwcwidth\fR(3C),
422 \fBattributes\fR(5), \fBstandards\fR(5)
423 .SH NOTES
424 .sp
425 .LP
426 The \fBwcscat()\fR, \fBwcsncat()\fR, \fBwcscmp()\fR, \fBwcsncmp()\fR,
427 \fBwcscpy()\fR, \fBwcsncpy()\fR, \fBwcslen()\fR, \fBwcschr()\fR,
428 \fBwcsrchr()\fR, \fBwcspbrk()\fR, \fBwcswcs()\fR, \fBwcsspn()\fR,
429 \fBwcscspn()\fR, and \fBwcstok()\fR functions are Standard. The \fBwscat()\fR,
430 \fBwsncat()\fR, \fBwscmp()\fR, \fBwsncmp()\fR, \fBwscpy()\fR, \fBwsncpy()\fR,
431 \fBwslen()\fR, \fBwschr()\fR, \fBwsrchr()\fR, \fBwspbrk()\fR, \fBwsspn()\fR,
432 \fBwstok()\fR, \fBwindex()\fR, and \fBwrindex()\fR functions are Stable.
|
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .Dd "Jul 22, 2014"
11 .Dt WCSTRING 3C
12 .Os
13 .Sh NAME
14 .Nm wcstring ,
15 .Nm wcscat ,
16 .Nm wscat ,
17 .Nm wcsncat ,
18 .Nm wsncat ,
19 .Nm wcscmp ,
20 .Nm wscmp ,
21 .Nm wcsncmp ,
22 .Nm wsncmp ,
23 .Nm wcscpy ,
24 .Nm wscpy ,
25 .Nm wcsncpy ,
26 .Nm wsncpy ,
27 .Nm wcschr ,
28 .Nm wschr ,
29 .Nm wcsrchr ,
30 .Nm wsrchr ,
31 .Nm windex ,
32 .Nm wrindex ,
33 .Nm wcspbrk ,
34 .Nm wspbrk ,
35 .Nm wcswcs ,
36 .Nm wcsspn ,
37 .Nm wsspn ,
38 .Nm wcscspn ,
39 .Nm wscspn ,
40 .Nm wcstok ,
41 .Nm wstok
42 .Nd wide-character string operations
43 .
44 .Sh SYNOPSIS
45 .In wchar.h
46 .
47 .Ft "wchar_t *"
48 .Fn wcscat "wchar_t *ws1" "const wchar_t *ws2"
49 .
50 .Ft "wchar_t *"
51 .Fn wcsncat "wchar_t *restrict ws1" "const wchar_t *restrict ws2" "size_t n"
52 .
53 .Ft int
54 .Fn wcscmp "const wchar_t *ws1" "const wchar_t *ws2"
55 .
56 .Ft int
57 .Fn wcsncmp "const wchar_t *ws1" "const wchar_t *ws2" "size_t n"
58 .
59 .Ft "wchar_t *"
60 .Fn wcscpy "wchar_t *ws1" "const wchar_t *ws2"
61 .
62 .Ft "wchar_t *"
63 .Fn wcsncpy "wchar_t *restrict ws1" "const wchar_t *restrict ws2" "size_t n"
64 .
65 .Ft "wchar_t *"
66 .Fn wcschr "const wchar_t *ws" "wchar_t wc"
67 .
68 .Ft "wchar_t *"
69 .Fn wcsrchr "const wchar_t *ws" "wchar_t wc"
70 .
71 .Ft "wchar_t *"
72 .Fn wcspbrk "const wchar_t *ws1" "const wchar_t *ws2"
73 .
74 .Ft "wchar_t *"
75 .Fn wcswcs "const wchar_t *ws1" "const wchar_t *ws2"
76 .
77 .Ft size_t
78 .Fn wcsspn "const wchar_t *ws1" "const wchar_t *ws2"
79 .
80 .Ft size_t
81 .Fn wcscspn "const wchar_t *ws1" "const wchar_t *ws2"
82 .
83 .Ss "XPG4 and SUS"
84 .
85 .Ft "wchar_t *"
86 .Fn wcstok "wchar_t *restrict ws1" "const wchar_t *restrict ws2"
87 .
88 .Ss "Default and other standards"
89 .
90 .Ft "wchar_t *"
91 .Fo wcstok
92 .Fa "wchar_t *restrict ws1"
93 .Fa "const wchar_t *restrict ws2"
94 .Fa "wchar_t **restrict ptr"
95 .Fc
96 .
97 .In widec.h
98 .
99 .Ft wchar_t *
100 .Fn wscat "wchar_t *ws1" "const wchar_t *ws2"
101 .
102 .Ft "wchar_t *"
103 .Fn wsncat "wchar_t *ws1" "const wchar_t *ws2" "size_t n"
104 .
105 .Ft int
106 .Fn wscmp "const wchar_t *ws1" "const wchar_t *ws2"
107 .
108 .Ft int
109 .Fn wsncmp "const wchar_t *ws1" "const wchar_t *ws2" "size_t n"
110 .
111 .Ft "wchar_t *"
112 .Fn wscpy "wchar_t *ws1" "const wchar_t *ws2"
113 .
114 .Ft "wchar_t *"
115 .Fn wsncpy "wchar_t *ws1" "const wchar_t *ws2" "size_t n"
116 .
117 .Ft "wchar_t *"
118 .Fn wschr "const wchar_t *ws" "wchat_t wc"
119 .
120 .Ft "wchar_t *"
121 .Fn wsrchr "const wchar_t *ws" "wchar_t wc"
122 .
123 .Ft "wchar_t *"
124 .Fn wspbrk "const wchar_t *ws1" "const wchar_t *ws2"
125 .
126 .Ft size_t
127 .Fn wsspn "const wchar_t *ws1" "const wchar_t *ws2"
128 .
129 .Ft size_t
130 .Fn wscspn "const wchar_t *ws1" "const wchar_t *ws2"
131 .
132 .Ft "wchar_t *"
133 .Fn wstok "wchar_t *ws1" "const wchar_t *ws2"
134 .
135 .Ft "wchar_t *"
136 .Fn windex "const wchar_t *ws" "wchar_t wc"
137 .
138 .Ft "wchar_t *"
139 .Fn wrindex "const wchar_t *ws" "wchar_t wc"
140 .
141 .Ss "ISO C++"
142 .
143 .In wchar.h
144 .
145 .Ft "const wchar_t *"
146 .Fn wcschr "const wchar_t *ws" "wchar_t wc"
147 .
148 .Ft "const wchar_t *"
149 .Fn wcspbrk "const wchar_t *ws1" "const wchar_t *ws2"
150 .
151 .Ft "const wchar_t *"
152 .Fn wcsrchr "const wchar_t *ws" "wchar_t wc"
153 .
154 .In cwchar
155 .
156 .Ft wchar_t *
157 .Fn std::wcschr "wchar_t *ws" "wchar_t wc"
158 .
159 .Ft "wchar_t *"
160 .Fn std::wcspbrk "wchar_t *ws1" "const wchar_t *ws2"
161 .
162 .Ft "wchar_t *"
163 .Fn std::wcsrchr "wchar_t *ws" "wchar_t wc"
164 .
165 .Sh DESCRIPTION
166 .
167 These functions operate on wide-character strings terminated by
168 .Ft wchar_t
169 null characters. During appending or copying, these routines do not check
170 for an overflow condition of the receiving string. In the following,
171 .Fa ws ,
172 .Fa ws1 ,
173 and
174 .Fa ws2
175 point to wide-character strings terminated by a
176 .Ft wchar_t
177 null, that is
178 .Pq Vt wchar_t
179 0.
180 .
181 .Ss Fn wcscat , wscat
182 .
183 The
184 .Fn wcscat and
185 .Fn wscat
186 functions append a copy of the
187 wide-character string pointed to by
188 .Fa ws2
189 (including the terminating null
190 wide-character code) to the end of the wide-character string pointed to by
191 .Fa ws1 .
192 The initial wide-character code of
193 .Fa ws2
194 overwrites the null wide-character code at the end of
195 .Fa ws1 .
196 If copying takes place between
197 objects that overlap, the behavior is undefined. Both functions return
198 .Fa ws1 ;
199 no return value is reserved to indicate an error.
200 .
201 .Ss Fn wcsncat , wsncat
202 .
203 The
204 .Fn wcsncat
205 and
206 .Fn wsncat
207 functions append not more than
208 .Fa n
209 wide-character codes (a null wide-character code and wide-character codes that
210 follow it are not appended) from the array pointed to by
211 .Fa ws2
212 to the end of the wide-character string pointed to by
213 .Fa ws1 .
214 The initial wide-character code of
215 .Fa ws2
216 overwrites the null wide-character code at the
217 end of
218 .Fa ws1 .
219 A terminating null wide-character code is always appended to
220 the result. Both functions return
221 .Fa ws1 ;
222 no return value is reserved to indicate an error.
223 .
224 .Ss Fn wcscmp , wscmp
225 .
226 The
227 .Fn wcscmp
228 and
229 .Fn wscmp
230 functions compare the wide-character string pointed to by
231 .Fa ws1
232 to the wide-character string pointed to by
233 .Fa ws2 .
234 The sign of a non-zero return value is determined by the sign of the
235 difference between the values of the first pair of wide-character codes that
236 differ in the objects being compared. Upon completion, both functions return an
237 integer greater than, equal to, or less than zero, if the wide-character string
238 pointed to by
239 .Fa ws1
240 is greater than, equal to, or less than the
241 wide-character string pointed to by
242 .Fa ws2 .
243 .
244 .Ss Fn wcsncmp , wsncmp
245 .
246 The
247 .Fn wcsncmp
248 and
249 .Fn wsncmp
250 functions compare not more than
251 .Fa n
252 wide-character codes (wide-character codes that follow a null wide character
253 code are not compared) from the array pointed to by
254 .Fa ws1
255 to the array pointed to by
256 .Fa ws2 .
257 The sign of a non-zero return value is determined by
258 the sign of the difference between the values of the first pair of
259 wide-character codes that differ in the objects being compared. Upon successful
260 completion, both functions return an integer greater than, equal to, or less
261 than zero, if the possibly null-terminated array pointed to by
262 .Fa ws1
263 is
264 greater than, equal to, or less than the possibly null-terminated array pointed
265 to by
266 .Fa ws2 .
267 .
268 .Ss Fn wcscpy , wscpy
269 .
270 The
271 .Fn wcscpy
272 and
273 .Fn wscpy
274 functions copy the wide-character string
275 pointed to by
276 .Fa ws2
277 (including the terminating null wide-character code)
278 into the array pointed to by
279 .Fa ws1 .
280 If copying takes place between objects
281 that overlap, the behavior is undefined. Both functions return
282 .Fa ws1 ;
283 no return value is reserved to indicate an error.
284 .
285 .Ss Fn wcsncpy , wsncpy
286 .
287 The
288 .Fn wcsncpy
289 and
290 .Fn wsncpy
291 functions copy not more than
292 .Fa n
293 wide-character codes (wide-character codes that follow a null wide character
294 code are not copied) from the array pointed to by
295 .Fa ws2
296 to the array pointed to by
297 .Fa ws1 .
298 If copying takes place between objects that overlap,
299 the behavior is undefined. If the array pointed to by
300 .Fa ws2
301 is a wide-character string that is shorter than
302 .Fa n
303 wide-character codes, null
304 wide-character codes are appended to the copy in the array pointed to by
305 .Fa ws1 ,
306 until a total
307 .Fa n
308 wide-character codes are written. Both
309 functions return
310 .Fa ws1 ;
311 no return value is reserved to indicate an error.
312 .
313 .Ss Fn wcschr , wschr , windex
314 .
315 The
316 .Fn wcschr ,
317 .Fn wschr
318 and
319 .Fn windex
320 functions locate the first occurrence of
321 .Fa wc
322 in the wide-character string pointed to by
323 .Fa ws .
324 The value of
325 .Fa wc
326 must be a character representable as a type
327 .Vt wchar_t
328 and must be
329 a wide-character code corresponding to a valid character in the current locale.
330 The terminating null wide-character code is considered to be part of the
331 wide-character string. Upon completion, both functions return a pointer to the
332 wide-character code, or a null pointer if the wide-character code is not found.
333 .
334 .Ss Fn wcsrchr , wsrchr , wrindex
335 .
336 The
337 .Fn wcsrchr ,
338 .Fn wsrchr
339 and
340 .Fn wrindex
341 functions locate the last occurrence of
342 .Fa wc
343 in the wide-character string pointed to by
344 .Fa ws .
345 The value of
346 .Fa wc
347 must be a character representable as a type
348 .Vt wchar_t
349 and must be
350 a wide-character code corresponding to a valid character in the current locale.
351 The terminating null wide-character code is considered to be part of the
352 wide-character string. Upon successful completion, both functions return a
353 pointer to the wide-character code, or a null pointer if
354 .Fa wc
355 does not occur in the wide-character string.
356 .
357 .Ss wcspbrk , wspbrk
358 .
359 The
360 .Fn wcspbrk
361 and
362 .Fn wspbrk
363 functions locate the first occurrence in
364 the wide character string pointed to by
365 .Fa ws1
366 of any wide-character code
367 from the wide-character string pointed to by
368 .Fa ws2 .
369 Upon successful
370 completion, the function returns a pointer to the wide-character code, or a
371 null pointer if no wide-character code from
372 .Fa ws2
373 occurs in
374 .Fa ws1 .
375 .
376 .Ss "wcswcs(\|)"
377 .
378 The
379 .Fn wcswcs
380 function locates the first occurrence in the wide-character
381 string pointed to by
382 .Fa ws1
383 of the sequence of wide-character codes
384 (excluding the terminating null wide-character code) in the wide-character
385 string pointed to by
386 .Fa ws2 .
387 Upon successful completion, the function
388 returns a pointer to the located wide-character string, or a null pointer if
389 the wide-character string is not found. If
390 .Fa ws2
391 points to a wide-character
392 string with zero length, the function returns
393 .Fa ws1 .
394 .
395 .Ss Fn wcsspn , wsspn
396 .
397 The
398 .Fn wcsspn
399 and
400 .Fn wsspn
401 functions return the length of the
402 maximum initial segment of the wide-character string pointed to by
403 .Fa ws1
404 which consists entirely of wide-character codes from the wide-character string
405 pointed to by
406 .Fa ws2 .
407 No return value is reserved to indicate an error.
408 .
409 .Ss wcscspn , wscspn
410 .
411 The
412 .Fn wcscspn
413 and
414 .Fn wscspn
415 functions return the length of the
416 maximum initial segment of the wide-character string pointed to by
417 .Fa ws1
418 which consists entirely of wide-character codes
419 .Em not
420 from the
421 wide-character string pointed to by
422 .Fa ws2 .
423 No return value is reserved to indicate an error.
424 .
425 .Ss wcstok , wstok
426 .
427 A sequence of calls to the
428 .Fn wcstok
429 and
430 .Fn wstok
431 functions break the wide-character string pointed to by
432 .Fa ws1
433 into a sequence of tokens, each
434 of which is delimited by a wide-character code from the wide-character string
435 pointed to by
436 .Fa ws2 .
437 The third argument points to a caller-provided
438 .Ft wchar_t
439 pointer into which
440 the
441 .Fn wcstok
442 function stores information necessary for it to continue
443 scanning the same wide-character string. This argument is not available with
444 the XPG4 legacy version of
445 .Fn wcstok ,
446 nor is it available with the
447 .Fn wstok
448 function. See
449 .Xr standards 5 .
450 .Lp
451 The first call in the sequence has
452 .Fa ws1
453 as its first argument, and is
454 followed by calls with a null pointer as their first argument. The separator
455 string pointed to by
456 .Fa ws2
457 may be different from call to call.
458 .Lp
459 The first call in the sequence searches the wide-character string pointed to by
460 .Fa ws1
461 for the first wide-character code that is
462 .Em not
463 contained in the current separator string pointed to by
464 .Fa ws2 .
465 If no such wide-character
466 code is found, then there are no tokens in the wide-character string pointed to
467 by
468 .Fa ws1 ,
469 and
470 .Fn wcstok
471 and
472 .Fn wstok
473 return a null pointer. If
474 such a wide-character code is found, it is the start of the first token.
475 .Lp
476 The
477 .Fn wcstok
478 and
479 .Fn wstok
480 functions then search from that point for
481 a wide-character code that
482 .Em is
483 contained in the current separator string.
484 If no such wide-character code is found, the current token extends to the end
485 of the wide-character string pointed to by
486 .Fa ws1 ,
487 and subsequent searches
488 for a token will return a null pointer. If such a wide-character code is found,
489 it is overwritten by a null wide character, which terminates the current token.
490 The
491 .Fn wcstok
492 and
493 .Fn wstok
494 functions save a pointer to the following
495 wide-character code into thread-specific storage, from which the next
496 search for a token will start.
497 .Lp
498 Each subsequent call, with a null pointer as the value of the first argument,
499 starts searching from the saved pointer and behaves as described above.
500 .Lp
501 Upon successful completion, both functions return a pointer to the first
502 wide-character code of a token. Otherwise, if there is no token, a null pointer
503 is returned.
504 .Sh CODE SET INDEPENDENCE
505 .Sy Enabled .
506 .Sh INTERFACE STABILITY
507 The
508 .Fn wcscat ,
509 .Fn wcsncat ,
510 .Fn wcscmp ,
511 .Fn wcsncmp ,
512 .Fn wcscpy ,
513 .Fn wcsncpy ,
514 .Fn wcschr ,
515 .Fn wcsrchr ,
516 .Fn wcspbrk ,
517 .Fn wcsspn ,
518 .Fn wcscspn ,
519 and
520 .Fn wcstok
521 functions are
522 .Sy Standard .
523 .Lp
524 The
525 .Fn wcswcs
526 function is
527 .Sy Obsolete Standard .
528 .Lp
529 The
530 .Fn wscat ,
531 .Fn wsncat ,
532 .Fn wscmp ,
533 .Fn wsncmp ,
534 .Fn wscpy ,
535 .Fn wsncpy ,
536 .Fn wslen ,
537 .Fn wschr ,
538 .Fn wsrchr ,
539 .Fn wspbrk ,
540 .Fn wsspn ,
541 .Fn wstok ,
542 .Fn windex ,
543 and
544 .Fn wrindex
545 functions are
546 .Sy Obsolete Committed .
547 .
548 .Sh MT-LEVEL
549 .Sy MT-Safe .
550 Note however that the legacy version of
551 .Fn wcstok ,
552 as well as
553 .Fn wstok ,
554 use thread-specific storage to store the tokenizer state. As a result,
555 the tokenizer state will not be visible to other threads.
556 .Sh SEE ALSO
557 .Xr malloc 3C ,
558 .Xr string 3C ,
559 .Xr wcsdup 3C ,
560 .Xr wcslen 3C ,
561 .Xr wcsstr 3C ,
562 .Xr wcswidth 3C ,
563 .Xr wcwidth 3C ,
564 .Xr standards 5
565 .Sh STANDARDS
566 The
567 .Fn wcscat ,
568 .Fn wcsncat ,
569 .Fn wcscmp ,
570 .Fn wcsncmp ,
571 .Fn wcscpy ,
572 .Fn wcsncpy ,
573 .Fn wcschr ,
574 .Fn wcsrchr ,
575 .Fn wcspbrk ,
576 .Fn wcsspn ,
577 .Fn wcscspn ,
578 .Fn wcstok
579 and
580 .Fn wcswcs
581 functions were introduced in
582 .St -xpg4 .
583 The
584 .Fn wcstok
585 function was modified to take a third argument in
586 .St -xbd5 .
587 The
588 .Fn wcswcs
589 function was removed from
590 .St -p1003.1-2008 ;
591 the
592 .Xr wcsstr 3C
593 function specified by
594 .St -isoC-99
595 is preferred.
|