1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Portions Copyright (c) 1994 Man-cgi 1.15, Panagiotis Christias (christia@softlab.ntua.gr)
46 .\" Portions Copyright (c) 1996-2008 Modified for NetBSD by Kimmo Suominen (kimmo@suominen.com)
47 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
48 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
49 .\" Copyright (c) 2014, Joyent, Inc.
50 .\"
51 .TH STRING 3C "Mar 23, 2016"
52 .SH NAME
53 string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat, strncat,
54 strlcat, strchr, strchrnul, strrchr, strcmp, strncmp, stpcpy, stpncpy, strcpy,
55 strncpy, strlcpy, strcspn, strspn, strdup, strndup, strdupa, strndupa, strlen,
56 strnlen, strpbrk, strsep, strstr, strnstr, strcasestr, strtok, strtok_r \-
57 string operations
58 .SH SYNOPSIS
59 .LP
60 .nf
61 #include <strings.h>
62
63 \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
64 .fi
65 .LP
66 .nf
67 \fBint\fR \fBstrcasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\fR);
68 .fi
69 .LP
70 .nf
71 \fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
72 .fi
73 .LP
74 .nf
75 \fBint\fR \fBstrncasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, \fBlocale_t\fR \fIloc\fR);
76 .fi
77 .LP
78 .nf
79 #include <string.h>
80
81 \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
82 .fi
83 .LP
84 .nf
85 \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
86 .fi
87 .LP
88 .nf
89 \fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
90 .fi
91 .LP
92 .nf
93 \fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
94 .fi
95 .LP
96 .nf
97 \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
98 .fi
99 .LP
100 .nf
101 \fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
102 .fi
103 .LP
104 .nf
105 \fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
106 .fi
107 .LP
108 .nf
109 \fBchar *\fR\fBstpcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
110 .fi
111 .LP
112 .nf
113 \fBchar *\fR\fBstpncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
114 .fi
115 .LP
116 .nf
117 \fBchar *\fR\fBstrcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
118 .fi
119 .LP
120 .nf
121 \fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
122 .fi
123 .LP
124 .nf
125 \fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
126 .fi
127 .LP
128 .nf
129 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
130 .fi
131 .LP
132 .nf
133 \fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
134 .fi
135 .LP
136 .nf
137 \fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
138 .fi
139 .LP
140 .nf
141 \fBchar *\fR\fBstrndup\fR(\fBconst char *\fR\fIs1\fR, \fBsize_t\fR \fIn\fR);
142 .fi
143 .LP
144 .nf
145 \fBchar *\fR\fBstrdupa\fR(\fBconst char *\fR\fIs1\fR);
146 .fi
147 .LP
148 .nf
149 \fBchar *\fR\fBstrndupa\fR(\fBconst char *\fR\fIs1\fR, \fBsize_t\fR \fIn\fR);
150 .fi
151 .LP
152 .nf
153 \fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
154 .fi
155 .LP
156 .nf
157 \fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
158 .fi
159 .LP
160 .nf
161 \fBchar *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
162 .fi
163 .LP
164 .nf
165 \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR);
166 .fi
167 .LP
168 .nf
169 \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
170 .fi
171 .LP
172 .nf
173 \fBchar *\fR\fBstrnstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
174 .fi
175 .LP
176 .nf
177 \fBchar *\fR\fBstrcasestr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
178 .fi
179 .LP
180 .nf
181 \fBchar *\fR\fBstrcasestr_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\fR);
182 .fi
183 .LP
184 .nf
185 \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
186 .fi
187 .LP
188 .nf
189 \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR,
190 \fBchar **restrict\fR \fIlasts\fR);
191 .fi
192 .SS "ISO C++"
193 .LP
194 .nf
195 #include <string.h>
196
197 \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
198 .fi
199 .LP
200 .nf
201 \fBconst char *\fR\fBstrchrnul\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
202 .fi
203 .LP
204 .nf
205 \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
206 .fi
207 .LP
208 .nf
209 \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
210 .fi
211 .LP
212 .nf
213 \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
214 .fi
215 .LP
216 .nf
217 #include <cstring>
218
219 \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
220 .fi
221 .LP
222 .nf
223 \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
224 .fi
225 .LP
226 .nf
227 \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
228 .fi
229 .LP
230 .nf
231 \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
232 .fi
233 .SH DESCRIPTION
234 .LP
235 The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
236 characters terminated by a null character). The \fBstrcat()\fR, \fBstrncat()\fR,
237 \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstpcpy()\fR, \fBstpncpy()\fR,
238 \fBstrncpy()\fR, \fBstrlcpy()\fR, \fBstrsep()\fR, \fBstrtok()\fR, and
239 \fBstrtok_r()\fR functions all alter their first argument. Additionally, the
240 \fBstrcat()\fR, \fBstpcpy()\fR, and \fBstrcpy()\fR functions do not check for
241 overflow of the array.
242 .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
243 .LP
244 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
245 versions of \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
246 .LP
247 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions compare two strings
248 byte-by-byte, after
249 converting each upper-case character to lower-case (as determined by the
250 \fBLC_CTYPE\fR category of the current locale). Note that neither the contents
251 pointed to by \fIs1\fR nor \fIs2\fR are modified.
252 .LP
253 The functions return an integer
254 greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR
255 is greater than, equal to, or less than the string pointed to by \fIs2\fR
256 respectively. The sign of a non-zero return value is determined by the sign of
257 the difference between the values of the first pair of bytes that differ in the
258 .LP
259 The \fBstrncasecmp()\fR function examines at most \fIn\fR bytes from each
260 string.
261 .SS "\fBstrcasecmp_l()\fR, \fBstrncasecmp_l()\fR"
262 .LP
263 The \fBstrcasecmp_l()\fR and \fBstrncasecmp_l()\fR functions behave identically
264 to \fBstrcasecmp()\fR and \fBstrncasecmp()\fR, except instead of operating in
265 the current locale, they instead operate in the locale specified by \fIloc\fR.
266 .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR"
267 .LP
268 The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the
269 terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR
270 function appends at most \fIn\fR characters of \fIs2\fR to \fIs1\fR, not
271 including any terminating null character, and then appends a null character.
272 Each returns a pointer to the null-terminated result. The initial character of
273 \fIs2\fR overrides the null character at the end of \fIs1\fR. If copying takes
274 place between objects that overlap, the behavior of \fBstrcat()\fR,
275 \fBstrncat()\fR, and \fBstrlcat()\fR is undefined.
276 .LP
277 The \fBstrlcat()\fR function appends at most
278 (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
279 (\fIdstsize\fR being the size of the string buffer \fIdst\fR). If the string
280 pointed to by \fIdst\fR contains a null-terminated string that fits into
281 \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
282 \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
283 (including the terminating null character) when it completes, and the initial
284 character of \fIsrc\fR will override the null character at the end of
285 \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
286 bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
287 not be changed. The function returns
288 \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
289 Buffer overflow can be checked as follows:
290 .sp
291 .in +2
292 .nf
293 if (strlcat(dst, src, dstsize) >= dstsize)
294 return \(mi1;
295 .fi
296 .in -2
297 .SS "\fBstrchr()\fR, \fBstrrchr()\fR, \fBstrchrnul()\fR"
298 .LP
299 The \fBstrchr()\fR function returns a pointer to the first occurrence of
300 \fIc\fR (converted to a \fBchar\fR) in string \fIs\fR, or a null pointer if
301 \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
302 pointer to the last occurrence of \fIc\fR. The null character terminating a
303 string is considered to be part of the string. The \fBstrchrnul()\fR function
304 behaves similarly to \fBstrchr()\fR, except when the character \fBc\fR is not
305 found, it returns a pointer to the null terminator of the string \fBs\fR and not
306 a null pointer.
307 .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
308 .LP
309 The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
310 ordering of your machine's character set. The function returns an integer
311 greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR
312 is greater than, equal to, or less than the string pointed to by \fIs2\fR
313 respectively. The sign of a non-zero return value is determined by the sign of
314 the difference between the values of the first pair of bytes that differ in the
315 strings being compared. The \fBstrncmp()\fR function makes the same comparison
316 but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
317 compared.
318 .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
319 .LP
320 The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
321 terminating null character, stopping after the null character has been copied.
322 The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
323 or adding null characters to \fIs1\fR if necessary. The result will not be
324 null-terminated if the length of \fIs2\fR is \fIn\fR or more. Both the
325 \fBstrcpy()\fR and \fBstrncpy()\fR functions return \fIs1\fR. If copying takes
326 place between objects that overlap, the behavior of \fBstrcpy()\fR,
327 \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
328 .LP
329 The \fBstrlcpy()\fR function copies at most \fIdstsize\fR\(mi1 characters
330 (\fIdstsize\fR being the size of the string buffer \fIdst\fR) from \fIsrc\fR
331 to \fIdst\fR, truncating \fIsrc\fR if necessary. The result is always
332 null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
333 can be checked as follows:
334 .sp
335 .in +2
336 .nf
337 if (strlcpy(dst, src, dstsize) >= dstsize)
338 return \(mi1;
339 .fi
340 .in -2
341 .SS "\fBstpcpy()\fR, \fBstpncpy()\fR"
342 .LP
343 The \fBstpcpy()\fR and \fBstpncpy()\fR functions behave identically to
344 \fBstrcpy()\fR and \fBstrncpy()\fR respectively; however, instead of returning a
345 pointer to the beginning of \fIs1\fR, they return a pointer to the terminating
346 null character.
347 .SS "\fBstrcspn()\fR, \fBstrspn()\fR"
348 .LP
349 The \fBstrcspn()\fR function returns the length of the initial segment of
350 string \fIs1\fR that consists entirely of characters not from string \fIs2\fR.
351 The \fBstrspn()\fR function returns the length of the initial segment of string
352 \fIs1\fR that consists entirely of characters from string \fIs2\fR.
353 .SS "\fBstrdup()\fR, \fBstrndup()\fR, \fBstrdupa()\fR, \fBstrndupa()\fR"
354 .LP
355 The \fBstrdup()\fR function returns a pointer to a new string that is a
356 duplicate of the string pointed to by \fIs1\fR. The returned pointer can be
357 passed to \fBfree()\fR. The space for the new string is obtained using
358 \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is
359 returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the
360 storage space available is insufficient. The \fBstrndup()\fR function is
361 identical to \fBstrdup()\fR, except it copies at most \fIn\fR bytes from
362 \fBs1\fR and ensures the copied string is always null terminated.
363 .LP
364 The functions \fBstrdupa()\fR and \fBstrndupa()\fR behave identically to
365 \fBstrdup()\fR and \fBstrndup()\fR respectively; however, instead of allocating
366 memory using \fBmalloc\fR(3C), they use \fBalloca\fR(3C). These functions are
367 provided for compatibility only, their use is strongly discouraged due to their
368 use of \fBalloca\fR(3C).
369 .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
370 The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
371 including the terminating null character.
372 .LP
373 The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
374 bytes in \fIs\fR, not including the terminating null character. The
375 \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
376 pointed to by \fIs\fR.
377 .SS "\fBstrpbrk()\fR"
378 .LP
379 The \fBstrpbrk()\fR function returns a pointer to the first occurrence in
380 string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no
381 character from \fIs2\fR exists in \fIs1\fR.
382 .SS "\fBstrsep()\fR"
383 .LP
384 The \fBstrsep()\fR function locates, in the null-terminated string referenced
385 by *\fIstringp\fR, the first occurrence of any character in the string
386 \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'.
387 The location of the next character after the delimiter character (or
388 \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR.
389 The original value of *\fIstringp\fR is returned.
390 .LP
391 An ``empty'' field (one caused by two adjacent delimiter characters) can be
392 detected by comparing the location referenced by the pointer returned by
393 \fBstrsep()\fR to `\e0'.
394 .LP
395 If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR.
396 .SS "\fBstrstr()\fR, \fBstrnstr()\fR, \fBstrcasestr()\fR, \fBstrcasestr_l()\fR"
397 .LP
398 The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR
399 (excluding the terminating null character) in string \fIs1\fR and returns a
400 pointer to the located string, or a null pointer if the string is not found. If
401 \fIs2\fR points to a string with zero length (that is, the string \fB""\fR),
402 the function returns \fIs1\fR. The \fBstrnstr()\fR function performs the same
403 search as \fBstrstr()\fR, but only considers up to \fIn\fR bytes of \fIs1\fR.
404 Bytes following a null byte are not compared.
405 .sp
406 .LP
407 The \fBstrcasestr()\fR and \fBstrcasestr_l()\fR functions are similar to
408 \fBstrstr()\fR, but both functions ignore the case of both \fBs1\fR and
409 \fBs2\fR. Where as the \fBstrcasestr()\fR function operates in the current
410 locale, the \fBstrcasestr_l()\fR function operates in the locale specified by
411 \fIloc\fR.
412 .SS "\fBstrtok()\fR"
413 .LP
414 A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR
415 into a sequence of tokens, each of which is delimited by a byte from the string
416 pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its
417 first argument, and is followed by calls with a null pointer as their first
418 argument. The separator string pointed to by \fIs2\fR can be different from
419 call to call.
420 .LP
421 The first call in the sequence searches the string pointed to by \fIs1\fR for
422 the first byte that is not contained in the current separator string pointed to
423 by \fIs2\fR. If no such byte is found, then there are no tokens in the string
424 pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a
425 byte is found, it is the start of the first token.
426 .LP
427 The \fBstrtok()\fR function then searches from there for a byte that is
428 contained in the current separator string. If no such byte is found, the
429 current token extends to the end of the string pointed to by \fIs1\fR, and
430 subsequent searches for a token return a null pointer. If such a byte is found,
431 it is overwritten by a null byte that terminates the current token. The
432 \fBstrtok()\fR function saves a pointer to the following byte in
433 thread-specific data, from which the next search for a token starts.
434 .LP
435 Each subsequent call, with a null pointer as the value of the first argument,
436 starts searching from the saved pointer and behaves as described above.
437 .LP
438 See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of
439 \fBstrtok()\fR usage and the explanation in \fBNOTES\fR.
440 .SS "\fBstrtok_r()\fR"
441 .LP
442 The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
443 a sequence of zero or more text tokens separated by spans of one or more
444 characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
445 to a user-provided pointer which points to stored information necessary for
446 \fBstrtok_r()\fR to continue scanning the same string.
447 .LP
448 In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
449 string, \fIs2\fR to a null-terminated string of separator characters, and the
450 value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
451 returns a pointer to the first character of the first token, writes a null
452 character into \fIs1\fR immediately following the returned token, and updates
453 the pointer to which \fIlasts\fR points.
454 .LP
455 In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
456 from the previous call so that subsequent calls move through the string
457 \fIs1\fR, returning successive tokens until no tokens remain. The separator
458 string \fIs2\fR can be different from call to call. When no token remains in
459 \fIs1\fR, a null pointer is returned.
460 .LP
461 See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR
462 usage and the explanation in \fBNOTES\fR.
463 .SH EXAMPLES
464 .LP
465 \fBExample 1 \fRSearch for word separators.
466 .LP
467 The following example searches for tokens separated by space characters.
468
469 .sp
470 .in +2
471 .nf
472 #include <string.h>
473 \&...
474 char *token;
475 char line[] = "LINE TO BE SEPARATED";
476 char *search = " ";
477
478 /* Token will point to "LINE". */
479 token = strtok(line, search);
480
481 /* Token will point to "TO". */
482 token = strtok(NULL, search);
483 .fi
484 .in -2
485
486 .LP
487 \fBExample 2 \fRBreak a Line.
488 .LP
489 The following example uses strtok to break a line into two character strings
490 separated by any combination of SPACEs, TABs, or NEWLINEs.
491
492 .sp
493 .in +2
494 .nf
495 #include <string.h>
496 \&...
497 struct element {
498 char *key;
499 char *data;
500 };
501 \&...
502 char line[LINE_MAX];
503 char *key, *data;
504 \&...
505 key = strtok(line, " \en");
506 data = strtok(NULL, " \en");
507 .fi
508 .in -2
509
510 .LP
511 \fBExample 3 \fRSearch for tokens.
512 .LP
513 The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search
514 for tokens separated by one or more characters from the string pointed to by
515 the second argument, "/".
516
517 .sp
518 .in +2
519 .nf
520 #define __EXTENSIONS__
521 #include <stdio.h>
522 #include <string.h>
523
524 int
525 main() {
526 char *buf="5/90/45";
527 char *token;
528 char *lasts;
529
530 printf("tokenizing \e"%s\e" with strtok():\en", buf);
531 if ((token = strtok(buf, "/")) != NULL) {
532 printf("token = "%s\e"\en", token);
533 while ((token = strtok(NULL, "/")) != NULL) {
534 printf("token = \e"%s\e"\en", token);
535 }
536 }
537
538 buf = "//5//90//45//";
539 printf("\entokenizing \e"%s\e" with strtok_r():\en", buf);
540 if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
541 printf("token = \e"%s\e"\en", token);
542 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
543 printf("token = \e"%s\e"\en", token);
544 }
545 }
546 }
547 .fi
548 .in -2
549
550 .LP
551 When compiled and run, this example produces the following output:
552
553 .sp
554 .in +2
555 .nf
556 tokenizing "5/90/45" with \fBstrtok()\fR:
557 token = "5"
558 token = "90"
559 token = "45"
560
561 tokenizing "//5//90//45//" with \fBstrtok_r()\fR:
562 token = "5"
563 token = "90"
564 token = "45"
565 .fi
566 .in -2
567
568 .SH ATTRIBUTES
569 .LP
570 See \fBattributes\fR(5) for descriptions of the following attributes:
571 .TS
572 box;
573 c | c
574 l | l .
575 ATTRIBUTE TYPE ATTRIBUTE VALUE
576 _
577 Interface Stability See below.
578 _
579 MT-Level See below.
580 _
581 Standard See below.
582 .TE
583
584 .LP
585 The
586 \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR functions are Committed.
587 All the rest are Standard.
588 .LP
589 The \fBstrtok()\fR, \fBstrdup()\fR, and \fBstrndup()\fR functions are MT-Safe.
590 The remaining functions are Async-Signal-Safe.
591 .LP
592 For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see
593 \fBstandards\fR(5).
594 .SH SEE ALSO
595 .LP
596 \fBmalloc\fR(3C),
597 \fBnewlocale\fR(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C),
598 \fBuselocale\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
599 .SH NOTES
600 .LP
601 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
602 defined on the compile line. This flag should only be used in multithreaded
603 applications.
604 .LP
605 A single-threaded application can gain access to \fBstrtok_r()\fR only by
606 defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value
607 greater than or equal to 199506L.
608 .LP
609 Except where noted otherwise, all of these functions assume the default
610 locale ``C.'' For some locales,
611 \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to
612 the functions.
613 .LP
614 The \fBstrtok()\fR function is safe to use in multithreaded applications
615 because it saves its internal state in a thread-specific data area. However,
616 its use is discouraged, even for single-threaded applications. The
617 \fBstrtok_r()\fR function should be used instead.
618 .LP
619 Do not pass the address of a character string literal as the argument \fIs1\fR
620 to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer
621 to the address of a character string literal as the argument \fIstringp\fR to
622 \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR
623 in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the
624 case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify
625 the storage occupied by a string literal results in undefined behavior. This
626 allows compilers (including \fBgcc\fR and the Sun Studio compilers when the
627 \fB-xstrconst\fR flag is used) to place string literals in read-only memory.
628 Note that in Example 1 above, this problem is avoided because the variable
629 \fIline\fR is declared as a writable array of type \fBchar\fR that is
630 initialized by a string literal rather than a pointer to \fBchar\fR that points
631 to a string literal.