wcstok(3) — Linux manual page

wcstok(3)               Library Functions Manual               wcstok(3)

NAME

       wcstok - split wide-character string into tokens

LIBRARY

       Standard C library (libc, -lc)

SYNOPSIS

       #include <wchar.h>

       wchar_t *wcstok(wchar_t *restrict wcs, const wchar_t *restrict delim,
                       wchar_t **restrict ptr);

DESCRIPTION

       The wcstok() function is the wide-character equivalent of the
       strtok(3) function, with an added argument to make it
       multithread-safe.  It can be used to split a wide-character
       string wcs into tokens, where a token is defined as a substring
       not containing any wide-characters from delim.

       The search starts at wcs, if wcs is not NULL, or at *ptr, if wcs
       is NULL.  First, any delimiter wide-characters are skipped, that
       is, the pointer is advanced beyond any wide-characters which
       occur in delim.  If the end of the wide-character string is now
       reached, wcstok() returns NULL, to indicate that no tokens were
       found, and stores an appropriate value in *ptr, so that
       subsequent calls to wcstok() will continue to return NULL.
       Otherwise, the wcstok() function recognizes the beginning of a
       token and returns a pointer to it, but before doing that, it
       zero-terminates the token by replacing the next wide-character
       which occurs in delim with a null wide character (L'\0'), and it
       updates *ptr so that subsequent calls will continue searching
       after the end of recognized token.

RETURN VALUE

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

ATTRIBUTES

       For an explanation of the terms used in this section, see
       attributes(7).
       ┌─────────────────────────────────────┬───────────────┬─────────┐
       │ Interface                           │ Attribute     │ Value   │
       ├─────────────────────────────────────┼───────────────┼─────────┤
       │ wcstok()                            │ Thread safety │ MT-Safe │
       └─────────────────────────────────────┴───────────────┴─────────┘

STANDARDS

       C11, POSIX.1-2008.

HISTORY

       POSIX.1-2001, C99.

NOTES

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

EXAMPLES

       The following code loops over the tokens contained in a wide-
       character string.

       wchar_t *wcs = ...;
       wchar_t *token;
       wchar_t *state;
       for (token = wcstok(wcs, L" \t\n", &state);
           token != NULL;
           token = wcstok(NULL, L" \t\n", &state)) {
           ...
       }

SEE ALSO

       strtok(3), wcschr(3)

COLOPHON

       This page is part of the man-pages (Linux kernel and C library
       user-space interface documentation) project.  Information about
       the project can be found at 
       ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report
       for this manual page, see
       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
       This page was obtained from the tarball man-pages-6.9.1.tar.gz
       fetched from
       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
       2024-06-26.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-
       to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not
       part of the original manual page), send a mail to
       man-pages@man7.org

Linux man-pages 6.9.1          2024-06-15                      wcstok(3)

Pages that refer to this page: strtok(3), signal-safety(7)

---