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