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.