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.