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