Print this page
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.
Various tweaks -- add our sections, etc.
Fixes for wcstok.
Finished obsoleting interfaces for XPG7.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/wcstring.3c
+++ new/usr/src/man/man3c/wcstring.3c
1 -'\" te
1 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 2 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
3 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 4 .\" http://www.opengroup.org/bookstore/.
5 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 6 .\" This notice shall appear on any product containing this material.
7 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 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 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
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
223 190 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
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
226 197 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
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
232 209 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
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
245 235 difference between the values of the first pair of wide-character codes that
246 236 differ in the objects being compared. Upon completion, both functions return an
247 237 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
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
254 252 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
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
257 258 the sign of the difference between the values of the first pair of
258 259 wide-character codes that differ in the objects being compared. Upon successful
259 260 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 +than zero, if the possibly null-terminated array pointed to by
262 +.Fa ws1
263 +is
261 264 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
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
275 293 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
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
280 304 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
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
296 329 a wide-character code corresponding to a valid character in the current locale.
297 330 The terminating null wide-character code is considered to be part of the
298 331 wide-character string. Upon completion, both functions return a pointer to the
299 332 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
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
306 350 a wide-character code corresponding to a valid character in the current locale.
307 351 The terminating null wide-character code is considered to be part of the
308 352 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
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
322 370 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
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
329 384 (excluding the terminating null wide-character code) in the wide-character
330 -string pointed to by \fIws2\fR. Upon successful completion, the function
385 +string pointed to by
386 +.Fa ws2 .
387 +Upon successful completion, the function
331 388 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
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
339 404 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
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
356 434 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
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
363 443 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
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
369 454 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
455 +string pointed to by
456 +.Fa ws2
457 +may be different from call to call.
458 +.Lp
373 459 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
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
376 466 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
467 +by
468 +.Fa ws1 ,
469 +and
470 +.Fn wcstok
471 +and
472 +.Fn wstok
473 +return a null pointer. If
378 474 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.
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.
383 484 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
485 +of the wide-character string pointed to by
486 +.Fa ws1 ,
487 +and subsequent searches
385 488 for a token will return a null pointer. If such a wide-character code is found,
386 489 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
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
391 498 Each subsequent call, with a null pointer as the value of the first argument,
392 499 starts searching from the saved pointer and behaves as described above.
393 -.sp
394 -.LP
500 +.Lp
395 501 Upon successful completion, both functions return a pointer to the first
396 502 wide-character code of a token. Otherwise, if there is no token, a null pointer
397 503 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.
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.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX