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