| .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
| .\" |
| .\" 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. |
| .\" |
| .\" 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 1999-07-25 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| wcstok \- split wide-character string into tokens |
| .SH SYNOPSIS |
| .nf |
| .B #include <wchar.h> |
| .sp |
| .BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim ", wchar_t **" ptr ); |
| .fi |
| .SH DESCRIPTION |
| The \fBwcstok\fP() function is the wide-character equivalent of the \fBstrtok\fP() |
| function, with an added argument to make it multithread-safe. It can be used |
| to split a wide-character string \fIwcs\fP into tokens, where a token is |
| defined as a substring not containing any wide-characters from \fIdelim\fP. |
| .PP |
| The search starts at \fIwcs\fP, if \fIwcs\fP is not NULL, or at \fI*ptr\fP, if |
| \fIwcs\fP is NULL. First, any delimiter wide-characters are skipped, i.e. the |
| pointer is advanced beyond any wide-characters which occur in \fIdelim\fP. |
| If the end of the wide-character string is now reached, \fBwcstok\fP() returns |
| NULL, to indicate that no tokens were found, and stores an appropriate value |
| in \fI*ptr\fP, so that subsequent calls to \fBwcstok\fP() will continue to return |
| NULL. Otherwise, the \fBwcstok\fP() 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 \fIdelim\fP with |
| a L'\\0' character, and it updates \fI*ptr\fP so that subsequent calls will |
| continue searching after the end of recognized token. |
| .SH "RETURN VALUE" |
| The \fBwcstok\fP() function returns a pointer to the next token, or NULL if no |
| further token was found. |
| .SH NOTES |
| The original \fIwcs\fP wide-character string is destructively modified during |
| the operation. |
| .SH EXAMPLE |
| The following code loops over the tokens contained in a wide-character string. |
| .sp |
| .nf |
| wchar_t *wcs = ...; |
| wchar_t *token; |
| wchar_t *state; |
| for (token = wcstok(wcs, " \\t\\n", &state); |
| token != NULL; |
| token = wcstok(NULL, " \\t\\n", &state)) { |
| ... |
| } |
| .fi |
| .SH "CONFORMING TO" |
| ISO/ANSI C, UNIX98 |
| .SH "SEE ALSO" |
| .BR strtok (3), |
| .BR wcschr (3) |