man3/wcstok.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" References consulted:
   7 .\"   GNU glibc-2 source code and manual
   8 .\"   Dinkumware C library reference http://www.dinkumware.com/
   9 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .TH wcstok 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 wcstok \- split wide-character string into tokens
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .PP
  22 .BI "wchar_t *wcstok(wchar_t *restrict " wcs \
  23 ", const wchar_t *restrict " delim ,
  24 .BI "                wchar_t **restrict " ptr );
  25 .fi
  26 .SH DESCRIPTION
  27 The
  28 .BR wcstok ()
  29 function is the wide-character equivalent of the
  30 .BR strtok (3)
  31 function,
  32 with an added argument to make it multithread-safe.
  33 It can be used
  34 to split a wide-character string
  35 .I wcs
  36 into tokens, where a token is
  37 defined as a substring not containing any wide-characters from
  38 .IR delim .
  39 .PP
  40 The search starts at
  41 .IR wcs ,
  42 if
  43 .I wcs
  44 is not NULL,
  45 or at
  46 .IR *ptr ,
  47 if
  48 .I wcs
  49 is NULL.
  50 First, any delimiter wide-characters are skipped, that is, the
  51 pointer is advanced beyond any wide-characters which occur in
  52 .IR delim .
  53 If the end of the wide-character string is now
  54 reached,
  55 .BR wcstok ()
  56 returns NULL, to indicate that no tokens
  57 were found, and stores an appropriate value in
  58 .IR *ptr ,
  59 so that subsequent calls to
  60 .BR wcstok ()
  61 will continue to return NULL.
  62 Otherwise, the
  63 .BR wcstok ()
  64 function recognizes the beginning of a token
  65 and returns a pointer to it, but before doing that, it zero-terminates the
  66 token by replacing the next wide-character which occurs in
  67 .I delim
  68 with
  69 a null wide character (L\[aq]\e0\[aq]),
  70 and it updates
  71 .I *ptr
  72 so that subsequent calls will
  73 continue searching after the end of recognized token.
  74 .SH RETURN VALUE
  75 The
  76 .BR wcstok ()
  77 function returns a pointer to the next token,
  78 or NULL if no further token was found.
  79 .SH ATTRIBUTES
  80 For an explanation of the terms used in this section, see
  81 .BR attributes (7).
  82 .TS
  83 allbox;
  84 lbx lb lb
  85 l l l.
  86 Interface       Attribute       Value
  87 T{
  88 .na
  89 .nh
  90 .BR wcstok ()
  91 T}      Thread safety   MT-Safe
  92 .TE
  93 .sp 1
  94 .SH STANDARDS
  95 C11, POSIX.1-2008.
  96 .SH HISTORY
  97 POSIX.1-2001, C99.
  98 .SH NOTES
  99 The original
 100 .I wcs
 101 wide-character string is destructively modified during
 102 the operation.
 103 .SH EXAMPLES
 104 The following code loops over the tokens contained in a wide-character string.
 105 .PP
 106 .EX
 107 wchar_t *wcs = ...;
 108 wchar_t *token;
 109 wchar_t *state;
 110 for (token = wcstok(wcs, L" \et\en", &state);
 111     token != NULL;
 112     token = wcstok(NULL, L" \et\en", &state)) {
 113     ...
 114 }
 115 .EE
 116 .SH SEE ALSO
 117 .BR strtok (3),
 118 .BR wcschr (3)