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