| blob | cc934221e3022ac7720b87a21b21f427c205f83f |
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 "Dec 20, 2014"
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. Each returns a pointer to the
236 null-terminated result. The initial character of \fIs2\fR overrides the null
237 character at the end of \fIs1\fR. If copying takes place between objects that
238 overlap, the behavior of \fBstrcat()\fR, \fBstrncat()\fR, and \fBstrlcat()\fR
239 is undefined.
240 .LP
241 The \fBstrlcat()\fR function appends at most
242 (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
243 (\fIdstsize\fR being the size of the string buffer \fIdst\fR). If the string
244 pointed to by \fIdst\fR contains a null-terminated string that fits into
245 \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
246 \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
247 (including the terminating null character) when it completes, and the initial
248 character of \fIsrc\fR will override the null character at the end of
249 \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
250 bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
251 not be changed. The function returns
252 \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
253 Buffer overflow can be checked as follows:
254 .sp
255 .in +2
256 .nf
257 if (strlcat(dst, src, dstsize) >= dstsize)
258 return \(mi1;
259 .fi
260 .in -2
261 .SS "\fBstrchr()\fR, \fBstrrchr()\fR, \fBstrchrnul()\fR"
262 .LP
263 The \fBstrchr()\fR function returns a pointer to the first occurrence of
264 \fIc\fR (converted to a \fBchar\fR) in string \fIs\fR, or a null pointer if
265 \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
266 pointer to the last occurrence of \fIc\fR. The null character terminating a
267 string is considered to be part of the string. The \fBstrchrnul()\fR function
268 behaves similarly to \fBstrchr()\fR, except when the character \fBc\fR is not
269 found, it returns a pointer to the null terminator of the string \fBs\fR and not
270 a null pointer.
271 .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
272 .LP
273 The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
274 ordering of your machine's character set. The function returns an integer
275 greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR
276 is greater than, equal to, or less than the string pointed to by \fIs2\fR
277 respectively. The sign of a non-zero return value is determined by the sign of
278 the difference between the values of the first pair of bytes that differ in the
279 strings being compared. The \fBstrncmp()\fR function makes the same comparison
280 but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
281 compared.
282 .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
283 .LP
284 The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
285 terminating null character, stopping after the null character has been copied.
286 The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
287 or adding null characters to \fIs1\fR if necessary. The result will not be
288 null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function
289 returns \fIs1\fR. If copying takes place between objects that overlap, the
290 behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
291 .LP
292 The \fBstrlcpy()\fR function copies at most \fIdstsize\fR\(mi1 characters
293 (\fIdstsize\fR being the size of the string buffer \fIdst\fR) from \fIsrc\fR
294 to \fIdst\fR, truncating \fIsrc\fR if necessary. The result is always
295 null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
296 can be checked as follows:
297 .sp
298 .in +2
299 .nf
300 if (strlcpy(dst, src, dstsize) >= dstsize)
301 return \(mi1;
302 .fi
303 .in -2
304 .SS "\fBstpcpy()\fR, \fBstpncpy()\fR"
305 .LP
306 The \fBstpcpy()\fR and \fBstpncpy()\fR functions behave identically to
307 \fBstrcpy()\fR and \fBstrncpy()\fR respectively; however, instead of returning a
308 pointer to the beginning of \fIs1\fR, they return a pointer to the terminating
309 null character.
310 .SS "\fBstrcspn()\fR, \fBstrspn()\fR"
311 .LP
312 The \fBstrcspn()\fR function returns the length of the initial segment of
313 string \fIs1\fR that consists entirely of characters not from string \fIs2\fR.
314 The \fBstrspn()\fR function returns the length of the initial segment of string
315 \fIs1\fR that consists entirely of characters from string \fIs2\fR.
316 .SS "\fBstrdup()\fR, \fBstrndup()\fR, \fBstrdupa()\fR, \fBstrndupa()\fR"
317 .LP
318 The \fBstrdup()\fR function returns a pointer to a new string that is a
319 duplicate of the string pointed to by \fIs1\fR. The returned pointer can be
320 passed to \fBfree()\fR. The space for the new string is obtained using
321 \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is
322 returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the
323 storage space available is insufficient. The \fBstrndup()\fR function is
324 identical to \fBstrdup()\fR, execept it copies at most \fIn\fR bytes from
325 \fBs1\fR and ensures the copied string is awlays null terminated.
326 .LP
327 The functions \fBstrdupa()\fR and \fBstrndupa()\fR behave identically to
328 \fBstrdup()\fr and \fBstrndup()\fR respectively; however, instead of allocating
329 memory using \fBmalloc\fR(3C), they use \fBalloca\fR(3C). These functions are
330 provided for compatibility only, their use is strongly discouraged due to their
331 use of \fBalloca\fR(3C).
332 .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
333 The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
334 including the terminating null character.
335 .LP
336 The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
337 bytes in \fIs\fR, not including the terminating null character. The
338 \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
339 pointed to by \fIs\fR.
340 .SS "\fBstrpbrk()\fR"
341 .LP
342 The \fBstrpbrk()\fR function returns a pointer to the first occurrence in
343 string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no
344 character from \fIs2\fR exists in \fIs1\fR.
345 .SS "\fBstrsep()\fR"
346 .LP
347 The \fBstrsep()\fR function locates, in the null-terminated string referenced
348 by *\fIstringp\fR, the first occurrence of any character in the string
349 \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'.
350 The location of the next character after the delimiter character (or
351 \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR.
352 The original value of *\fIstringp\fR is returned.
353 .LP
354 An ``empty'' field (one caused by two adjacent delimiter characters) can be
355 detected by comparing the location referenced by the pointer returned by
356 \fBstrsep()\fR to `\e0'.
357 .LP
358 If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR.
359 .SS "\fBstrstr()\fR, \fBstrnstr()\fR, \fBstrcasestr()\fR, \fBstrcasestr_l()\fR"
360 .LP
361 The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR
362 (excluding the terminating null character) in string \fIs1\fR and returns a
363 pointer to the located string, or a null pointer if the string is not found. If
364 \fIs2\fR points to a string with zero length (that is, the string \fB""\fR),
365 the function returns \fIs1\fR. The \fBstrnstr()\fR function performs the same
366 search as \fBstrstr()\fR, but only considers up to \fIn\fR bytes of \fIs1\fR.
367 Bytes following a null byte are not compared.
368 .sp
369 .LP
370 The \fBstrcasestr()\fR and \fBstrcasestr_l()\fR functions are similar to
371 \fBstrstr()\fR, but both functions ignore the case of both \fBs1\fR and
372 \fBs2\fR. Where as the \fBstrcasestr()\fR function operates in the current
373 locale, the \fBstrcasestr_l()\fR function operates in the locale specified by
374 \fIloc\fR.
375 .SS "\fBstrtok()\fR"
376 .LP
377 A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR
378 into a sequence of tokens, each of which is delimited by a byte from the string
379 pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its
380 first argument, and is followed by calls with a null pointer as their first
381 argument. The separator string pointed to by \fIs2\fR can be different from
382 call to call.
383 .LP
384 The first call in the sequence searches the string pointed to by \fIs1\fR for
385 the first byte that is not contained in the current separator string pointed to
386 by \fIs2\fR. If no such byte is found, then there are no tokens in the string
387 pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a
388 byte is found, it is the start of the first token.
389 .LP
390 The \fBstrtok()\fR function then searches from there for a byte that is
391 contained in the current separator string. If no such byte is found, the
392 current token extends to the end of the string pointed to by \fIs1\fR, and
393 subsequent searches for a token return a null pointer. If such a byte is found,
394 it is overwritten by a null byte that terminates the current token. The
395 \fBstrtok()\fR function saves a pointer to the following byte in
396 thread-specific data, from which the next search for a token starts.
397 .LP
398 Each subsequent call, with a null pointer as the value of the first argument,
399 starts searching from the saved pointer and behaves as described above.
400 .LP
401 See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of
402 \fBstrtok()\fR usage and the explanation in \fBNOTES\fR.
403 .SS "\fBstrtok_r()\fR"
404 .LP
405 The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
406 a sequence of zero or more text tokens separated by spans of one or more
407 characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
408 to a user-provided pointer which points to stored information necessary for
409 \fBstrtok_r()\fR to continue scanning the same string.
410 .LP
411 In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
412 string, \fIs2\fR to a null-terminated string of separator characters, and the
413 value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
414 returns a pointer to the first character of the first token, writes a null
415 character into \fIs1\fR immediately following the returned token, and updates
416 the pointer to which \fIlasts\fR points.
417 .LP
418 In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
419 from the previous call so that subsequent calls move through the string
420 \fIs1\fR, returning successive tokens until no tokens remain. The separator
421 string \fIs2\fR can be different from call to call. When no token remains in
422 \fIs1\fR, a null pointer is returned.
423 .LP
424 See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR
425 usage and the explanation in \fBNOTES\fR.
426 .SH EXAMPLES
427 .LP
428 \fBExample 1 \fRSearch for word separators.
429 .LP
430 The following example searches for tokens separated by space characters.
432 .sp
433 .in +2
434 .nf
435 #include <string.h>
436 \&...
437 char *token;
438 char line[] = "LINE TO BE SEPARATED";
439 char *search = " ";
441 /* Token will point to "LINE". */
442 token = strtok(line, search);
444 /* Token will point to "TO". */
445 token = strtok(NULL, search);
446 .fi
447 .in -2
449 .LP
450 \fBExample 2 \fRBreak a Line.
451 .LP
452 The following example uses strtok to break a line into two character strings
453 separated by any combination of SPACEs, TABs, or NEWLINEs.
455 .sp
456 .in +2
457 .nf
458 #include <string.h>
459 \&...
460 struct element {
461 char *key;
462 char *data;
463 };
464 \&...
465 char line[LINE_MAX];
466 char *key, *data;
467 \&...
468 key = strtok(line, " \en");
469 data = strtok(NULL, " \en");
470 .fi
471 .in -2
473 .LP
474 \fBExample 3 \fRSearch for tokens.
475 .LP
476 The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search
477 for tokens separated by one or more characters from the string pointed to by
478 the second argument, "/".
480 .sp
481 .in +2
482 .nf
483 #define __EXTENSIONS__
484 #include <stdio.h>
485 #include <string.h>
487 int
488 main() {
489 char *buf="5/90/45";
490 char *token;
491 char *lasts;
493 printf("tokenizing \e"%s\e" with strtok():\en", buf);
494 if ((token = strtok(buf, "/")) != NULL) {
495 printf("token = "%s\e"\en", token);
496 while ((token = strtok(NULL, "/")) != NULL) {
497 printf("token = \e"%s\e"\en", token);
498 }
499 }
501 buf = "//5//90//45//";
502 printf("\entokenizing \e"%s\e" with strtok_r():\en", buf);
503 if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
504 printf("token = \e"%s\e"\en", token);
505 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
506 printf("token = \e"%s\e"\en", token);
507 }
508 }
509 }
510 .fi
511 .in -2
513 .LP
514 When compiled and run, this example produces the following output:
516 .sp
517 .in +2
518 .nf
519 tokenizing "5/90/45" with \fBstrtok()\fR:
520 token = "5"
521 token = "90"
522 token = "45"
524 tokenizing "//5//90//45//" with \fBstrtok_r()\fR:
525 token = "5"
526 token = "90"
527 token = "45"
528 .fi
529 .in -2
531 .SH ATTRIBUTES
532 .LP
533 See \fBattributes\fR(5) for descriptions of the following attributes:
534 .TS
535 box;
536 c | c
537 l | l .
538 ATTRIBUTE TYPE ATTRIBUTE VALUE
539 _
540 Interface Stability See below.
541 _
542 MT-Level See below.
543 _
544 Standard See below.
545 .TE
547 .LP
548 The
549 \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR functions are Committed.
550 All the rest are Standard.
551 .LP
552 The \fBstrtok()\fR, \fBstrdup()\fR, and \fBstrndup()\fR functions are MT-Safe.
553 The remaining functions are Async-Signal-Safe.
554 .LP
555 For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see
556 \fBstandards\fR(5).
557 .SH SEE ALSO
558 .LP
559 \fBmalloc\fR(3C),
560 \fBnewlocale(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBuselocale\fR(3C),
561 \fBattributes\fR(5), \fBstandards\fR(5)
562 .SH NOTES
563 .LP
564 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
565 defined on the compile line. This flag should only be used in multithreaded
566 applications.
567 .LP
568 A single-threaded application can gain access to \fBstrtok_r()\fR only by
569 defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value
570 greater than or equal to 199506L.
571 .LP
572 Except where noted otherwise, all of these functions assume the default
573 locale ``C.'' For some locales,
574 \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to
575 the functions.
576 .LP
577 The \fBstrtok()\fR function is safe to use in multithreaded applications
578 because it saves its internal state in a thread-specific data area. However,
579 its use is discouraged, even for single-threaded applications. The
580 \fBstrtok_r()\fR function should be used instead.
581 .LP
582 Do not pass the address of a character string literal as the argument \fIs1\fR
583 to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer
584 to the address of a character string literal as the argument \fIstringp\fR to
585 \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR
586 in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the
587 case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify
588 the storage occupied by a string literal results in undefined behavior. This
589 allows compilers (including \fBgcc\fR and the Sun Studio compilers when the
590 \fB-xstrconst\fR flag is used) to place string literals in read-only memory.
591 Note that in Example 1 above, this problem is avoided because the variable
592 \fIline\fR is declared as a writable array of type \fBchar\fR that is
593 initialized by a string literal rather than a pointer to \fBchar\fR that points
594 to a string literal.