| .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" %%%LICENSE_END |
| .\" |
| .\" References consulted: |
| .\" GNU glibc-2 source code and manual |
| .\" Dinkumware C library reference http://www.dinkumware.com/ |
| .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
| .\" ISO/IEC 9899:1999 |
| .\" |
| .TH WCSTOK 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| wcstok \- split wide-character string into tokens |
| .SH SYNOPSIS |
| .nf |
| .B #include <wchar.h> |
| .PP |
| .BI "wchar_t *wcstok(wchar_t *restrict " wcs \ |
| ", const wchar_t *restrict " delim , |
| .BI " wchar_t **restrict " ptr ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR wcstok () |
| function is the wide-character equivalent of the |
| .BR strtok (3) |
| function, |
| with an added argument to make it multithread-safe. |
| It can be used |
| to split a wide-character string |
| .I wcs |
| into tokens, where a token is |
| defined as a substring not containing any wide-characters from |
| .IR delim . |
| .PP |
| The search starts at |
| .IR wcs , |
| if |
| .I wcs |
| is not NULL, |
| or at |
| .IR *ptr , |
| if |
| .I wcs |
| is NULL. |
| First, any delimiter wide-characters are skipped, that is, the |
| pointer is advanced beyond any wide-characters which occur in |
| .IR delim . |
| If the end of the wide-character string is now |
| reached, |
| .BR wcstok () |
| returns NULL, to indicate that no tokens |
| were found, and stores an appropriate value in |
| .IR *ptr , |
| so that subsequent calls to |
| .BR wcstok () |
| will continue to return NULL. |
| Otherwise, the |
| .BR 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 |
| .I delim |
| with |
| a null wide character (L\(aq\e0\(aq), |
| and it updates |
| .I *ptr |
| so that subsequent calls will |
| continue searching after the end of recognized token. |
| .SH RETURN VALUE |
| The |
| .BR wcstok () |
| function returns a pointer to the next token, |
| or NULL if no further token was found. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR wcstok () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, C99. |
| .SH NOTES |
| The original |
| .I wcs |
| wide-character string is destructively modified during |
| the operation. |
| .SH EXAMPLES |
| The following code loops over the tokens contained in a wide-character string. |
| .PP |
| .EX |
| wchar_t *wcs = ...; |
| wchar_t *token; |
| wchar_t *state; |
| for (token = wcstok(wcs, " \et\en", &state); |
| token != NULL; |
| token = wcstok(NULL, " \et\en", &state)) { |
| ... |
| } |
| .EE |
| .SH SEE ALSO |
| .BR strtok (3), |
| .BR wcschr (3) |
