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