Debian Codegraph @

upstream/debian-trixie/man3/strtok.3

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