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