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.
   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.