WCSTOK(3P)

💖 WCSTOK(3P) — POSIX Programmer's Manual 💖

okay bestie, we're doing a POSIX page today, WCSTOK(3P), straight out of the POSIX Programmer's Manual. buckle up, this one's actually kinda fun once you get the vibe ✨

---

🌸 PROLOG 🌸

so real talk first: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so like, consult the corresponding Linux manual page for the deets on Linux behavior — or honestly the interface may not even be implemented on Linux at all. 🙈

---

✨ 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 🦋

okay so first things first, everything described on this reference page is aligned with the ISO C standard. If there's any conflict between what's written here and the ISO C standard, that conflict is unintentional — no cap. This volume of POSIX.1‐2017 defers to the ISO C standard. periodt.

A sequence of calls to wcstok() shall break the wide-character string pointed to by ws1 into a sequence of tokens, and each of those tokens 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, and that's where wcstok() shall store the information it needs so it can keep scanning the same wide-character string later. it's giving "state, but you hold it."

The first call in the sequence has ws1 as its first argument, and then it's followed by calls with a null pointer as their first argument. Also — and this is lowkey important — the separator string pointed to by ws2 may be different from call to call. the vibes can change mid-scan, iconic. 🌈

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. But if such a wide-character code is found? that's the start of the first token, bestie. main character energy fr fr. 👑

Then wcstok() shall 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 all the way to the end of the wide-character string pointed to by ws1, and subsequent searches for a token shall return a null pointer. But if such a wide-character code is found, it shall be overwritten by a null wide character, which terminates the current token. 😭 (yes, it really just writes over your string like that. that's the whole bit.) Then wcstok() shall save a pointer to the following wide-character code, and that's where the next search for a token shall start. so organized.

Each subsequent call, with a null pointer as the value of the first argument, shall start searching from that saved pointer and behave exactly as described above. same energy, new starting point. 💫

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

---

💜 RETURN VALUE 💜

Upon successful completion, wcstok() 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. that's it, that's the tea.

---

🍓 ERRORS 🍓

No errors are defined. 🎀

The following sections are informative. (iykyk)

---

🧚 EXAMPLES 🧚

None. 🙈

---

🌸 APPLICATION USAGE 🌸

None. 💀

---

⭐ RATIONALE ⭐

None. 🫶

---

🔥 FUTURE DIRECTIONS 🔥

None. ✨

---

🌈 SEE ALSO 🌈

• The Base Definitions volume of POSIX.1‐2017, <wchar.h>

---

👑 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 .

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 .

---

and that's the whole page bestie!! 🎀💖 this one was brought to you by IEEE/The Open Group, dated 2017, filed under WCSTOK(3P) — go forth and tokenize responsibly, mwah 💅✨🦋