1 /* Copyright (C) 1991-1993,1995-2004,2007,2009,2010,2012
2 Free Software Foundation, Inc.
3 This file is part of the GNU C Library.
5 The GNU C Library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
10 The GNU C Library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public
16 License along with the GNU C Library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 * ISO C99 Standard: 7.21 String handling <string.h>
31 /* Get size_t and NULL from <stddef.h>. */
36 /* Tell the caller that we provide correct C++ prototypes. */
37 #if defined __cplusplus && __GNUC_PREREQ (4, 4)
38 # define __CORRECT_ISO_CPP_STRING_H_PROTO
43 /* Copy N bytes of SRC to DEST. */
44 extern void *memcpy (void *__restrict __dest, const void *__restrict __src,
45 size_t __n) __THROW __nonnull ((1, 2));
46 /* Copy N bytes of SRC to DEST, guaranteeing
47 correct behavior for overlapping strings. */
48 extern void *memmove (void *__dest, const void *__src, size_t __n)
49 __THROW __nonnull ((1, 2));
52 /* Copy no more than N bytes of SRC to DEST, stopping when C is found.
53 Return the position in DEST one byte past where C was copied,
54 or NULL if C was not found in the first N bytes of SRC. */
55 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN
56 extern void *memccpy (void *__restrict __dest, const void *__restrict __src,
58 __THROW __nonnull ((1, 2));
63 /* Set N bytes of S to C. */
64 extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
66 /* Compare N bytes of S1 and S2. */
67 extern int memcmp (const void *__s1, const void *__s2, size_t __n)
68 __THROW __attribute_pure__ __nonnull ((1, 2));
70 /* Search N bytes of S for C. */
71 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
74 extern void *memchr (void *__s, int __c, size_t __n)
75 __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
76 extern const void *memchr (const void *__s, int __c, size_t __n)
77 __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
80 __extern_always_inline void *
81 memchr (void *__s, int __c, size_t __n) __THROW
83 return __builtin_memchr (__s, __c, __n);
86 __extern_always_inline const void *
87 memchr (const void *__s, int __c, size_t __n) __THROW
89 return __builtin_memchr (__s, __c, __n);
94 extern void *memchr (const void *__s, int __c, size_t __n)
95 __THROW __attribute_pure__ __nonnull ((1));
100 /* Search in S for C. This is similar to `memchr' but there is no
102 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
103 extern "C++" void *rawmemchr (void *__s, int __c)
104 __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
105 extern "C++" const void *rawmemchr (const void *__s, int __c)
106 __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
108 extern void *rawmemchr (const void *__s, int __c)
109 __THROW __attribute_pure__ __nonnull ((1));
112 /* Search N bytes of S for the final occurrence of C. */
113 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
114 extern "C++" void *memrchr (void *__s, int __c, size_t __n)
115 __THROW __asm ("memrchr") __attribute_pure__ __nonnull ((1));
116 extern "C++" const void *memrchr (const void *__s, int __c, size_t __n)
117 __THROW __asm ("memrchr") __attribute_pure__ __nonnull ((1));
119 extern void *memrchr (const void *__s, int __c, size_t __n)
120 __THROW __attribute_pure__ __nonnull ((1));
125 __BEGIN_NAMESPACE_STD
126 /* Copy SRC to DEST. */
127 extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
128 __THROW __nonnull ((1, 2));
129 /* Copy no more than N characters of SRC to DEST. */
130 extern char *strncpy (char *__restrict __dest,
131 const char *__restrict __src, size_t __n)
132 __THROW __nonnull ((1, 2));
134 /* Append SRC onto DEST. */
135 extern char *strcat (char *__restrict __dest, const char *__restrict __src)
136 __THROW __nonnull ((1, 2));
137 /* Append no more than N characters from SRC onto DEST. */
138 extern char *strncat (char *__restrict __dest, const char *__restrict __src,
139 size_t __n) __THROW __nonnull ((1, 2));
141 /* Compare S1 and S2. */
142 extern int strcmp (const char *__s1, const char *__s2)
143 __THROW __attribute_pure__ __nonnull ((1, 2));
144 /* Compare N characters of S1 and S2. */
145 extern int strncmp (const char *__s1, const char *__s2, size_t __n)
146 __THROW __attribute_pure__ __nonnull ((1, 2));
148 /* Compare the collated forms of S1 and S2. */
149 extern int strcoll (const char *__s1, const char *__s2)
150 __THROW __attribute_pure__ __nonnull ((1, 2));
151 /* Put a transformation of SRC into no more than N bytes of DEST. */
152 extern size_t strxfrm (char *__restrict __dest,
153 const char *__restrict __src, size_t __n)
154 __THROW __nonnull ((2));
157 #ifdef __USE_XOPEN2K8
158 /* The following functions are equivalent to the both above but they
159 take the locale they use for the collation as an extra argument.
160 This is not standardsized but something like will come. */
161 # include <xlocale.h>
163 /* Compare the collated forms of S1 and S2 using rules from L. */
164 extern int strcoll_l (const char *__s1, const char *__s2, __locale_t __l)
165 __THROW __attribute_pure__ __nonnull ((1, 2, 3));
166 /* Put a transformation of SRC into no more than N bytes of DEST. */
167 extern size_t strxfrm_l (char *__dest, const char *__src, size_t __n,
168 __locale_t __l) __THROW __nonnull ((2, 4));
171 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED \
172 || defined __USE_XOPEN2K8
173 /* Duplicate S, returning an identical malloc'd string. */
174 extern char *strdup (const char *__s)
175 __THROW __attribute_malloc__ __nonnull ((1));
178 /* Return a malloc'd copy of at most N bytes of STRING. The
179 resultant string is terminated even if no null terminator
180 appears before STRING[N]. */
181 #if defined __USE_XOPEN2K8
182 extern char *strndup (const char *__string, size_t __n)
183 __THROW __attribute_malloc__ __nonnull ((1));
186 #if defined __USE_GNU && defined __GNUC__
187 /* Duplicate S, returning an identical alloca'd string. */
188 # define strdupa(s) \
191 const char *__old = (s); \
192 size_t __len = strlen (__old) + 1; \
193 char *__new = (char *) __builtin_alloca (__len); \
194 (char *) memcpy (__new, __old, __len); \
197 /* Return an alloca'd copy of at most N bytes of string. */
198 # define strndupa(s, n) \
201 const char *__old = (s); \
202 size_t __len = strnlen (__old, (n)); \
203 char *__new = (char *) __builtin_alloca (__len + 1); \
204 __new[__len] = '\0'; \
205 (char *) memcpy (__new, __old, __len); \
209 __BEGIN_NAMESPACE_STD
210 /* Find the first occurrence of C in S. */
211 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
214 extern char *strchr (char *__s, int __c)
215 __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
216 extern const char *strchr (const char *__s, int __c)
217 __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
220 __extern_always_inline char *
221 strchr (char *__s, int __c) __THROW
223 return __builtin_strchr (__s, __c);
226 __extern_always_inline const char *
227 strchr (const char *__s, int __c) __THROW
229 return __builtin_strchr (__s, __c);
234 extern char *strchr (const char *__s, int __c)
235 __THROW __attribute_pure__ __nonnull ((1));
237 /* Find the last occurrence of C in S. */
238 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
241 extern char *strrchr (char *__s, int __c)
242 __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
243 extern const char *strrchr (const char *__s, int __c)
244 __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
247 __extern_always_inline char *
248 strrchr (char *__s, int __c) __THROW
250 return __builtin_strrchr (__s, __c);
253 __extern_always_inline const char *
254 strrchr (const char *__s, int __c) __THROW
256 return __builtin_strrchr (__s, __c);
261 extern char *strrchr (const char *__s, int __c)
262 __THROW __attribute_pure__ __nonnull ((1));
267 /* This function is similar to `strchr'. But it returns a pointer to
268 the closing NUL byte in case C is not found in S. */
269 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
270 extern "C++" char *strchrnul (char *__s, int __c)
271 __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
272 extern "C++" const char *strchrnul (const char *__s, int __c)
273 __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
275 extern char *strchrnul (const char *__s, int __c)
276 __THROW __attribute_pure__ __nonnull ((1));
280 __BEGIN_NAMESPACE_STD
281 /* Return the length of the initial segment of S which
282 consists entirely of characters not in REJECT. */
283 extern size_t strcspn (const char *__s, const char *__reject)
284 __THROW __attribute_pure__ __nonnull ((1, 2));
285 /* Return the length of the initial segment of S which
286 consists entirely of characters in ACCEPT. */
287 extern size_t strspn (const char *__s, const char *__accept)
288 __THROW __attribute_pure__ __nonnull ((1, 2));
289 /* Find the first occurrence in S of any character in ACCEPT. */
290 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
293 extern char *strpbrk (char *__s, const char *__accept)
294 __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
295 extern const char *strpbrk (const char *__s, const char *__accept)
296 __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
299 __extern_always_inline char *
300 strpbrk (char *__s, const char *__accept) __THROW
302 return __builtin_strpbrk (__s, __accept);
305 __extern_always_inline const char *
306 strpbrk (const char *__s, const char *__accept) __THROW
308 return __builtin_strpbrk (__s, __accept);
313 extern char *strpbrk (const char *__s, const char *__accept)
314 __THROW __attribute_pure__ __nonnull ((1, 2));
316 /* Find the first occurrence of NEEDLE in HAYSTACK. */
317 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
320 extern char *strstr (char *__haystack, const char *__needle)
321 __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
322 extern const char *strstr (const char *__haystack, const char *__needle)
323 __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
326 __extern_always_inline char *
327 strstr (char *__haystack, const char *__needle) __THROW
329 return __builtin_strstr (__haystack, __needle);
332 __extern_always_inline const char *
333 strstr (const char *__haystack, const char *__needle) __THROW
335 return __builtin_strstr (__haystack, __needle);
340 extern char *strstr (const char *__haystack, const char *__needle)
341 __THROW __attribute_pure__ __nonnull ((1, 2));
345 /* Divide S into tokens separated by characters in DELIM. */
346 extern char *strtok (char *__restrict __s, const char *__restrict __delim)
347 __THROW __nonnull ((2));
350 /* Divide S into tokens separated by characters in DELIM. Information
351 passed between calls are stored in SAVE_PTR. */
352 extern char *__strtok_r (char *__restrict __s,
353 const char *__restrict __delim,
354 char **__restrict __save_ptr)
355 __THROW __nonnull ((2, 3));
356 #if defined __USE_POSIX || defined __USE_MISC
357 extern char *strtok_r (char *__restrict __s, const char *__restrict __delim,
358 char **__restrict __save_ptr)
359 __THROW __nonnull ((2, 3));
363 /* Similar to `strstr' but this function ignores the case of both strings. */
364 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
365 extern "C++" char *strcasestr (char *__haystack, const char *__needle)
366 __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
367 extern "C++" const char *strcasestr (const char *__haystack,
368 const char *__needle)
369 __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
371 extern char *strcasestr (const char *__haystack, const char *__needle)
372 __THROW __attribute_pure__ __nonnull ((1, 2));
377 /* Find the first occurrence of NEEDLE in HAYSTACK.
378 NEEDLE is NEEDLELEN bytes long;
379 HAYSTACK is HAYSTACKLEN bytes long. */
380 extern void *memmem (const void *__haystack, size_t __haystacklen,
381 const void *__needle, size_t __needlelen)
382 __THROW __attribute_pure__ __nonnull ((1, 3));
384 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
385 last written byte. */
386 extern void *__mempcpy (void *__restrict __dest,
387 const void *__restrict __src, size_t __n)
388 __THROW __nonnull ((1, 2));
389 extern void *mempcpy (void *__restrict __dest,
390 const void *__restrict __src, size_t __n)
391 __THROW __nonnull ((1, 2));
395 __BEGIN_NAMESPACE_STD
396 /* Return the length of S. */
397 extern size_t strlen (const char *__s)
398 __THROW __attribute_pure__ __nonnull ((1));
401 #ifdef __USE_XOPEN2K8
402 /* Find the length of STRING, but scan at most MAXLEN characters.
403 If no '\0' terminator is found in that many characters, return MAXLEN. */
404 extern size_t strnlen (const char *__string, size_t __maxlen)
405 __THROW __attribute_pure__ __nonnull ((1));
409 __BEGIN_NAMESPACE_STD
410 /* Return a string describing the meaning of the `errno' code in ERRNUM. */
411 extern char *strerror (int __errnum) __THROW;
413 #if defined __USE_XOPEN2K || defined __USE_MISC
414 /* Reentrant version of `strerror'.
415 There are 2 flavors of `strerror_r', GNU which returns the string
416 and may or may not use the supplied temporary buffer and POSIX one
417 which fills the string into the buffer.
418 To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
419 without -D_GNU_SOURCE is needed, otherwise the GNU version is
421 # if defined __USE_XOPEN2K && !defined __USE_GNU
422 /* Fill BUF with a string describing the meaning of the `errno' code in
424 # ifdef __REDIRECT_NTH
425 extern int __REDIRECT_NTH (strerror_r,
426 (int __errnum, char *__buf, size_t __buflen),
427 __xpg_strerror_r) __nonnull ((2));
429 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
430 __THROW __nonnull ((2));
431 # define strerror_r __xpg_strerror_r
434 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
436 extern char *strerror_r (int __errnum, char *__buf, size_t __buflen)
437 __THROW __nonnull ((2));
441 #ifdef __USE_XOPEN2K8
442 /* Translate error number to string according to the locale L. */
443 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
447 /* We define this function always since `bzero' is sometimes needed when
448 the namespace rules does not allow this. */
449 extern void __bzero (void *__s, size_t __n) __THROW __nonnull ((1));
452 /* Copy N bytes of SRC to DEST (like memmove, but args reversed). */
453 extern void bcopy (const void *__src, void *__dest, size_t __n)
454 __THROW __nonnull ((1, 2));
456 /* Set N bytes of S to 0. */
457 extern void bzero (void *__s, size_t __n) __THROW __nonnull ((1));
459 /* Compare N bytes of S1 and S2 (same as memcmp). */
460 extern int bcmp (const void *__s1, const void *__s2, size_t __n)
461 __THROW __attribute_pure__ __nonnull ((1, 2));
463 /* Find the first occurrence of C in S (same as strchr). */
464 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
467 extern char *index (char *__s, int __c)
468 __THROW __asm ("index") __attribute_pure__ __nonnull ((1));
469 extern const char *index (const char *__s, int __c)
470 __THROW __asm ("index") __attribute_pure__ __nonnull ((1));
472 # if defined __OPTIMIZE__ && !defined __CORRECT_ISO_CPP_STRINGS_H_PROTO
473 __extern_always_inline char *
474 index (char *__s, int __c) __THROW
476 return __builtin_index (__s, __c);
479 __extern_always_inline const char *
480 index (const char *__s, int __c) __THROW
482 return __builtin_index (__s, __c);
487 extern char *index (const char *__s, int __c)
488 __THROW __attribute_pure__ __nonnull ((1));
491 /* Find the last occurrence of C in S (same as strrchr). */
492 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
495 extern char *rindex (char *__s, int __c)
496 __THROW __asm ("rindex") __attribute_pure__ __nonnull ((1));
497 extern const char *rindex (const char *__s, int __c)
498 __THROW __asm ("rindex") __attribute_pure__ __nonnull ((1));
500 # if defined __OPTIMIZE__ && !defined __CORRECT_ISO_CPP_STRINGS_H_PROTO
501 __extern_always_inline char *
502 rindex (char *__s, int __c) __THROW
504 return __builtin_rindex (__s, __c);
507 __extern_always_inline const char *
508 rindex (const char *__s, int __c) __THROW
510 return __builtin_rindex (__s, __c);
515 extern char *rindex (const char *__s, int __c)
516 __THROW __attribute_pure__ __nonnull ((1));
519 /* Return the position of the first bit set in I, or 0 if none are set.
520 The least-significant bit is position 1, the most-significant 32. */
521 extern int ffs (int __i) __THROW __attribute__ ((__const__));
523 /* The following two functions are non-standard but necessary for non-32 bit
526 extern int ffsl (long int __l) __THROW __attribute__ ((__const__));
528 __extension__ extern int ffsll (long long int __ll)
529 __THROW __attribute__ ((__const__));
533 /* Compare S1 and S2, ignoring case. */
534 extern int strcasecmp (const char *__s1, const char *__s2)
535 __THROW __attribute_pure__ __nonnull ((1, 2));
537 /* Compare no more than N chars of S1 and S2, ignoring case. */
538 extern int strncasecmp (const char *__s1, const char *__s2, size_t __n)
539 __THROW __attribute_pure__ __nonnull ((1, 2));
540 #endif /* Use BSD. */
543 /* Again versions of a few functions which use the given locale instead
544 of the global one. */
545 extern int strcasecmp_l (const char *__s1, const char *__s2,
547 __THROW __attribute_pure__ __nonnull ((1, 2, 3));
549 extern int strncasecmp_l (const char *__s1, const char *__s2,
550 size_t __n, __locale_t __loc)
551 __THROW __attribute_pure__ __nonnull ((1, 2, 4));
555 /* Return the next DELIM-delimited token from *STRINGP,
556 terminating it with a '\0', and update *STRINGP to point past it. */
557 extern char *strsep (char **__restrict __stringp,
558 const char *__restrict __delim)
559 __THROW __nonnull ((1, 2));
562 #ifdef __USE_XOPEN2K8
563 /* Return a string describing the meaning of the signal number in SIG. */
564 extern char *strsignal (int __sig) __THROW;
566 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST. */
567 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
568 __THROW __nonnull ((1, 2));
569 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
570 __THROW __nonnull ((1, 2));
572 /* Copy no more than N characters of SRC to DEST, returning the address of
573 the last character written into DEST. */
574 extern char *__stpncpy (char *__restrict __dest,
575 const char *__restrict __src, size_t __n)
576 __THROW __nonnull ((1, 2));
577 extern char *stpncpy (char *__restrict __dest,
578 const char *__restrict __src, size_t __n)
579 __THROW __nonnull ((1, 2));
583 /* Compare S1 and S2 as strings holding name & indices/version numbers. */
584 extern int strverscmp (const char *__s1, const char *__s2)
585 __THROW __attribute_pure__ __nonnull ((1, 2));
587 /* Sautee STRING briskly. */
588 extern char *strfry (char *__string) __THROW __nonnull ((1));
590 /* Frobnicate N bytes of S. */
591 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
594 /* Return the file name within directory of FILENAME. We don't
595 declare the function if the `basename' macro is available (defined
596 in <libgen.h>) which makes the XPG version of this function
598 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
599 extern "C++" char *basename (char *__filename)
600 __THROW __asm ("basename") __nonnull ((1));
601 extern "C++" const char *basename (const char *__filename)
602 __THROW __asm ("basename") __nonnull ((1));
604 extern char *basename (const char *__filename) __THROW __nonnull ((1));
610 #if defined __GNUC__ && __GNUC__ >= 2
611 # if defined __OPTIMIZE__ && !defined __OPTIMIZE_SIZE__ \
612 && !defined __NO_INLINE__ && !defined __cplusplus
613 /* When using GNU CC we provide some optimized versions of selected
614 functions from this header. There are two kinds of optimizations:
616 - machine-dependent optimizations, most probably using inline
617 assembler code; these might be quite expensive since the code
618 size can increase significantly.
619 These optimizations are not used unless the symbol
621 is defined before including this header.
623 - machine-independent optimizations which do not increase the
624 code size significantly and which optimize mainly situations
625 where one or more arguments are compile-time constants.
626 These optimizations are used always when the compiler is
629 One can inhibit all optimizations by defining __NO_STRING_INLINES. */
631 /* Get the machine-dependent optimizations (if any). */
632 # include <bits/string.h>
634 /* These are generic optimizations which do not add too much inline code. */
635 # include <bits/string2.h>
638 # if __USE_FORTIFY_LEVEL > 0 && defined __extern_always_inline
639 /* Functions with security checks. */
640 # include <bits/string3.h>
646 #endif /* string.h */