The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> wcstok - split a wide-character string into tokens

#### SYNOPSIS

> ``#include <wchar.h>
> wchar_t *wcstok(wchar_t *restrict` ws1`, const wchar_t *restrict` ws2`,
> wchar_t **restrict` ptr`);
> ``

#### DESCRIPTION

> [CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2008 defers to the ISO C standard.

> A sequence of calls to wcstok() shall break the wide-character string pointed to by ws1 into a sequence of tokens, each of which shall be delimited by a wide-character code from the wide-character string pointed to by ws2. The ptr argument points to a caller-provided wchar_t pointer into which the wcstok() function shall store information necessary for it to continue scanning the same wide-character string.

> The first call in the sequence has ws1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by ws2 may be different from call to call.

> The first call in the sequence shall search the wide-character string pointed to by ws1 for the first wide-character code that is not contained in the current separator string pointed to by ws2. If no such wide-character code is found, then there are no tokens in the wide-character string pointed to by ws1 and wcstok() shall return a null pointer. If such a wide-character code is found, it shall be the start of the first token.

> The wcstok() function shall then search from there for a wide-character code that is contained in the current separator string. If no such wide-character code is found, the current token extends to the end of the wide-character string pointed to by ws1, and subsequent searches for a token shall return a null pointer. If such a wide-character code is found, it shall be overwritten by a null wide character, which terminates the current token. The wcstok() function shall save a pointer to the following wide-character code, from which the next search for a token shall start.

> Each subsequent call, with a null pointer as the value of the first argument, shall start searching from the saved pointer and behave as described above.

> The implementation shall behave as if no function calls wcstok().

#### RETURN VALUE

> Upon successful completion, the wcstok() function shall return a pointer to the first wide-character code of a token. Otherwise, if there is no token, wcstok() shall return a null pointer.

#### ERRORS

> No errors are defined.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> XBD <wchar.h>

#### CHANGE HISTORY

> First released in Issue 4.

#### Issue 5

> Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, a third argument is added to the definition of wcstok() in the SYNOPSIS.

#### Issue 6

> The wcstok() prototype is updated for alignment with the ISO/IEC 9899:1999 standard.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]