Guardian Native C Library Calls Reference Manual (G06.28+, H06.05+)

Guardian Native C Library Calls (t - z) wcstok(3)
NAME
wcstok - Splits wide-character strings into tokens
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL
G-series native OSS processes: /G/system/sysnn/zcrtlsrl
H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
H-series OSS processes: /G/system/zdllnnn/zcrtldll
SYNOPSIS
#include <wchar.h>
wchar_t *wcstok(
wchar_t *ws1,
const wchar_t *ws2);
PARAMETERS
ws1 Contains a pointer to the wide-character string that is to be searched.
ws2 Contains a pointer to the string of wide-character token delimiters.
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. The first time the application program calls the wcstok() function, it sets the ws1 parame-
ter to point to the input wide-character string. The function returns a pointer to the first token.
Then 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
was returned.
In 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 del-
imiter 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 delimiter 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 following the null wide character and returns a pointer to the start of
the token.
In the subsequent calls to wcstok(), in which the ws1 parameter is set to the null pointer, the
function starts at its 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()
function saves a pointer to the wide character following the null wide character and returns a
pointer to the start of the new token.
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 character that does occur in the delimiter string, the current token extends to the end of the
string and subsequent calls to wcstok() will 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 program can set the second parameter, ws2, to different wide-
527192-007 Hewlett-Packard Company 7−75