]>
Commit | Line | Data |
---|---|---|
616c2730 | 1 | .\" Copyright (C) 2005, 2013 Michael Kerrisk <mtk.manpages@gmail.com> |
ff452e0d MK |
2 | .\" a few fragments from an earlier (1996) version by |
3 | .\" Andries Brouwer (aeb@cwi.nl) remain. | |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Rewritten old page, 960210, aeb@cwi.nl | |
e00c3a07 | 28 | .\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier <nick@debian.org> |
87cee315 | 29 | .\" 2005-11-17, mtk: Substantial parts rewritten |
ff452e0d | 30 | .\" 2013-05-19, mtk: added much further detail on the operation of strtok() |
87cee315 | 31 | .\" |
4b8c67d9 | 32 | .TH STRTOK 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
33 | .SH NAME |
34 | strtok, strtok_r \- extract tokens from strings | |
35 | .SH SYNOPSIS | |
36 | .nf | |
37 | .B #include <string.h> | |
68e4db0a | 38 | .PP |
87cee315 | 39 | .BI "char *strtok(char *" str ", const char *" delim ); |
68e4db0a | 40 | .PP |
87cee315 | 41 | .BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr ); |
fea681da | 42 | .fi |
68e4db0a | 43 | .PP |
cc4615cc MK |
44 | .in -4n |
45 | Feature Test Macro Requirements for glibc (see | |
46 | .BR feature_test_macros (7)): | |
47 | .in | |
68e4db0a | 48 | .PP |
cc4615cc MK |
49 | .ad l |
50 | .BR strtok_r (): | |
d59161f9 MK |
51 | _POSIX_C_SOURCE |
52 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
cc4615cc | 53 | .ad b |
fea681da | 54 | .SH DESCRIPTION |
60a90ecd MK |
55 | The |
56 | .BR strtok () | |
ff452e0d | 57 | function breaks a string into a sequence of zero or more nonempty tokens. |
60a90ecd | 58 | On the first call to |
6b8b0e50 | 59 | .BR strtok (), |
60a90ecd | 60 | the string to be parsed should be |
46d8df8e MK |
61 | specified in |
62 | .IR str . | |
c13182ef | 63 | In each subsequent call that should parse the same string, |
46d8df8e MK |
64 | .I str |
65 | must be NULL. | |
847e0d88 | 66 | .PP |
46d8df8e MK |
67 | The |
68 | .I delim | |
69 | argument specifies a set of bytes that | |
87cee315 | 70 | delimit the tokens in the parsed string. |
46d8df8e MK |
71 | The caller may specify different strings in |
72 | .I delim | |
73 | in successive | |
87cee315 | 74 | calls that parse the same string. |
847e0d88 | 75 | .PP |
60a90ecd MK |
76 | Each call to |
77 | .BR strtok () | |
78 | returns a pointer to a | |
87cee315 | 79 | null-terminated string containing the next token. |
a00b7454 | 80 | This string does not include the delimiting byte. |
60a90ecd MK |
81 | If no more tokens are found, |
82 | .BR strtok () | |
83 | returns NULL. | |
847e0d88 | 84 | .PP |
ff452e0d MK |
85 | A sequence of calls to |
86 | .BR strtok () | |
87 | that operate on the same string maintains a pointer | |
88 | that determines the point from which to start searching for the next token. | |
89 | The first call to | |
90 | .BR strtok () | |
91 | sets this pointer to point to the first byte of the string. | |
51700fd7 | 92 | The start of the next token is determined by scanning forward |
ff452e0d MK |
93 | for the next nondelimiter byte in |
94 | .IR str . | |
95 | If such a byte is found, it is taken as the start of the next token. | |
96 | If no such byte is found, | |
97 | then there are no more tokens, and | |
98 | .BR strtok () | |
99 | returns NULL. | |
89b85ead | 100 | (A string that is empty or that contains only delimiters |
ff452e0d MK |
101 | will thus cause |
102 | .BR strtok () | |
103 | to return NULL on the first call.) | |
847e0d88 | 104 | .PP |
ff452e0d MK |
105 | The end of each token is found by scanning forward until either |
106 | the next delimiter byte is found or until the | |
107 | terminating null byte (\(aq\\0\(aq) is encountered. | |
108 | If a delimiter byte is found, it is overwritten with | |
109 | a null byte to terminate the current token, and | |
110 | .BR strtok () | |
111 | saves a pointer to the following byte; | |
112 | that pointer will be used as the starting point | |
113 | when searching for the next token. | |
114 | In this case, | |
115 | .BR strtok () | |
116 | returns a pointer to the start of the found token. | |
847e0d88 | 117 | .PP |
ff452e0d MK |
118 | From the above description, |
119 | it follows that a sequence of two or more contiguous delimiter bytes in | |
120 | the parsed string is considered to be a single delimiter, and that | |
121 | delimiter bytes at the start or end of the string are ignored. | |
60a90ecd MK |
122 | Put another way: the tokens returned by |
123 | .BR strtok () | |
aa796481 | 124 | are always nonempty strings. |
ff452e0d MK |
125 | Thus, for example, given the string "\fIaaa;;bbb,\fP", |
126 | successive calls to | |
127 | .BR strtok () | |
51700fd7 | 128 | that specify the delimiter string "\fI;,\fP" |
ff452e0d | 129 | would return the strings "\fIaaa\fP" and "\fIbbb\fP", |
b437fdd9 | 130 | and then a null pointer. |
847e0d88 | 131 | .PP |
c13182ef | 132 | The |
87cee315 MK |
133 | .BR strtok_r () |
134 | function is a reentrant version | |
135 | .BR strtok (). | |
46d8df8e MK |
136 | The |
137 | .I saveptr | |
138 | argument is a pointer to a | |
139 | .IR "char\ *" | |
140 | variable that is used internally by | |
87cee315 MK |
141 | .BR strtok_r () |
142 | in order to maintain context between successive calls that parse the | |
143 | same string. | |
847e0d88 | 144 | .PP |
c13182ef | 145 | On the first call to |
87cee315 MK |
146 | .BR strtok_r (), |
147 | .I str | |
c13182ef | 148 | should point to the string to be parsed, and the value of |
87cee315 MK |
149 | .I saveptr |
150 | is ignored. | |
46d8df8e MK |
151 | In subsequent calls, |
152 | .I str | |
153 | should be NULL, and | |
154 | .I saveptr | |
155 | should be unchanged since the previous call. | |
847e0d88 | 156 | .PP |
87cee315 MK |
157 | Different strings may be parsed concurrently using sequences of calls to |
158 | .BR strtok_r () | |
46d8df8e MK |
159 | that specify different |
160 | .I saveptr | |
161 | arguments. | |
47297adb | 162 | .SH RETURN VALUE |
2b2581ee MK |
163 | The |
164 | .BR strtok () | |
165 | and | |
166 | .BR strtok_r () | |
167 | functions return a pointer to | |
168 | the next token, or NULL if there are no more tokens. | |
32208956 | 169 | .SH ATTRIBUTES |
4d22c42d PH |
170 | For an explanation of the terms used in this section, see |
171 | .BR attributes (7). | |
172 | .TS | |
173 | allbox; | |
174 | lb lb lb | |
175 | l l l. | |
176 | Interface Attribute Value | |
177 | T{ | |
32208956 | 178 | .BR strtok () |
05e8fa8f | 179 | T} Thread safety MT-Unsafe race:strtok |
4d22c42d | 180 | T{ |
32208956 | 181 | .BR strtok_r () |
4d22c42d PH |
182 | T} Thread safety MT-Safe |
183 | .TE | |
47297adb | 184 | .SH CONFORMING TO |
2b2581ee MK |
185 | .TP |
186 | .BR strtok () | |
3546ed98 | 187 | POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. |
2b2581ee MK |
188 | .TP |
189 | .BR strtok_r () | |
3546ed98 | 190 | POSIX.1-2001, POSIX.1-2008. |
2b2581ee | 191 | .SH BUGS |
132719a5 | 192 | Be cautious when using these functions. |
2b2581ee | 193 | If you do use them, note that: |
7bb33c46 | 194 | .IP * 2 |
2b2581ee | 195 | These functions modify their first argument. |
7bb33c46 | 196 | .IP * |
2b2581ee | 197 | These functions cannot be used on constant strings. |
7bb33c46 | 198 | .IP * |
a00b7454 | 199 | The identity of the delimiting byte is lost. |
7bb33c46 | 200 | .IP * |
2b2581ee MK |
201 | The |
202 | .BR strtok () | |
203 | function uses a static buffer while parsing, so it's not thread safe. | |
204 | Use | |
205 | .BR strtok_r () | |
206 | if this matters to you. | |
9b336505 | 207 | .SH EXAMPLE |
a831ef97 | 208 | The program below uses nested loops that employ |
87cee315 MK |
209 | .BR strtok_r () |
210 | to break a string into a two-level hierarchy of tokens. | |
211 | The first command-line argument specifies the string to be parsed. | |
a00b7454 | 212 | The second argument specifies the delimiter byte(s) |
87cee315 | 213 | to be used to separate that string into "major" tokens. |
a00b7454 | 214 | The third argument specifies the delimiter byte(s) |
87cee315 | 215 | to be used to separate the "major" tokens into subtokens. |
fea681da | 216 | .PP |
a831ef97 MK |
217 | An example of the output produced by this program is the following: |
218 | .PP | |
219 | .in +4n | |
b8302363 | 220 | .EX |
a831ef97 MK |
221 | .RB "$" " ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq" |
222 | 1: a/bbb///cc | |
223 | \-\-> a | |
224 | \-\-> bbb | |
225 | \-\-> cc | |
226 | 2: xxx | |
227 | \-\-> xxx | |
228 | 3: yyy | |
229 | \-\-> yyy | |
b8302363 | 230 | .EE |
a831ef97 MK |
231 | .in |
232 | .SS Program source | |
d84d0300 | 233 | \& |
e7d0bb47 | 234 | .EX |
87cee315 MK |
235 | #include <stdio.h> |
236 | #include <stdlib.h> | |
237 | #include <string.h> | |
238 | ||
239 | int | |
240 | main(int argc, char *argv[]) | |
241 | { | |
242 | char *str1, *str2, *token, *subtoken; | |
243 | char *saveptr1, *saveptr2; | |
244 | int j; | |
245 | ||
246 | if (argc != 4) { | |
c13182ef | 247 | fprintf(stderr, "Usage: %s string delim subdelim\\n", |
87cee315 MK |
248 | argv[0]); |
249 | exit(EXIT_FAILURE); | |
c13182ef | 250 | } |
87cee315 MK |
251 | |
252 | for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) { | |
253 | token = strtok_r(str1, argv[2], &saveptr1); | |
254 | if (token == NULL) | |
255 | break; | |
39ad75ab | 256 | printf("%d: %s\\n", j, token); |
87cee315 MK |
257 | |
258 | for (str2 = token; ; str2 = NULL) { | |
259 | subtoken = strtok_r(str2, argv[3], &saveptr2); | |
260 | if (subtoken == NULL) | |
261 | break; | |
29059a65 | 262 | printf("\t \-\-> %s\\n", subtoken); |
c13182ef MK |
263 | } |
264 | } | |
87cee315 MK |
265 | |
266 | exit(EXIT_SUCCESS); | |
c54ed37e | 267 | } |
e7d0bb47 | 268 | .EE |
f91b1db0 PB |
269 | .PP |
270 | Another example program using | |
271 | .BR strtok () | |
272 | can be found in | |
273 | .BR getaddrinfo_a (3). | |
47297adb | 274 | .SH SEE ALSO |
fea681da MK |
275 | .BR index (3), |
276 | .BR memchr (3), | |
277 | .BR rindex (3), | |
278 | .BR strchr (3), | |
d095200e | 279 | .BR string (3), |
fea681da MK |
280 | .BR strpbrk (3), |
281 | .BR strsep (3), | |
282 | .BR strspn (3), | |
1709027c MK |
283 | .BR strstr (3), |
284 | .BR wcstok (3) |