wcstok.3p (4145B)
- '\" et
- .TH WCSTOK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .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
- \(em split a wide-character string into tokens
- .SH SYNOPSIS
- .LP
- .nf
- #include <wchar.h>
- .P
- wchar_t *wcstok(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP,
- wchar_t **restrict \fIptr\fP);
- .fi
- .SH DESCRIPTION
- 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\(hy2017 defers to the ISO\ C standard.
- .P
- A sequence of calls to
- \fIwcstok\fR()
- shall break the wide-character string pointed to by
- .IR 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
- .IR ws2 .
- The
- .IR ptr
- argument points to a caller-provided
- .BR wchar_t
- pointer into which the
- \fIwcstok\fR()
- function shall store information necessary for it to continue
- scanning the same wide-character string.
- .P
- The first call in the sequence has
- .IR ws1
- as its first argument, and is followed by calls with a null pointer as
- their first argument. The separator string pointed to by
- .IR ws2
- may be different from call to call.
- .P
- The first call in the sequence shall search the wide-character string
- pointed to by
- .IR ws1
- for the first wide-character code that is
- .IR not
- contained in the current separator string pointed to by
- .IR ws2 .
- If no such wide-character code is found, then there are no tokens in
- the wide-character string pointed to by
- .IR ws1
- and
- \fIwcstok\fR()
- shall return a null pointer. If such a wide-character code is found,
- it shall be the start of the first token.
- .P
- The
- \fIwcstok\fR()
- function shall then search from there for a wide-character code that
- .IR 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
- .IR 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
- \fIwcstok\fR()
- function shall save a pointer to the following wide-character code,
- from which the next search for a token shall start.
- .P
- 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.
- .P
- The implementation shall behave as if no function calls
- \fIwcstok\fR().
- .SH "RETURN VALUE"
- Upon successful completion, the
- \fIwcstok\fR()
- function shall return a pointer to the first wide-character code of a
- token. Otherwise, if there is no token,
- \fIwcstok\fR()
- shall return a null pointer.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<wchar.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .