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.