Debian Codegraph @

upstream/debian-unstable/man3/wcstok.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH wcstok 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wcstok \- split wide-character string into tokens
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BI "wchar_t *wcstok(wchar_t *restrict " wcs \
18 ", const wchar_t *restrict " delim ,
19 .BI " wchar_t **restrict " ptr );
20 .fi
21 .SH DESCRIPTION
22 The
23 .BR wcstok ()
24 function is the wide-character equivalent of the
25 .BR strtok (3)
26 function,
27 with an added argument to make it multithread-safe.
28 It can be used
29 to split a wide-character string
30 .I wcs
31 into tokens, where a token is
32 defined as a substring not containing any wide-characters from
33 .IR delim .
34 .P
35 The search starts at
36 .IR wcs ,
37 if
38 .I wcs
39 is not NULL,
40 or at
41 .IR *ptr ,
42 if
43 .I wcs
44 is NULL.
45 First, any delimiter wide-characters are skipped, that is, the
46 pointer is advanced beyond any wide-characters which occur in
47 .IR delim .
48 If the end of the wide-character string is now
49 reached,
50 .BR wcstok ()
51 returns NULL, to indicate that no tokens
52 were found, and stores an appropriate value in
53 .IR *ptr ,
54 so that subsequent calls to
55 .BR wcstok ()
56 will continue to return NULL.
57 Otherwise, the
58 .BR wcstok ()
59 function recognizes the beginning of a token
60 and returns a pointer to it, but before doing that, it zero-terminates the
61 token by replacing the next wide-character which occurs in
62 .I delim
63 with
64 a null wide character (L\[aq]\[rs]0\[aq]),
65 and it updates
66 .I *ptr
67 so that subsequent calls will
68 continue searching after the end of recognized token.
69 .SH RETURN VALUE
70 The
71 .BR wcstok ()
72 function returns a pointer to the next token,
73 or NULL if no further token was found.
74 .SH ATTRIBUTES
75 For an explanation of the terms used in this section, see
76 .BR attributes (7).
77 .TS
78 allbox;
79 lbx lb lb
80 l l l.
81 Interface Attribute Value
82 T{
83 .na
84 .nh
85 .BR wcstok ()
86 T} Thread safety MT-Safe
87 .TE
88 .SH STANDARDS
89 C11, POSIX.1-2008.
90 .SH HISTORY
91 POSIX.1-2001, C99.
92 .SH NOTES
93 The original
94 .I wcs
95 wide-character string is destructively modified during
96 the operation.
97 .SH EXAMPLES
98 The following code loops over the tokens contained in a wide-character string.
99 .P
100 .EX
101 wchar_t *wcs = ...;
102 wchar_t *token;
103 wchar_t *state;
104 for (token = wcstok(wcs, L" \[rs]t\[rs]n", &state);
105 token != NULL;
106 token = wcstok(NULL, L" \[rs]t\[rs]n", &state)) {
107 ...
108 }
109 .EE
110 .SH SEE ALSO
111 .BR strtok (3),
112 .BR wcschr (3)