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  2013-11-18 "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 .sp
  23 .BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim \
  24 ", wchar_t **" 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\\0\(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 .SS Multithreading (see pthreads(7))
  81 The
  82 .BR wcstok ()
  83 function is thread-safe.
  84 .SH CONFORMING TO
  85 C99.
  86 .SH NOTES
  87 The original
  88 .I wcs
  89 wide-character string is destructively modified during
  90 the operation.
  91 .SH EXAMPLE
  92 The following code loops over the tokens contained in a wide-character string.
  93 .sp
  94 .nf
  95 wchar_t *wcs = ...;
  96 wchar_t *token;
  97 wchar_t *state;
  98 for (token = wcstok(wcs, " \\t\\n", &state);
  99     token != NULL;
 100     token = wcstok(NULL, " \\t\\n", &state)) {
 101     ...
 102 }
 103 .fi
 104 .SH SEE ALSO
 105 .BR strtok (3),
 106 .BR wcschr (3)