1string(3C) Standard C Library Functions string(3C)
2
6 string, strcasecmp, strncasecmp, strcat, strncat, strlcat, strchr, str‐
7 rchr, strcmp, strncmp, strcpy, strncpy, strlcpy, strcspn, strspn,
8 strdup, strlen, strnlen, strpbrk, strsep, strstr, strtok, strtok_r -
9 string operations
10
12 #include <strings.h>
13 int strcasecmp(const char *s1, const char *s2);
15 int strncasecmp(const char *s1, const char *s2, size_t n);
18 #include <string.h>
21 char *strcat(char *restrict s1, const char *restrict s2);
23 char *strncat(char *restrict s1, const char *restrict s2, size_t n);
26 size_t strlcat(char *dst, const char *src, size_t dstsize);
29 char *strchr(const char *s, int c);
32 char *strrchr(const char *s, int c);
35 int strcmp(const char *s1, const char *s2);
38 int strncmp(const char *s1, const char *s2, size_t n);
41 char *strcpy(char *restrict s1, const char *restrict s2);
44 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
47 size_t strlcpy(char *dst, const char *src, size_t dstsize);
50 size_t strcspn(const char *s1, const char *s2);
53 size_t strspn(const char *s1, const char *s2);
56 char *strdup(const char *s1);
59 size_t strlen(const char *s);
62 size_t strnlen(const char *s, size_t n);
65 char *strpbrk(const char *s1, const char *s2);
68 char *strsep(char **stringp, const char *delim);
71 char *strstr(const char *s1, const char *s2);
74 char *strtok(char *restrict s1, const char *restrict s2);
77 char *strtok_r(char *s1, const char *s2, char **lasts);
80 ISO C++
83 #include <string.h>
84 const char *strchr(const char *s, int c);
86 const char *strpbrk(const char *s1, const char *s2);
89 const char *strrchr(const char *s, int c);
92 const char *strstr(const char *s1, const char *s2);
95 #include <cstring>
98 char *std::strchr(char *s, int c);
100 char *std::strpbrk(char *s1, const char *s2);
103 char *std::strrchr(char *s, int c);
106 char *std::strstr(char *s1, const char *s2);
109
112 The arguments s, s1, and s2 point to strings (arrays of characters ter‐
113 minated by a null character). The strcat(), strncat(), strlcat(), str‐
114 cpy(), strncpy(), strlcpy(), strsep(), strtok(), and strtok_r() func‐
115 tions all alter their first argument. Additionally, the strcat() and
116 strcpy() functions do not check for overflow of the array.
117 strcasecmp(), strncasecmp()
119 The strcasecmp() and strncasecmp() functions are case-insensitive ver‐
120 sions of strcmp() and strncmp() respectively, described below. They
121 assume the ASCII character set and ignore differences in case when com‐
122 paring lower and upper case characters.
123 strcat(), strncat(), strlcat()
125 The strcat() function appends a copy of string s2, including the termi‐
126 nating null character, to the end of string s1. The strncat() function
127 appends at most n characters. Each returns a pointer to the null-termi‐
128 nated result. The initial character of s2 overrides the null character
129 at the end of s1. If copying takes place between objects that overlap,
130 the behavior of strcat(), strncat(), and strlcat() is undefined.
131 The strlcat() function appends at most (dstsize-strlen(dst)-1) char‐
134 acters of src to dst (dstsize being the size of the string buffer
135 dst). If the string pointed to by dst contains a null-terminated string
136 that fits into dstsize bytes when strlcat() is called, the string
137 pointed to by dst will be a null-terminated string that fits in dstsize
138 bytes (including the terminating null character) when it completes, and
139 the initial character of src will override the null character at the
140 end of dst. If the string pointed to by dst is longer than dstsize
141 bytes when strlcat() is called, the string pointed to by dst will not
142 be changed. The function returns min{dstsize,strlen(dst)}+strlen(src).
143 Buffer overflow can be checked as follows:
144 if (strlcat(dst, src, dstsize) >= dstsize)
146 return −1;
147 strchr(), strrchr()
150 The strchr() function returns a pointer to the first occurrence of c
151 (converted to a char) in string s, or a null pointer if c does not
152 occur in the string. The strrchr() function returns a pointer to the
153 last occurrence of c. The null character terminating a string is con‐
154 sidered to be part of the string.
155 strcmp(), strncmp()
157 The strcmp() function compares two strings byte-by-byte, according to
158 the ordering of your machine's character set. The function returns an
159 integer greater than, equal to, or less than 0, if the string pointed
160 to by s1 is greater than, equal to, or less than the string pointed to
161 by s2 respectively. The sign of a non-zero return value is determined
162 by the sign of the difference between the values of the first pair of
163 bytes that differ in the strings being compared. The strncmp() function
164 makes the same comparison but looks at a maximum of n bytes. Bytes fol‐
165 lowing a null byte are not compared.
166 strcpy(), strncpy(), strlcpy()
168 The strcpy() function copies string s2 to s1, including the terminating
169 null character, stopping after the null character has been copied. The
170 strncpy() function copies exactly n bytes, truncating s2 or adding null
171 characters to s1 if necessary. The result will not be null-terminated
172 if the length of s2 is n or more. Each function returns s1. If copying
173 takes place between objects that overlap, the behavior of strcpy(),
174 strncpy(), and strlcpy() is undefined.
175 The strlcpy() function copies at most dstsize−1 characters (dstsize
178 being the size of the string buffer dst) from src to dst, truncating
179 src if necessary. The result is always null-terminated. The function
180 returns strlen(src). Buffer overflow can be checked as follows:
181 if (strlcpy(dst, src, dstsize) >= dstsize)
183 return −1;
184 strcspn(), strspn()
187 The strcspn() function returns the length of the initial segment of
188 string s1 that consists entirely of characters not from string s2. The
189 strspn() function returns the length of the initial segment of string
190 s1 that consists entirely of characters from string s2.
191 strdup()
193 The strdup() function returns a pointer to a new string that is a
194 duplicate of the string pointed to by s1. The returned pointer can be
195 passed to free(). The space for the new string is obtained using mal‐
196 loc(3C). If the new string cannot be created, a null pointer is
197 returned and errno may be set to ENOMEM to indicate that the storage
198 space available is insufficient.
199 strlen(), strnlen()
201 The strlen() function returns the number of bytes in s, not including
202 the terminating null character.
203 The strnlen() function returns the smaller of n or the number of bytes
206 in s, not including the terminating null character. The strnlen() func‐
207 tion never examines more than n bytes of the string pointed to by s.
208 strpbrk()
210 The strpbrk() function returns a pointer to the first occurrence in
211 string s1 of any character from string s2, or a null pointer if no
212 character from s2 exists in s1.
213 strsep()
215 The strsep() function locates, in the null-terminated string referenced
216 by *stringp, the first occurrence of any character in the string delim
217 (or the terminating `\0' character) and replaces it with a `\0'. The
218 location of the next character after the delimiter character (or NULL,
219 if the end of the string was reached) is stored in *stringp. The orig‐
220 inal value of *stringp is returned.
221 An ``empty'' field (one caused by two adjacent delimiter characters)
224 can be detected by comparing the location referenced by the pointer
225 returned by strsep() to `\0'.
226 If *stringp is initially NULL, strsep() returns NULL.
229 strstr()
231 The strstr() function locates the first occurrence of the string s2
232 (excluding the terminating null character) in string s1 and returns a
233 pointer to the located string, or a null pointer if the string is not
234 found. If s2 points to a string with zero length (that is, the string
235 ""), the function returns s1.
236 strtok()
238 A sequence of calls to strtok() breaks the string pointed to by s1 into
239 a sequence of tokens, each of which is delimited by a byte from the
240 string pointed to by s2. The first call in the sequence has s1 as its
241 first argument, and is followed by calls with a null pointer as their
242 first argument. The separator string pointed to by s2 can be different
243 from call to call.
244 The first call in the sequence searches the string pointed to by s1 for
247 the first byte that is not contained in the current separator string
248 pointed to by s2. If no such byte is found, then there are no tokens in
249 the string pointed to by s1 and strtok() returns a null pointer. If
250 such a byte is found, it is the start of the first token.
251 The strtok() function then searches from there for a byte that is con‐
254 tained in the current separator string. If no such byte is found, the
255 current token extends to the end of the string pointed to by s1, and
256 subsequent searches for a token return a null pointer. If such a byte
257 is found, it is overwritten by a null byte that terminates the current
258 token. The strtok() function saves a pointer to the following byte in
259 thread-specific data, from which the next search for a token starts.
260 Each subsequent call, with a null pointer as the value of the first
263 argument, starts searching from the saved pointer and behaves as
264 described above.
265 See Example 1, 2, and 3 in the EXAMPLES section for examples of str‐
268 tok() usage and the explanation in NOTES.
269 strtok_r()
271 The strtok_r() function considers the null-terminated string s1 as a
272 sequence of zero or more text tokens separated by spans of one or more
273 characters from the separator string s2. The argument lasts points to a
274 user-provided pointer which points to stored information necessary for
275 strtok_r() to continue scanning the same string.
276 In the first call to strtok_r(), s1 points to a null-terminated string,
279 s2 to a null-terminated string of separator characters, and the value
280 pointed to by lasts is ignored. The strtok_r() function returns a
281 pointer to the first character of the first token, writes a null char‐
282 acter into s1 immediately following the returned token, and updates the
283 pointer to which lasts points.
284 In subsequent calls, s1 is a null pointer and lasts is unchanged from
287 the previous call so that subsequent calls move through the string s1,
288 returning successive tokens until no tokens remain. The separator
289 string s2 can be different from call to call. When no token remains in
290 s1, a null pointer is returned.
291 See Example 3 in the EXAMPLES section for an example of strtok_r()
294 usage and the explanation in NOTES.
295
297 Example 1 Search for word separators.
298 The following example searches for tokens separated by space charac‐
301 ters.
302 #include <string.h>
305 ...
306 char *token;
307 char line[] = "LINE TO BE SEPARATED";
308 char *search = " ";
309 /* Token will point to "LINE". */
311 token = strtok(line, search);
312 /* Token will point to "TO". */
314 token = strtok(NULL, search);
315 Example 2 Break a Line.
318 The following example uses strtok to break a line into two character
321 strings separated by any combination of SPACEs, TABs, or NEWLINEs.
322 #include <string.h>
325 ...
326 struct element {
327 char *key;
328 char *data;
329 };
330 ...
331 char line[LINE_MAX];
332 char *key, *data;
333 ...
334 key = strtok(line, " \n");
335 data = strtok(NULL, " \n");
336 Example 3 Search for tokens.
339 The following example uses both strtok() and strtok_r() to search for
342 tokens separated by one or more characters from the string pointed to
343 by the second argument, "/".
344 #define __EXTENSIONS__
347 #include <stdio.h>
348 #include <string.h>
349 int
351 main() {
352 char *buf="5/90/45";
353 char *token;
354 char *lasts;
355 printf("tokenizing \"%s\" with strtok():\n", buf);
357 if ((token = strtok(buf, "/")) != NULL) {
358 printf("token = "%s\"\n", token);
359 while ((token = strtok(NULL, "/")) != NULL) {
360 printf("token = \"%s\"\n", token);
361 }
362 }
363 buf = "//5//90//45//";
365 printf("\ntokenizing \"%s\" with strtok_r():\n", buf);
366 if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
367 printf("token = \"%s\"\n", token);
368 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
369 printf("token = \"%s\"\n", token);
370 }
371 }
372 }
373 When compiled and run, this example produces the following output:
377 tokenizing "5/90/45" with strtok():
380 token = "5"
381 token = "90"
382 token = "45"
383 tokenizing "//5//90//45//" with strtok_r():
385 token = "5"
386 token = "90"
387 token = "45"
388
391 See attributes(5) for descriptions of the following attributes:
392 ┌─────────────────────────────┬─────────────────────────────┐
397 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
398 ├─────────────────────────────┼─────────────────────────────┤
399 │Interface Stability │Committed │
400 ├─────────────────────────────┼─────────────────────────────┤
401 │MT-Level │See below. │
402 ├─────────────────────────────┼─────────────────────────────┤
403 │Standard │See below. │
404 └─────────────────────────────┴─────────────────────────────┘
405 The strtok() and strdup() functions are MT-Safe. The remaining func‐
408 tions are Async-Signal-Safe.
409 For all except strlcat(), strlcpy(), and strsep(), see standards(5).
412
414 malloc(3C), setlocale(3C), strxfrm(3C), attributes(5), standards(5)
415
417 When compiling multithreaded applications, the _REENTRANT flag must be
418 defined on the compile line. This flag should only be used in multi‐
419 threaded applications.
420 A single-threaded application can gain access to strtok_r() only by
423 defining __EXTENSIONS__ or by defining _POSIX_C_SOURCE to a value
424 greater than or equal to 199506L.
425 All of these functions assume the default locale ``C.'' For some
428 locales, strxfrm(3C) should be applied to the strings before they are
429 passed to the functions.
430 The strtok() function is safe to use in multithreaded applications
433 because it saves its internal state in a thread-specific data area.
434 However, its use is discouraged, even for single-threaded applications.
435 The strtok_r() function should be used instead.
436 Do not pass the address of a character string literal as the argument
439 s1 to either strtok() or strtok_r(). Similarly, do not pass a pointer
440 to the address of a character string literal as the argument stringp to
441 strsep(). These functions can modify the storage pointed to by s1 in
442 the case of strtok() and strtok_r() or *stringp in the case of
443 strsep(). The C99 standard specifies that attempting to modify the
444 storage occupied by a string literal results in undefined behavior.
445 This allows compilers (including gcc and the Sun Studio compilers when
446 the -xstrconst flag is used) to place string literals in read-only mem‐
447 ory. Note that in Example 1 above, this problem is avoided because the
448 variable line is declared as a writable array of type char that is ini‐
449 tialized by a string literal rather than a pointer to char that points
450 to a string literal.
451SunOS 5.11 1 Aug 2008 string(3C)