wcstok(3)

1wcstok(3)                  Library Functions Manual                  wcstok(3)
2
3
4

NAME

6       wcstok - split wide-character string into tokens
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <wchar.h>
13
14       wchar_t *wcstok(wchar_t *restrict wcs, const wchar_t *restrict delim,
15                       wchar_t **restrict ptr);
16

DESCRIPTION

18       The wcstok() function is the wide-character equivalent of the strtok(3)
19       function, with an added argument to make it multithread-safe.   It  can
20       be used to split a wide-character string wcs into tokens, where a token
21       is defined as a substring not containing any wide-characters  from  de‐
22       lim.
23
24       The  search  starts  at  wcs, if wcs is not NULL, or at *ptr, if wcs is
25       NULL.  First, any delimiter wide-characters are skipped, that  is,  the
26       pointer  is  advanced  beyond any wide-characters which occur in delim.
27       If the end of the wide-character string is now  reached,  wcstok()  re‐
28       turns NULL, to indicate that no tokens were found, and stores an appro‐
29       priate value in *ptr, so that subsequent calls to  wcstok()  will  con‐
30       tinue  to return NULL.  Otherwise, the wcstok() function recognizes the
31       beginning of a token and returns a pointer  to  it,  but  before  doing
32       that, it zero-terminates the token by replacing the next wide-character
33       which occurs in delim with a null wide character (L'\0'),  and  it  up‐
34       dates  *ptr  so that subsequent calls will continue searching after the
35       end of recognized token.
36

RETURN VALUE

38       The wcstok() function returns a pointer to the next token, or  NULL  if
39       no further token was found.
40

ATTRIBUTES

42       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
43       tributes(7).
44
45       ┌────────────────────────────────────────────┬───────────────┬─────────┐
46       │Interface                                   │ Attribute     │ Value   │
47       ├────────────────────────────────────────────┼───────────────┼─────────┤
48       │wcstok()                                    │ Thread safety │ MT-Safe │
49       └────────────────────────────────────────────┴───────────────┴─────────┘
50

STANDARDS

52       C11, POSIX.1-2008.
53

HISTORY

55       POSIX.1-2001, C99.
56

NOTES

58       The original wcs wide-character string is destructively modified during
59       the operation.
60

EXAMPLES

62       The  following code loops over the tokens contained in a wide-character
63       string.
64
65       wchar_t *wcs = ...;
66       wchar_t *token;
67       wchar_t *state;
68       for (token = wcstok(wcs, L" \t\n", &state);
69           token != NULL;
70           token = wcstok(NULL, L" \t\n", &state)) {
71           ...
72       }
73