usr/src/man/man3c/wcstring.3c

   1 '\" te
   2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   3 .\"  Copyright (c) 1992, X/Open Company Limited  All Rights Reserved  Portions Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" 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
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\" 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.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" 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.
   9 .\" 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.
  10 .\" 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]
  11 .TH WCSTRING 3C "Aug 15, 2014"
  12 .SH NAME
  13 wcstring, wcscat, wscat, wcsncat, wsncat, wcscmp, wscmp, wcsncmp, wsncmp,
  14 wcscpy, wscpy, wcsncpy, wsncpy, wslen, wcschr, wschr, wcsrchr, wsrchr,
  15 windex, wrindex, wcspbrk, wspbrk, wcswcs, wcsspn, wsspn, wcscspn, wscspn,
  16 wcstok, wstok \- wide-character string operations
  17 .SH SYNOPSIS
  18 .LP
  19 .nf
  20 #include <wchar.h>
  21
  22 \fBwchar_t *\fR\fBwcscat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBwchar_t *\fR\fBwcsncat\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR,
  28      \fBsize_t\fR \fIn\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBwcscmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBwcsncmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBwchar_t *\fR\fBwcscpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBwchar_t *\fR\fBwcsncpy\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR,
  49      \fBsize_t\fR \fIn\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBwchar_t *\fR\fBwcschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBwchar_t *\fR\fBwcsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBwchar_t *\fR\fBwcspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  65 .fi
  66
  67 .LP
  68 .nf
  69 \fBwchar_t *\fR\fBwcswcs\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  70 .fi
  71
  72 .LP
  73 .nf
  74 \fBsize_t\fR \fBwcsspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  75 .fi
  76
  77 .LP
  78 .nf
  79 \fBsize_t\fR \fBwcscspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  80 .fi
  81
  82 .SS "XPG4, SUS, SUSv2, SUSv3"
  83 .LP
  84 .nf
  85 \fBwchar_t *\fR\fBwcstok\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR);
  86 .fi
  87
  88 .SS "Default and other standards"
  89 .LP
  90 .nf
  91 \fBwchar_t *\fR\fBwcstok\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBwchar_t **\fR\fIptr\fR);
  92 .fi
  93
  94 .LP
  95 .nf
  96 #include <widec.h>
  97
  98 \fBwchar_t *\fR\fBwscat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
  99 .fi
 100
 101 .LP
 102 .nf
 103 \fBwchar_t *\fR\fBwsncat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
 104 .fi
 105
 106 .LP
 107 .nf
 108 \fBint\fR \fBwscmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 109 .fi
 110
 111 .LP
 112 .nf
 113 \fBint\fR \fBwsncmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
 114 .fi
 115
 116 .LP
 117 .nf
 118 \fBwchar_t *\fR\fBwscpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 119 .fi
 120
 121 .LP
 122 .nf
 123 \fBwchar_t *\fR\fBwsncpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR);
 124 .fi
 125
 126 .LP
 127 .nf
 128 \fBsize_t\fR \fBwslen\fR(\fBconst wchar_t *\fR\fIws\fR);
 129 .fi
 130
 131 .LP
 132 .nf
 133 \fBwchar_t *\fR\fBwschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchat_t\fR \fIwc\fR);
 134 .fi
 135
 136 .LP
 137 .nf
 138 \fBwchar_t *\fR\fBwsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchat_t\fR \fIwc\fR);
 139 .fi
 140
 141 .LP
 142 .nf
 143 \fBwchar_t *\fR\fBwspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 144 .fi
 145
 146 .LP
 147 .nf
 148 \fBsize_t\fR \fBwsspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 149 .fi
 150
 151 .LP
 152 .nf
 153 \fBsize_t\fR \fBwscspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 154 .fi
 155
 156 .LP
 157 .nf
 158 \fBwchar_t *\fR\fBwstok\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 159 .fi
 160
 161 .LP
 162 .nf
 163 \fBwchar_t *\fR\fBwindex\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
 164 .fi
 165
 166 .LP
 167 .nf
 168 \fBwchar_t *\fR\fBwrindex\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
 169 .fi
 170
 171 .SS "ISO C++"
 172 .LP
 173 .nf
 174 #include <wchar.h>
 175
 176 \fBconst wchar_t *\fR\fBwcschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
 177 .fi
 178
 179 .LP
 180 .nf
 181 \fBconst wchar_t *\fR\fBwcspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 182 .fi
 183
 184 .LP
 185 .nf
 186 \fBconst wchar_t *\fR\fBwcsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
 187 .fi
 188
 189 .LP
 190 .nf
 191 #include <cwchar>
 192
 193 \fBwchar_t *std::\fR\fBwcschr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
 194 .fi
 195
 196 .LP
 197 .nf
 198 \fBwchar_t *std::\fR\fBwcspbrk\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR);
 199 .fi
 200
 201 .LP
 202 .nf
 203 \fBwchar_t *std::\fR\fBwcsrchr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR);
 204 .fi
 205
 206 .SH DESCRIPTION
 207 .LP
 208 These functions operate on wide-character strings terminated by \fBwchar_t\fR
 209 \fINULL\fR characters. During appending or copying, these routines do not check
 210 for an overflow condition of the receiving string. In the following, \fIws\fR,
 211 \fIws1\fR, and \fIws2\fR point to wide-character strings terminated by a
 212 \fBwchar_t NULL\fR.
 213 .SS "wcscat(\|), wscat(\|)"
 214 .LP
 215 The \fBwcscat()\fR and \fBwscat()\fR functions append a copy of the
 216 wide-character string pointed to by \fIws2\fR (including the terminating null
 217 wide-character code) to the end of the wide-character string pointed to by
 218 \fIws1\fR. The initial wide-character code of \fIws2\fR overwrites the null
 219 wide-character code at the end of \fIws1\fR. If copying takes place between
 220 objects that overlap, the behavior is undefined. Both functions return
 221 \fIs1\fR; no return value is reserved to indicate an error.
 222 .SS "wcsncat(\|), wsncat(\|)"
 223 .LP
 224 The \fBwcsncat()\fR and \fBwsncat()\fR functions append not more than \fIn\fR
 225 wide-character codes (a null wide-character code and wide-character codes that
 226 follow it are not appended) from the array pointed to by \fIws2\fR to the end
 227 of the wide-character string pointed to by \fIws1\fR. The initial
 228 wide-character code of \fIws2\fR overwrites the null wide-character code at the
 229 end of \fIws1\fR. A terminating null wide-character code is always appended to
 230 the result. Both functions return \fIws1\fR; no return value is reserved to
 231 indicate an error.
 232 .SS "wcscmp(\|), wscmp(\|)"
 233 .LP
 234 The \fBwcscmp()\fR and \fBwscmp()\fR functions compare the wide-character
 235 string pointed to by \fIws1\fR to the wide-character string pointed to by
 236 \fIws2\fR. The sign of a non-zero return value is determined by the sign of the
 237 difference between the values of the first pair of wide-character codes that
 238 differ in the objects being compared. Upon completion, both functions return an
 239 integer greater than, equal to, or less than zero, if the wide-character string
 240 pointed to by \fIws1\fR is greater than, equal to, or less than the
 241 wide-character string pointed to by \fIws2\fR.
 242 .SS "wcsncmp(\|), wsncmp(\|)"
 243 .LP
 244 The \fBwcsncmp()\fR and \fBwsncmp()\fR functions compare not more than \fIn\fR
 245 wide-character codes (wide-character codes that follow a null wide character
 246 code are not compared) from the array pointed to by \fIws1\fR to the array
 247 pointed to by \fIws2\fR. The sign of a non-zero return value is determined by
 248 the sign of the difference between the values of the first pair of
 249 wide-character codes that differ in the objects being compared. Upon successful
 250 completion, both functions return an integer greater than, equal to, or less
 251 than zero, if the possibly null-terminated array pointed to by \fIws1\fR is
 252 greater than, equal to, or less than the possibly null-terminated array pointed
 253 to by \fIws2\fR.
 254 .SS "wcscpy(\|), wscpy(\|)"
 255 .LP
 256 The \fBwcscpy()\fR and \fBwscpy()\fR functions copy the wide-character string
 257 pointed to by \fIws2\fR (including the terminating null wide-character code)
 258 into the array pointed to by \fIws1\fR. If copying takes place between objects
 259 that overlap, the behavior is undefined. Both functions return \fIws1\fR; no
 260 return value is reserved to indicate an error.
 261 .SS "wcsncpy(\|), wsncpy(\|)"
 262 .LP
 263 The \fBwcsncpy()\fR and \fBwsncpy()\fR functions  copy not more than \fIn\fR
 264 wide-character codes (wide-character codes that follow a null wide character
 265 code are not copied) from the array pointed to by \fIws2\fR to the array
 266 pointed to by \fIws1\fR. If copying takes place between objects that overlap,
 267 the behavior is undefined. If the array pointed to by \fIws2\fR is a
 268 wide-character string that is shorter than \fIn\fR wide-character codes, null
 269 wide-character codes are appended to the copy in the array pointed to by
 270 \fIws1\fR, until a total \fIn\fR wide-character codes are written. Both
 271 functions return \fI ws1\fR; no return value is reserved to indicate an error.
 272 .SS "wslen(\|)"
 273 .LP
 274 The \fBwslen()\fR function computes the number of
 275 wide-character codes in the wide-character string to which \fIws\fR points, not
 276 including the terminating null wide-character code. It returns
 277 \fIws\fR; no return value is reserved to indicate an error.
 278 .SS "wcschr(\|), wschr(\|)"
 279 .LP
 280 The \fBwcschr()\fR and \fBwschr()\fR functions locate the first occurrence of
 281 \fIwc\fR in the wide-character string pointed to by \fIws\fR. The value of
 282 \fIwc\fR must be a character representable as a type \fBwchar_t\fR and must be
 283 a wide-character code corresponding to a valid character in the current locale.
 284 The terminating null wide-character code is considered to be part of the
 285 wide-character string. Upon completion, both functions return a pointer to the
 286 wide-character code, or a null pointer if the wide-character code is not found.
 287 .SS "wcsrchr(\|), wsrchr(\|)"
 288 .LP
 289 The \fBwcsrchr()\fR and \fBwsrchr()\fR functions locate the last occurrence of
 290 \fIwc\fR in the wide-character string pointed to by \fIws\fR. The value of
 291 \fIwc\fR must be a character representable as a type \fBwchar_t\fR and must be
 292 a wide-character code corresponding to a valid character in the current locale.
 293 The terminating null wide-character code is considered to be part of the
 294 wide-character string. Upon successful completion, both functions return a
 295 pointer to the wide-character code, or a null pointer if \fIwc\fR does not
 296 occur in the wide-character string.
 297 .SS "windex(\|), wrindex(\|)"
 298 .LP
 299 The \fBwindex()\fR and \fBwrindex()\fR functions behave the same as
 300 \fBwschr()\fR and \fBwsrchr()\fR, respectively.
 301 .SS "wcspbrk(\|), wspbrk(\|)"
 302 .LP
 303 The \fBwcspbrk()\fR and \fBwspbrk()\fR functions locate the first occurrence in
 304 the wide character string pointed to by \fIws1\fR of any wide-character code
 305 from the wide-character string pointed to by \fIws2\fR. Upon successful
 306 completion, the function returns a pointer to the wide-character code, or a
 307 null pointer if no wide-character code from \fIws2\fR occurs in \fIws1\fR.
 308 .SS "wcswcs(\|)"
 309 .LP
 310 The \fBwcswcs()\fR function locates the first occurrence in the wide-character
 311 string pointed to by \fIws1\fR of the sequence of wide-character codes
 312 (excluding the terminating null wide-character code) in the wide-character
 313 string pointed to by \fIws2\fR. Upon successful completion, the function
 314 returns a pointer to the located wide-character string, or a null pointer if
 315 the wide-character string is not found. If \fIws2\fR points to a wide-character
 316 string with zero length, the function returns \fIws1\fR.
 317 .SS "wcsspn(\|), wsspn(\|)"
 318 .LP
 319 The \fBwcsspn()\fR and \fBwsspn()\fR functions compute the length of the
 320 maximum initial segment of the wide-character string pointed to by \fIws1\fR
 321 which consists entirely of wide-character codes from the wide-character string
 322 pointed to by \fIws2\fR. Both functions return the length \fIws1\fR; no return
 323 value is reserved to indicate an error.
 324 .SS "wcscspn(\|), wscspn(\|)"
 325 .LP
 326 The \fBwcscspn()\fR and \fBwscspn()\fR functions compute the length of the
 327 maximum initial segment of the wide-character string pointed to by \fIws1\fR
 328 which consists entirely of wide-character codes \fInot\fR from the
 329 wide-character string pointed to by \fIws2\fR. Both functions return the length
 330 of the initial substring of \fIws1\fR; no return value is reserved to indicate
 331 an error.
 332 .SS "wcstok(\|), wstok(\|)"
 333 .LP
 334 A sequence of calls to the \fBwcstok()\fR and \fBwstok()\fR functions break the
 335 wide-character string pointed to by \fIws1\fR into a sequence of tokens, each
 336 of which is delimited by a wide-character code from the wide-character string
 337 pointed to by \fIws2\fR.
 338 .SS "Default and other standards"
 339 .LP
 340 The third argument points to a caller-provided \fBwchar_t\fR pointer into which
 341 the \fBwcstok()\fR function stores information necessary for it to continue
 342 scanning the same wide-character string. This argument is not available with
 343 the XPG4 and SUS versions of \fBwcstok()\fR, nor is it available with the
 344 \fBwstok()\fR function.  See \fBstandards\fR(5).
 345 .LP
 346 The first call in the sequence has \fIws1\fR as its first argument, and is
 347 followed by calls with a null pointer as their first argument. The separator
 348 string pointed to by \fIws2\fR may be different from call to call.
 349 .LP
 350 The first call in the sequence searches the wide-character string pointed to by
 351 \fIws1\fR for the first wide-character code that is \fInot\fR contained in the
 352 current separator string pointed to by \fIws2\fR. If no such wide-character
 353 code is found, then there are no tokens in the wide-character string pointed to
 354 by \fIws1\fR, and \fBwcstok()\fR and \fBwstok()\fR return a null pointer. If
 355 such a wide-character code is found, it is the start of the first token.
 356 .LP
 357 The \fBwcstok()\fR and \fBwstok()\fR functions then search from that point for
 358 a wide-character code that \fIis\fR contained in the current separator string.
 359 If no such wide-character code is found, the current token extends to the end
 360 of the wide-character string pointed to by \fIws1\fR, and subsequent searches
 361 for a token will return a null pointer. If such a wide-character code is found,
 362 it is overwritten by a null wide character, which terminates the current token.
 363 The \fBwcstok()\fR and \fBwstok()\fR functions save a pointer to the following
 364 wide-character code, from which the next search for a token will start.
 365 .LP
 366 Each subsequent call, with a null pointer as the value of the first argument,
 367 starts searching from the saved pointer and behaves as described above.
 368 .LP
 369 Upon successful completion, both functions return a pointer to the first
 370 wide-character code of a token. Otherwise, if there is no token, a null pointer
 371 is returned.
 372 .SH ATTRIBUTES
 373 .LP
 374 See \fBattributes\fR(5) for descriptions of the following attributes:
 375 .sp
 376
 377 .sp
 378 .TS
 379 box;
 380 c | c
 381 l | l .
 382 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 383 _
 384 CSI     Enabled
 385 _
 386 Interface Stability     See NOTES.
 387 _
 388 MT-Level        MT-Safe
 389 .TE
 390
 391 .SH SEE ALSO
 392 .LP
 393 \fBmalloc\fR(3C),
 394 \fBstring\fR(3C),
 395 \fBwcscasecmp\fR(3C),
 396 \fBwcsdup\fR(3C),
 397 \fBwcslen\fR(3C),
 398 \fBwcswidth\fR(3C),
 399 \fBwcwidth\fR(3C),
 400 \fBattributes\fR(5),
 401 \fBstandards\fR(5)
 402 .SH NOTES
 403 .LP
 404 The \fBwcscat()\fR, \fBwcsncat()\fR, \fBwcscmp()\fR, \fBwcsncmp()\fR,
 405 \fBwcscpy()\fR, \fBwcsncpy()\fR, \fBwcschr()\fR,
 406 \fBwcsrchr()\fR, \fBwcspbrk()\fR, \fBwcswcs()\fR, \fBwcsspn()\fR,
 407 \fBwcscspn()\fR, and \fBwcstok()\fR functions are Standard. The \fBwscat()\fR,
 408 \fBwsncat()\fR, \fBwscmp()\fR, \fBwsncmp()\fR, \fBwscpy()\fR, \fBwsncpy()\fR,
 409 \fBwslen()\fR, \fBwschr()\fR, \fBwsrchr()\fR, \fBwspbrk()\fR, \fBwsspn()\fR,
 410 \fBwstok()\fR, \fBwindex()\fR, and \fBwrindex()\fR functions are Stable.