wcstok(3)wcstok(3)NAME
wcstok, wcstok_r - Split wide-character strings into tokens
SYNOPSIS
wchar_t *wcstok(
wchar_t *ws1,
const wchar_t *ws2,
wchar_t **savept );
This prototype conforms to both ISO C and XSH Issue 5 and is strongly
recommended for new applications. The wcstok() function supported in
compilation environments for XSH versions earlier than XSH Issue 5 does
not include the savept parameter, which is required for threadsafe
operation. The following proprietary prototype is the threadsafe inter‐
face that was supported on Tru64 UNIX versions prior to Version 4.0 and
is supported only to provide backward compatibility for applications
written before the ISO C and XSH5 threadsafe prototype was available.
wchar_t *wcstok_r(
wchar_t *ws1,
const wchar_t *ws2,
wchar_t **savept );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
wcstok(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Contains a pointer to the wide-character string to be searched. Con‐
tains a pointer to the string of wide-character token delimiters.
Identifies the location of the wide character where the search for
tokens should be started in the next call. The savept parameter con‐
tains a pointer to a variable that contains a pointer to the wide char‐
acter where scanning begins.
DESCRIPTION
The wcstok() function splits the wide-character string pointed to by
the ws1 parameter into a sequence of tokens, each of which is delimited
by a wide character from the wide-character string pointed to by the
ws2 parameter.
Usually, the wcstok() function is called repeatedly to extract the
tokens in a wide-character string. On the first call to the wcstok()
function, the application sets the ws1 parameter to point to the input
wide-character string. The function returns a pointer to the first
token.
The application program calls the function again with the ws1 parameter
set to the null pointer. This call returns a pointer to the next token
in the string. The application program repeats the call to wcstok()
with the ws1 parameter set to the null pointer until all the tokens in
the string have been returned.
On the initial call to wcstok(), the function first searches the wide-
character string pointed to by the ws1 parameter to locate the first
wide character that does not occur in the wide-character delimiter
string pointed to by the ws2 parameter. If such a wide character is
found, it is the start of the first token. The wcstok() function then
searches from there for a wide character that does occur in the delim‐
iter string. If such a wide-character delimiter is found, wcstok()
overwrites it with a null wide character, which terminates the current
token. The wcstok() function saves a pointer to the wide character fol‐
lowing the null wide character and returns a pointer to the start of
the token.
In subsequent calls to wcstok(), where ws1 is set to a null pointer,
the function starts at the saved pointer and searches for the next wide
character that does not occur in the wide-character delimiter string
pointed to by the ws2 parameter. If such a wide character is found, it
is the start of the new token. The wcstok() function then searches from
there for a wide character that does occur in the delimiter string. If
such a wide-character delimiter is found, wcstok() overwrites it with a
null wide character, which terminates the new token. The wcstok() func‐
tion saves a pointer to the wide character following the null wide
character and returns a pointer to the start of the new token. It
stores the saved pointer in the *savept parameter as well as inter‐
nally. On calls where the s1 parameter is a null pointer, the function
uses the saved pointer in *savept to start searching for the next
token. Applications that require threadsafe operation must use a
wcstok() interface that includes the savept parameter.
If a call to the wcstok() function cannot find a wide character that
does not occur in the delimiter string, it returns the null pointer. If
a call to the wcstok() function cannot find the terminating wide char‐
acter that does occur in the delimiter string, the current token
extends to the end of the string and subsequent calls to wcstok()
return the null pointer.
If the delimiters used in the wide-character string change from one set
of characters to another within the string, the application can set the
second parameter, ws2, to different wide-character strings from call to
call.
The implementation behaves as though no function calls the wcstok()
function.
RETURN VALUES
On successful completion, the wcstok() function returns a pointer to
the first wide character of a token. A null pointer is returned if
there is no token.
The wcstok() function also sets the pointer *savept to the wide charac‐
ter from which the search for the next token starts, or to a null
pointer if there is none.
EXAMPLES
The following example splits a wide-character string into tokens:
#include <wchar.h> #include <locale.h> #include <stdio.h> #define
WLENGTH 40
main() {
wchar_t WCString1[WLENGTH], delimiters[WLENGTH];
wchar_t * pwcs;
int counter;
(void)setlocale(LC_ALL," ");
printf("Enter the string to be searched: ");
if (fgetws(WCString1, WLENGTH, stdin) != NULL) {
printf("Enter the delimiter(s): ");
if (fgetws(delimiters, WLENGTH, stdin) \ != NULL) {
if ((pwcs = wcstok(WCString1, delimiters )) \ != NULL) {
/* pwcs points to the first token */
printf("Token 1 is %S\n", pwcs);
counter = 2;
while ((pwcs = wcstok((wchar_t * )NULL, delimiters )) \ !=
NULL) {
printf("Token %d is %S\n", counter, pwcs);
counter++;
}
}
}
} }
SEE ALSO
Functions: strtok(3), wcspbrk(3), wcsspn(3), wcstod(3), wcstol(3),
wcstoul(3)
Standards: standards(5)wcstok(3)
