Debian Codegraph @

upstream/mageia-cauldron/man3/strtok.3

raw
1 '\" t
2 .\" Copyright 2005-2013, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH strtok 3 2026-02-08 "Linux man-pages 6.17"
8 .SH NAME
9 strtok, strtok_r \- extract tokens from strings
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <string.h>
16 .P
17 .BI "char *strtok(char *_Nullable restrict " str \
18 ", const char *restrict " delim );
19 .BI "char *strtok_r(char *_Nullable restrict " str \
20 ", const char *restrict " delim ,
21 .BI " char **restrict " saveptr );
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR strtok_r ():
30 .nf
31 _POSIX_C_SOURCE
32 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
33 .fi
34 .SH DESCRIPTION
35 The
36 .BR strtok ()
37 function breaks a string into a sequence of zero or more nonempty tokens.
38 On the first call to
39 .BR strtok (),
40 the string to be parsed should be
41 specified in
42 .IR str .
43 In each subsequent call that should parse the same string,
44 .I str
45 must be NULL.
46 .P
47 The
48 .I delim
49 argument specifies a set of bytes that
50 delimit the tokens in the parsed string.
51 The caller may specify different strings in
52 .I delim
53 in successive
54 calls that parse the same string.
55 .P
56 Each call to
57 .BR strtok ()
58 returns a pointer to a
59 null-terminated string containing the next token.
60 This string does not include the delimiting byte.
61 If no more tokens are found,
62 .BR strtok ()
63 returns NULL.
64 .P
65 A sequence of calls to
66 .BR strtok ()
67 that operate on the same string maintains a pointer
68 that determines the point from which to start searching for the next token.
69 The first call to
70 .BR strtok ()
71 sets this pointer to point to the first byte of the string.
72 The start of the next token is determined by scanning forward
73 for the next nondelimiter byte in
74 .IR str .
75 If such a byte is found, it is taken as the start of the next token.
76 If no such byte is found,
77 then there are no more tokens, and
78 .BR strtok ()
79 returns NULL.
80 (A string that is empty or that contains only delimiters
81 will thus cause
82 .BR strtok ()
83 to return NULL on the first call.)
84 .P
85 The end of each token is found by scanning forward until either
86 the next delimiter byte is found or until the
87 terminating null byte (\[aq]\[rs]0\[aq]) is encountered.
88 If a delimiter byte is found, it is overwritten with
89 a null byte to terminate the current token, and
90 .BR strtok ()
91 saves a pointer to the following byte;
92 that pointer will be used as the starting point
93 when searching for the next token.
94 In this case,
95 .BR strtok ()
96 returns a pointer to the start of the found token.
97 .P
98 From the above description,
99 it follows that a sequence of two or more contiguous delimiter bytes in
100 the parsed string is considered to be a single delimiter, and that
101 delimiter bytes at the start or end of the string are ignored.
102 Put another way: the tokens returned by
103 .BR strtok ()
104 are always nonempty strings.
105 Thus, for example, given the string
106 .RI \[dq] aaa;;bbb, \[dq],
107 successive calls to
108 .BR strtok ()
109 that specify the delimiter string
110 .RI \[dq] ;, \[dq]
111 would return the strings
112 .RI \[dq] aaa \[dq]
113 and
114 .RI \[dq] bbb \[dq],
115 and then a null pointer.
116 .P
117 The
118 .BR strtok_r ()
119 function is a reentrant version of
120 .BR strtok ().
121 The
122 .I saveptr
123 argument is a pointer to a
124 .I char\~*
125 variable that is used internally by
126 .BR strtok_r ()
127 in order to maintain context between successive calls that parse the
128 same string.
129 .P
130 On the first call to
131 .BR strtok_r (),
132 .I str
133 should point to the string to be parsed, and the value of
134 .I *saveptr
135 is ignored (but see VERSIONS).
136 In subsequent calls,
137 .I str
138 should be NULL, and
139 .I saveptr
140 (and the buffer that it points to)
141 should be unchanged since the previous call.
142 .P
143 Different strings may be parsed concurrently using sequences of calls to
144 .BR strtok_r ()
145 that specify different
146 .I saveptr
147 arguments.
148 .SH RETURN VALUE
149 The
150 .BR strtok ()
151 and
152 .BR strtok_r ()
153 functions return a pointer to
154 the next token, or NULL if there are no more tokens.
155 .SH ATTRIBUTES
156 For an explanation of the terms used in this section, see
157 .BR attributes (7).
158 .TS
159 allbox;
160 lbx lb lb
161 l l l.
162 Interface Attribute Value
163 T{
164 .na
165 .nh
166 .BR strtok ()
167 T} Thread safety MT-Unsafe race:strtok
168 T{
169 .na
170 .nh
171 .BR strtok_r ()
172 T} Thread safety MT-Safe
173 .TE
174 .SH VERSIONS
175 On some implementations,
176 .\" Tru64, according to its manual page
177 .I *saveptr
178 is required to be NULL on the first call to
179 .BR strtok_r ()
180 that is being used to parse
181 .IR str .
182 .SH STANDARDS
183 .TP
184 .BR strtok ()
185 C11, POSIX.1-2008.
186 .TP
187 .BR strtok_r ()
188 POSIX.1-2008.
189 .SH HISTORY
190 .TP
191 .BR strtok ()
192 POSIX.1-2001, C89, SVr4, 4.3BSD.
193 .TP
194 .BR strtok_r ()
195 POSIX.1-2001.
196 .SH BUGS
197 Be cautious when using these functions.
198 If you do use them, note that:
199 .IP \[bu] 3
200 These functions modify their first argument.
201 .IP \[bu]
202 These functions cannot be used on constant strings.
203 .IP \[bu]
204 The identity of the delimiting byte is lost.
205 .IP \[bu]
206 The
207 .BR strtok ()
208 function uses a static buffer while parsing, so it's not thread safe.
209 Use
210 .BR strtok_r ()
211 if this matters to you.
212 .SH EXAMPLES
213 The program below uses nested loops that employ
214 .BR strtok_r ()
215 to break a string into a two-level hierarchy of tokens.
216 The first command-line argument specifies the string to be parsed.
217 The second argument specifies the delimiter byte(s)
218 to be used to separate that string into "major" tokens.
219 The third argument specifies the delimiter byte(s)
220 to be used to separate the "major" tokens into subtokens.
221 .P
222 An example of the output produced by this program is the following:
223 .P
224 .in +4n
225 .EX
226 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
227 1: a/bbb///cc
228 \-\-> a
229 \-\-> bbb
230 \-\-> cc
231 2: xxx
232 \-\-> xxx
233 3: yyy
234 \-\-> yyy
235 .EE
236 .in
237 .SS Program source
238 \&
239 .\" SRC BEGIN (strtok.c)
240 .EX
241 #include <stdio.h>
242 #include <stdlib.h>
243 #include <string.h>
244 \&
245 int
246 main(int argc, char *argv[])
247 {
248 char *str1, *str2, *token, *subtoken;
249 char *saveptr1, *saveptr2;
250 int j;
251 \&
252 if (argc != 4) {
253 fprintf(stderr, "Usage: %s string delim subdelim\[rs]n",
254 argv[0]);
255 exit(EXIT_FAILURE);
256 }
257 \&
258 for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
259 token = strtok_r(str1, argv[2], &saveptr1);
260 if (token == NULL)
261 break;
262 printf("%d: %s\[rs]n", j, token);
263 \&
264 for (str2 = token; ; str2 = NULL) {
265 subtoken = strtok_r(str2, argv[3], &saveptr2);
266 if (subtoken == NULL)
267 break;
268 printf("\[rs]t \-\-> %s\[rs]n", subtoken);
269 }
270 }
271 \&
272 exit(EXIT_SUCCESS);
273 }
274 .EE
275 .\" SRC END
276 .P
277 Another example program using
278 .BR strtok ()
279 can be found in
280 .BR getaddrinfo_a (3).
281 .SH SEE ALSO
282 .BR memchr (3),
283 .BR strchr (3),
284 .BR string (3),
285 .BR strpbrk (3),
286 .BR strsep (3),
287 .BR strspn (3),
288 .BR strstr (3),
289 .BR wcstok (3)