.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "WCSTOK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" wcstok 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
wcstok \- split a wide-character string into tokens
.SH SYNOPSIS
.LP
\fB#include <wchar.h>
.br
.sp
wchar_t *wcstok(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t *restrict\fP
\fIws2\fP\fB,
.br
\ \ \ \ \ \  wchar_t **restrict\fP \fIptr\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
A sequence of calls to \fIwcstok\fP() shall break the wide-character
string pointed to by \fIws1\fP into a sequence of tokens,
each of which shall be delimited by a wide-character code from the
wide-character string pointed to by \fIws2\fP. The \fIptr\fP
argument points to a caller-provided \fBwchar_t\fP pointer into which
the \fIwcstok\fP() function shall store information
necessary for it to continue scanning the same wide-character string.
.LP
The first call in the sequence has \fIws1\fP as its first argument,
and is followed by calls with a null pointer as their first
argument. The separator string pointed to by \fIws2\fP may be different
from call to call.
.LP
The first call in the sequence shall search the wide-character string
pointed to by \fIws1\fP for the first wide-character code
that is \fInot\fP contained in the current separator string pointed
to by \fIws2\fP. If no such wide-character code is found,
then there are no tokens in the wide-character string pointed to by
\fIws1\fP and \fIwcstok\fP() shall return a null pointer. If
such a wide-character code is found, it shall be the start of the
first token.
.LP
The \fIwcstok\fP() function shall then search from there for a wide-character
code that \fIis\fP 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 \fIws1\fP, 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 \fIwcstok\fP() function shall save a
pointer to the following wide-character code, from which the next
search for a token shall start.
.LP
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.
.LP
The implementation shall behave as if no function calls \fIwcstok\fP().
.SH RETURN VALUE
.LP
Upon successful completion, the \fIwcstok\fP() function shall return
a pointer to the first wide-character code of a token.
Otherwise, if there is no token, \fIwcstok\fP() shall return a null
pointer.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<wchar.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .