Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/string.3c.man.txt
+++ new/usr/src/man/man3c/string.3c.man.txt
1 1 STRING(3C) Standard C Library Functions STRING(3C)
2 2
3 3
4 4
5 5 NAME
6 6 string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat,
7 7 strncat, strlcat, strchr, strchrnul, strrchr, strcmp, strncmp, stpcpy,
8 8 stpncpy, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strndup,
9 9 strdupa, strndupa, strlen, strnlen, strpbrk, strsep, strstr, strnstr,
10 10 strcasestr, strtok, strtok_r - string operations
11 11
12 12 SYNOPSIS
13 13 #include <strings.h>
14 14
15 15 int strcasecmp(const char *s1, const char *s2);
16 16
17 17 int strcasecmp_l(const char *s1, const char *s2, locale_t loc);
18 18
19 19 int strncasecmp(const char *s1, const char *s2, size_t n);
20 20
21 21 int strncasecmp_l(const char *s1, const char *s2, size_t n, locale_t loc);
22 22
23 23 #include <string.h>
24 24
25 25 char *strcat(char *restrict s1, const char *restrict s2);
26 26
27 27 char *strncat(char *restrict s1, const char *restrict s2, size_t n);
28 28
29 29 size_t strlcat(char *dst, const char *src, size_t dstsize);
30 30
31 31 char *strchr(const char *s, int c);
32 32
33 33 char *strrchr(const char *s, int c);
34 34
35 35 int strcmp(const char *s1, const char *s2);
36 36
37 37 int strncmp(const char *s1, const char *s2, size_t n);
38 38
39 39 char *stpcpy(char *restrict s1, const char *restrict s2);
40 40
41 41 char *stpncpy(char *restrict s1, const char *restrict s2, size_t n);
42 42
43 43 char *strcpy(char *restrict s1, const char *restrict s2);
44 44
45 45 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
46 46
47 47 size_t strlcpy(char *dst, const char *src, size_t dstsize);
48 48
49 49 size_t strcspn(const char *s1, const char *s2);
50 50
51 51 size_t strspn(const char *s1, const char *s2);
52 52
53 53 char *strdup(const char *s1);
54 54
55 55 char *strndup(const char *s1, size_t n);
56 56
57 57 char *strdupa(const char *s1);
58 58
59 59 char *strndupa(const char *s1, size_t n);
60 60
61 61 size_t strlen(const char *s);
62 62
63 63 size_t strnlen(const char *s, size_t n);
64 64
65 65 char *strpbrk(const char *s1, const char *s2);
66 66
67 67 char *strsep(char **stringp, const char *delim);
68 68
69 69 char *strstr(const char *s1, const char *s2);
70 70
71 71 char *strnstr(const char *s1, const char *s2, size_t n);
72 72
73 73 char *strcasestr(const char *s1, const char *s2);
74 74
75 75 char *strcasestr_l(const char *s1, const char *s2, locale_t loc);
76 76
77 77 char *strtok(char *restrict s1, const char *restrict s2);
78 78
79 79 char *strtok_r(char *restrict s1, const char *restrict s2,
80 80 char **restrict lasts);
81 81
82 82 ISO C++
83 83 #include <string.h>
84 84
85 85 const char *strchr(const char *s, int c);
86 86
87 87 const char *strchrnul(const char *s, int c);
88 88
89 89 const char *strpbrk(const char *s1, const char *s2);
90 90
91 91 const char *strrchr(const char *s, int c);
92 92
93 93 const char *strstr(const char *s1, const char *s2);
94 94
95 95 #include <cstring>
96 96
97 97 char *std::strchr(char *s, int c);
98 98
99 99 char *std::strpbrk(char *s1, const char *s2);
100 100
101 101 char *std::strrchr(char *s, int c);
102 102
103 103 char *std::strstr(char *s1, const char *s2);
104 104
105 105 DESCRIPTION
106 106 The arguments s, s1, and s2 point to strings (arrays of characters
107 107 terminated by a null character). The strcat(), strncat(), strlcat(),
108 108 strcpy(), stpcpy(), stpncpy(), strncpy(), strlcpy(), strsep(),
109 109 strtok(), and strtok_r() functions all alter their first argument.
110 110 Additionally, the strcat(), stpcpy(), and strcpy() functions do not
111 111 check for overflow of the array.
112 112
113 113 strcasecmp(), strncasecmp()
114 114 The strcasecmp() and strncasecmp() functions are case-insensitive
115 115 versions of strcmp() and strncmp() respectively, described below.
116 116
117 117 The strcasecmp() and strncasecmp() functions compare two strings byte-
118 118 by-byte, after converting each upper-case character to lower-case (as
119 119 determined by the LC_CTYPE category of the current locale). Note that
120 120 neither the contents pointed to by s1 nor s2 are modified.
121 121
122 122 The functions return an integer greater than, equal to, or less than 0,
123 123 if the string pointed to by s1 is greater than, equal to, or less than
124 124 the string pointed to by s2 respectively. The sign of a non-zero return
125 125 value is determined by the sign of the difference between the values
126 126 of the first pair of bytes that differ in the
127 127
128 128 The strncasecmp() function examines at most n bytes from each string.
129 129
130 130 strcasecmp_l(), strncasecmp_l()
131 131 The strcasecmp_l() and strncasecmp_l() functions behave identically to
132 132 strcasecmp() and strncasecmp(), except instead of operating in the
133 133 current locale, they instead operate in the locale specified by loc.
134 134
135 135 strcat(), strncat(), strlcat()
136 136 The strcat() function appends a copy of string s2, including the
137 137 terminating null character, to the end of string s1. The strncat()
138 138 function appends at most n characters of s2 to s1, not including any
139 139 terminating null character, and then appends a null character. Each
140 140 returns a pointer to the null-terminated result. The initial character
141 141 of s2 overrides the null character at the end of s1. If copying takes
142 142 place between objects that overlap, the behavior of strcat(),
143 143 strncat(), and strlcat() is undefined.
144 144
145 145 The strlcat() function appends at most (dstsize-strlen(dst)-1)
146 146 characters of src to dst (dstsize being the size of the string buffer
147 147 dst). If the string pointed to by dst contains a null-terminated string
148 148 that fits into dstsize bytes when strlcat() is called, the string
149 149 pointed to by dst will be a null-terminated string that fits in dstsize
150 150 bytes (including the terminating null character) when it completes, and
151 151 the initial character of src will override the null character at the
152 152 end of dst. If the string pointed to by dst is longer than dstsize
153 153 bytes when strlcat() is called, the string pointed to by dst will not
154 154 be changed. The function returns min{dstsize,strlen(dst)}+strlen(src).
155 155 Buffer overflow can be checked as follows:
156 156
157 157 if (strlcat(dst, src, dstsize) >= dstsize)
158 158 return -1;
159 159
160 160 strchr(), strrchr(), strchrnul()
161 161 The strchr() function returns a pointer to the first occurrence of c
162 162 (converted to a char) in string s, or a null pointer if c does not
163 163 occur in the string. The strrchr() function returns a pointer to the
164 164 last occurrence of c. The null character terminating a string is
165 165 considered to be part of the string. The strchrnul() function behaves
166 166 similarly to strchr(), except when the character c is not found, it
167 167 returns a pointer to the null terminator of the string s and not a null
168 168 pointer.
169 169
170 170 strcmp(), strncmp()
171 171 The strcmp() function compares two strings byte-by-byte, according to
172 172 the ordering of your machine's character set. The function returns an
173 173 integer greater than, equal to, or less than 0, if the string pointed
174 174 to by s1 is greater than, equal to, or less than the string pointed to
175 175 by s2 respectively. The sign of a non-zero return value is determined
176 176 by the sign of the difference between the values of the first pair of
177 177 bytes that differ in the strings being compared. The strncmp() function
178 178 makes the same comparison but looks at a maximum of n bytes. Bytes
179 179 following a null byte are not compared.
180 180
181 181 strcpy(), strncpy(), strlcpy()
182 182 The strcpy() function copies string s2 to s1, including the terminating
183 183 null character, stopping after the null character has been copied. The
184 184 strncpy() function copies exactly n bytes, truncating s2 or adding null
185 185 characters to s1 if necessary. The result will not be null-terminated
186 186 if the length of s2 is n or more. Both the strcpy() and strncpy()
187 187 functions return s1. If copying takes place between objects that
188 188 overlap, the behavior of strcpy(), strncpy(), and strlcpy() is
189 189 undefined.
190 190
191 191 The strlcpy() function copies at most dstsize-1 characters (dstsize
192 192 being the size of the string buffer dst) from src to dst, truncating
193 193 src if necessary. The result is always null-terminated. The function
194 194 returns strlen(src). Buffer overflow can be checked as follows:
195 195
196 196 if (strlcpy(dst, src, dstsize) >= dstsize)
197 197 return -1;
198 198
199 199 stpcpy(), stpncpy()
200 200 The stpcpy() and stpncpy() functions behave identically to strcpy() and
201 201 strncpy() respectively; however, instead of returning a pointer to the
202 202 beginning of s1, they return a pointer to the terminating null
203 203 character.
204 204
205 205 strcspn(), strspn()
206 206 The strcspn() function returns the length of the initial segment of
207 207 string s1 that consists entirely of characters not from string s2. The
|
↓ open down ↓ |
207 lines elided |
↑ open up ↑ |
208 208 strspn() function returns the length of the initial segment of string
209 209 s1 that consists entirely of characters from string s2.
210 210
211 211 strdup(), strndup(), strdupa(), strndupa()
212 212 The strdup() function returns a pointer to a new string that is a
213 213 duplicate of the string pointed to by s1. The returned pointer can be
214 214 passed to free(). The space for the new string is obtained using
215 215 malloc(3C). If the new string cannot be created, a null pointer is
216 216 returned and errno may be set to ENOMEM to indicate that the storage
217 217 space available is insufficient. The strndup() function is identical to
218 - strdup(), execept it copies at most n bytes from s1 and ensures the
219 - copied string is awlays null terminated.
218 + strdup(), except it copies at most n bytes from s1 and ensures the
219 + copied string is always null terminated.
220 220
221 221 The functions strdupa() and strndupa() behave identically to strdup()
222 222 and strndup() respectively; however, instead of allocating memory using
223 223 malloc(3C), they use alloca(3C). These functions are provided for
224 224 compatibility only, their use is strongly discouraged due to their use
225 225 of alloca(3C).
226 226
227 227 strlen(), strnlen()
228 228 The strlen() function returns the number of bytes in s, not including
229 229 the terminating null character.
230 230
231 231 The strnlen() function returns the smaller of n or the number of bytes
232 232 in s, not including the terminating null character. The strnlen()
233 233 function never examines more than n bytes of the string pointed to by
234 234 s.
235 235
236 236 strpbrk()
237 237 The strpbrk() function returns a pointer to the first occurrence in
238 238 string s1 of any character from string s2, or a null pointer if no
239 239 character from s2 exists in s1.
240 240
241 241 strsep()
242 242 The strsep() function locates, in the null-terminated string referenced
243 243 by *stringp, the first occurrence of any character in the string delim
244 244 (or the terminating `\0' character) and replaces it with a `\0'. The
245 245 location of the next character after the delimiter character (or NULL,
246 246 if the end of the string was reached) is stored in *stringp. The
247 247 original value of *stringp is returned.
248 248
249 249 An ``empty'' field (one caused by two adjacent delimiter characters)
250 250 can be detected by comparing the location referenced by the pointer
251 251 returned by strsep() to `\0'.
252 252
253 253 If *stringp is initially NULL, strsep() returns NULL.
254 254
255 255 strstr(), strnstr(), strcasestr(), strcasestr_l()
256 256 The strstr() function locates the first occurrence of the string s2
257 257 (excluding the terminating null character) in string s1 and returns a
258 258 pointer to the located string, or a null pointer if the string is not
259 259 found. If s2 points to a string with zero length (that is, the string
260 260 ""), the function returns s1. The strnstr() function performs the same
261 261 search as strstr(), but only considers up to n bytes of s1. Bytes
262 262 following a null byte are not compared.
263 263
264 264
265 265 The strcasestr() and strcasestr_l() functions are similar to strstr(),
266 266 but both functions ignore the case of both s1 and s2. Where as the
267 267 strcasestr() function operates in the current locale, the
268 268 strcasestr_l() function operates in the locale specified by loc.
269 269
270 270 strtok()
271 271 A sequence of calls to strtok() breaks the string pointed to by s1 into
272 272 a sequence of tokens, each of which is delimited by a byte from the
273 273 string pointed to by s2. The first call in the sequence has s1 as its
274 274 first argument, and is followed by calls with a null pointer as their
275 275 first argument. The separator string pointed to by s2 can be different
276 276 from call to call.
277 277
278 278 The first call in the sequence searches the string pointed to by s1 for
279 279 the first byte that is not contained in the current separator string
280 280 pointed to by s2. If no such byte is found, then there are no tokens in
281 281 the string pointed to by s1 and strtok() returns a null pointer. If
282 282 such a byte is found, it is the start of the first token.
283 283
284 284 The strtok() function then searches from there for a byte that is
285 285 contained in the current separator string. If no such byte is found,
286 286 the current token extends to the end of the string pointed to by s1,
287 287 and subsequent searches for a token return a null pointer. If such a
288 288 byte is found, it is overwritten by a null byte that terminates the
289 289 current token. The strtok() function saves a pointer to the following
290 290 byte in thread-specific data, from which the next search for a token
291 291 starts.
292 292
293 293 Each subsequent call, with a null pointer as the value of the first
294 294 argument, starts searching from the saved pointer and behaves as
295 295 described above.
296 296
297 297 See Example 1, 2, and 3 in the EXAMPLES section for examples of
298 298 strtok() usage and the explanation in NOTES.
299 299
300 300 strtok_r()
301 301 The strtok_r() function considers the null-terminated string s1 as a
302 302 sequence of zero or more text tokens separated by spans of one or more
303 303 characters from the separator string s2. The argument lasts points to a
304 304 user-provided pointer which points to stored information necessary for
305 305 strtok_r() to continue scanning the same string.
306 306
307 307 In the first call to strtok_r(), s1 points to a null-terminated string,
308 308 s2 to a null-terminated string of separator characters, and the value
309 309 pointed to by lasts is ignored. The strtok_r() function returns a
310 310 pointer to the first character of the first token, writes a null
311 311 character into s1 immediately following the returned token, and updates
312 312 the pointer to which lasts points.
313 313
314 314 In subsequent calls, s1 is a null pointer and lasts is unchanged from
315 315 the previous call so that subsequent calls move through the string s1,
316 316 returning successive tokens until no tokens remain. The separator
317 317 string s2 can be different from call to call. When no token remains in
318 318 s1, a null pointer is returned.
319 319
320 320 See Example 3 in the EXAMPLES section for an example of strtok_r()
321 321 usage and the explanation in NOTES.
322 322
323 323 EXAMPLES
324 324 Example 1 Search for word separators.
325 325
326 326 The following example searches for tokens separated by space
327 327 characters.
328 328
329 329
330 330 #include <string.h>
331 331 ...
332 332 char *token;
333 333 char line[] = "LINE TO BE SEPARATED";
334 334 char *search = " ";
335 335
336 336 /* Token will point to "LINE". */
337 337 token = strtok(line, search);
338 338
339 339 /* Token will point to "TO". */
340 340 token = strtok(NULL, search);
341 341
342 342
343 343 Example 2 Break a Line.
344 344
345 345 The following example uses strtok to break a line into two character
346 346 strings separated by any combination of SPACEs, TABs, or NEWLINEs.
347 347
348 348
349 349 #include <string.h>
350 350 ...
351 351 struct element {
352 352 char *key;
353 353 char *data;
354 354 };
355 355 ...
356 356 char line[LINE_MAX];
357 357 char *key, *data;
358 358 ...
359 359 key = strtok(line, " \n");
360 360 data = strtok(NULL, " \n");
361 361
362 362
363 363 Example 3 Search for tokens.
364 364
365 365 The following example uses both strtok() and strtok_r() to search for
366 366 tokens separated by one or more characters from the string pointed to
367 367 by the second argument, "/".
368 368
369 369
370 370 #define __EXTENSIONS__
371 371 #include <stdio.h>
372 372 #include <string.h>
373 373
374 374 int
375 375 main() {
376 376 char *buf="5/90/45";
377 377 char *token;
378 378 char *lasts;
379 379
380 380 printf("tokenizing \"%s\" with strtok():\n", buf);
381 381 if ((token = strtok(buf, "/")) != NULL) {
382 382 printf("token = "%s\"\n", token);
383 383 while ((token = strtok(NULL, "/")) != NULL) {
384 384 printf("token = \"%s\"\n", token);
385 385 }
386 386 }
387 387
388 388 buf = "//5//90//45//";
389 389 printf("\ntokenizing \"%s\" with strtok_r():\n", buf);
390 390 if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
391 391 printf("token = \"%s\"\n", token);
392 392 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
393 393 printf("token = \"%s\"\n", token);
394 394 }
395 395 }
396 396 }
397 397
398 398
399 399 When compiled and run, this example produces the following output:
400 400
401 401
402 402 tokenizing "5/90/45" with strtok():
403 403 token = "5"
404 404 token = "90"
405 405 token = "45"
406 406
407 407 tokenizing "//5//90//45//" with strtok_r():
408 408 token = "5"
409 409 token = "90"
410 410 token = "45"
411 411
412 412
413 413 ATTRIBUTES
414 414 See attributes(5) for descriptions of the following attributes:
415 415
416 416 +--------------------+-----------------+
417 417 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
418 418 +--------------------+-----------------+
419 419 |Interface Stability | See below. |
420 420 +--------------------+-----------------+
421 421 |MT-Level | See below. |
422 422 +--------------------+-----------------+
423 423 |Standard | See below. |
424 424 +--------------------+-----------------+
425 425
426 426 The strlcat(), strlcpy(), and strsep() functions are Committed. All
427 427 the rest are Standard.
428 428
429 429 The strtok(), strdup(), and strndup() functions are MT-Safe. The
430 430 remaining functions are Async-Signal-Safe.
431 431
432 432 For all except strlcat(), strlcpy(), and strsep(), see standards(5).
433 433
434 434 SEE ALSO
435 435 malloc(3C), newlocale(3C), setlocale(3C), strxfrm(3C), uselocale(3C),
436 436 attributes(5), standards(5)
437 437
438 438 NOTES
439 439 When compiling multithreaded applications, the _REENTRANT flag must be
440 440 defined on the compile line. This flag should only be used in
441 441 multithreaded applications.
442 442
443 443 A single-threaded application can gain access to strtok_r() only by
444 444 defining __EXTENSIONS__ or by defining _POSIX_C_SOURCE to a value
445 445 greater than or equal to 199506L.
446 446
447 447 Except where noted otherwise, all of these functions assume the default
448 448 locale ``C.'' For some locales, strxfrm(3C) should be applied to the
449 449 strings before they are passed to the functions.
450 450
451 451 The strtok() function is safe to use in multithreaded applications
452 452 because it saves its internal state in a thread-specific data area.
453 453 However, its use is discouraged, even for single-threaded applications.
454 454 The strtok_r() function should be used instead.
455 455
456 456 Do not pass the address of a character string literal as the argument
457 457 s1 to either strtok() or strtok_r(). Similarly, do not pass a pointer
458 458 to the address of a character string literal as the argument stringp to
459 459 strsep(). These functions can modify the storage pointed to by s1 in
460 460 the case of strtok() and strtok_r() or *stringp in the case of
461 461 strsep(). The C99 standard specifies that attempting to modify the
462 462 storage occupied by a string literal results in undefined behavior.
463 463 This allows compilers (including gcc and the Sun Studio compilers when
464 464 the -xstrconst flag is used) to place string literals in read-only
465 465 memory. Note that in Example 1 above, this problem is avoided because
466 466 the variable line is declared as a writable array of type char that is
467 467 initialized by a string literal rather than a pointer to char that
468 468 points to a string literal.
469 469
470 470
471 471
472 472 March 23, 2016 STRING(3C)
|
↓ open down ↓ |
243 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX