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