man3/wcstok.3

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