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