include/string.h

   1 /* Copyright (C) 1991-1993,1995-2004,2007,2009 Free Software Foundation, Inc.
   2    This file is part of the GNU C Library.
   3
   4    The GNU C Library is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU Lesser General Public
   6    License as published by the Free Software Foundation; either
   7    version 2.1 of the License, or (at your option) any later version.
   8
   9    The GNU C Library is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public
  15    License along with the GNU C Library; if not, see
  16    <http://www.gnu.org/licenses/>.  */
  17
  18 /*
  19  *      ISO C99 Standard: 7.21 String handling  <string.h>
  20  */
  21
  22 #ifndef _STRING_H
  23 #define _STRING_H       1
  24
  25 #include <features.h>
  26
  27 __BEGIN_DECLS
  28
  29 /* Get size_t and NULL from <stddef.h>.  */
  30 #define __need_size_t
  31 #define __need_NULL
  32 #include <stddef.h>
  33
  34
  35 __BEGIN_NAMESPACE_STD
  36 /* Copy N bytes of SRC to DEST.  */
  37 extern void *memcpy (void *__restrict __dest,
  38                      const void *__restrict __src, size_t __n)
  39      __THROW __nonnull ((1, 2));
  40 libc_hidden_proto(memcpy)
  41 /* Copy N bytes of SRC to DEST, guaranteeing
  42    correct behavior for overlapping strings.  */
  43 extern void *memmove (void *__dest, const void *__src, size_t __n)
  44      __THROW __nonnull ((1, 2));
  45 libc_hidden_proto(memmove)
  46 __END_NAMESPACE_STD
  47
  48 /* Copy no more than N bytes of SRC to DEST, stopping when C is found.
  49    Return the position in DEST one byte past where C was copied,
  50    or NULL if C was not found in the first N bytes of SRC.  */
  51 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN
  52 extern void *memccpy (void *__restrict __dest, const void *__restrict __src,
  53                       int __c, size_t __n)
  54      __THROW __nonnull ((1, 2));
  55 libc_hidden_proto(memccpy)
  56 #endif /* SVID.  */
  57
  58
  59 __BEGIN_NAMESPACE_STD
  60 /* Set N bytes of S to C.  */
  61 extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
  62 libc_hidden_proto(memset)
  63
  64 /* Compare N bytes of S1 and S2.  */
  65 extern int memcmp (const void *__s1, const void *__s2, size_t __n)
  66      __THROW __attribute_pure__ __nonnull ((1, 2));
  67 libc_hidden_proto(memcmp)
  68
  69 /* Search N bytes of S for C.  */
  70 extern void *memchr (const void *__s, int __c, size_t __n)
  71       __THROW __attribute_pure__ __nonnull ((1));
  72 libc_hidden_proto(memchr)
  73 __END_NAMESPACE_STD
  74
  75 #ifdef __USE_GNU
  76 /* Search in S for C.  This is similar to `memchr' but there is no
  77    length limit.  */
  78 extern void *rawmemchr (const void *__s, int __c)
  79      __THROW __attribute_pure__ __nonnull ((1));
  80 libc_hidden_proto(rawmemchr)
  81
  82 /* Search N bytes of S for the final occurrence of C.  */
  83 extern void *memrchr (const void *__s, int __c, size_t __n)
  84       __THROW __attribute_pure__ __nonnull ((1));
  85 libc_hidden_proto(memrchr)
  86 #endif
  87
  88
  89 __BEGIN_NAMESPACE_STD
  90 /* Copy SRC to DEST.  */
  91 extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
  92      __THROW __nonnull ((1, 2));
  93 libc_hidden_proto(strcpy)
  94 /* Copy no more than N characters of SRC to DEST.  */
  95 extern char *strncpy (char *__restrict __dest,
  96                       const char *__restrict __src, size_t __n)
  97      __THROW __nonnull ((1, 2));
  98 libc_hidden_proto(strncpy)
  99
 100 /* Append SRC onto DEST.  */
 101 extern char *strcat (char *__restrict __dest, const char *__restrict __src)
 102      __THROW __nonnull ((1, 2));
 103 libc_hidden_proto(strcat)
 104 /* Append no more than N characters from SRC onto DEST.  */
 105 extern char *strncat (char *__restrict __dest, const char *__restrict __src,
 106                       size_t __n) __THROW __nonnull ((1, 2));
 107 libc_hidden_proto(strncat)
 108
 109 /* Compare S1 and S2.  */
 110 extern int strcmp (const char *__s1, const char *__s2)
 111      __THROW __attribute_pure__ __nonnull ((1, 2));
 112 libc_hidden_proto(strcmp)
 113 /* Compare N characters of S1 and S2.  */
 114 extern int strncmp (const char *__s1, const char *__s2, size_t __n)
 115      __THROW __attribute_pure__ __nonnull ((1, 2));
 116 libc_hidden_proto(strncmp)
 117
 118 /* Compare the collated forms of S1 and S2.  */
 119 extern int strcoll (const char *__s1, const char *__s2)
 120      __THROW __attribute_pure__ __nonnull ((1, 2));
 121 libc_hidden_proto(strcoll)
 122 /* Put a transformation of SRC into no more than N bytes of DEST.  */
 123 extern size_t strxfrm (char *__restrict __dest,
 124                        const char *__restrict __src, size_t __n)
 125      __THROW __nonnull ((2));
 126 __END_NAMESPACE_STD
 127
 128 #if defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__
 129 /* The following functions are equivalent to the both above but they
 130    take the locale they use for the collation as an extra argument.
 131    This is not standardsized but something like will come.  */
 132 # include <xlocale.h>
 133
 134 /* Compare the collated forms of S1 and S2 using rules from L.  */
 135 extern int strcoll_l (const char *__s1, const char *__s2, __locale_t __l)
 136      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
 137 libc_hidden_proto(strcoll_l)
 138 /* Put a transformation of SRC into no more than N bytes of DEST.  */
 139 extern size_t strxfrm_l (char *__dest, const char *__src, size_t __n,
 140                          __locale_t __l) __THROW __nonnull ((2, 4));
 141 libc_hidden_proto(strxfrm_l)
 142 #endif
 143
 144 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED
 145 /* Duplicate S, returning an identical malloc'd string.  */
 146 extern char *strdup (const char *__s)
 147      __THROW __attribute_malloc__ __nonnull ((1));
 148 libc_hidden_proto(strdup)
 149 #endif
 150
 151 /* Return a malloc'd copy of at most N bytes of STRING.  The
 152    resultant string is terminated even if no null terminator
 153    appears before STRING[N].  */
 154 #if defined __USE_XOPEN2K8
 155 extern char *strndup (const char *__string, size_t __n)
 156      __THROW __attribute_malloc__ __nonnull ((1));
 157 libc_hidden_proto(strndup)
 158 #endif
 159
 160 #if defined __USE_GNU && defined __GNUC__
 161 /* Duplicate S, returning an identical alloca'd string.  */
 162 # define strdupa(s)                                                           \
 163   (__extension__                                                              \
 164     ({                                                                        \
 165       const char *__old = (s);                                        \
 166       size_t __len = strlen (__old) + 1;                                      \
 167       char *__new = (char *) __builtin_alloca (__len);                        \
 168       (char *) memcpy (__new, __old, __len);                                  \
 169     }))
 170
 171 /* Return an alloca'd copy of at most N bytes of string.  */
 172 # define strndupa(s, n)                                                       \
 173   (__extension__                                                              \
 174     ({                                                                        \
 175       const char *__old = (s);                                        \
 176       size_t __len = strnlen (__old, (n));                                    \
 177       char *__new = (char *) __builtin_alloca (__len + 1);                    \
 178       __new[__len] = '\0';                                                    \
 179       (char *) memcpy (__new, __old, __len);                                  \
 180     }))
 181 #endif
 182
 183 __BEGIN_NAMESPACE_STD
 184 /* Find the first occurrence of C in S.  */
 185 extern char *strchr (const char *__s, int __c)
 186      __THROW __attribute_pure__ __nonnull ((1));
 187 libc_hidden_proto(strchr)
 188 /* Find the last occurrence of C in S.  */
 189 extern char *strrchr (const char *__s, int __c)
 190      __THROW __attribute_pure__ __nonnull ((1));
 191 libc_hidden_proto(strrchr)
 192 __END_NAMESPACE_STD
 193
 194 #ifdef __USE_GNU
 195 /* This function is similar to `strchr'.  But it returns a pointer to
 196    the closing NUL byte in case C is not found in S.  */
 197 extern char *strchrnul (const char *__s, int __c)
 198      __THROW __attribute_pure__ __nonnull ((1));
 199 libc_hidden_proto(strchrnul)
 200 #endif
 201
 202 __BEGIN_NAMESPACE_STD
 203 /* Return the length of the initial segment of S which
 204    consists entirely of characters not in REJECT.  */
 205 extern size_t strcspn (const char *__s, const char *__reject)
 206      __THROW __attribute_pure__ __nonnull ((1, 2));
 207 libc_hidden_proto(strcspn)
 208 /* Return the length of the initial segment of S which
 209    consists entirely of characters in ACCEPT.  */
 210 extern size_t strspn (const char *__s, const char *__accept)
 211      __THROW __attribute_pure__ __nonnull ((1, 2));
 212 libc_hidden_proto(strspn)
 213 /* Find the first occurrence in S of any character in ACCEPT.  */
 214 extern char *strpbrk (const char *__s, const char *__accept)
 215      __THROW __attribute_pure__ __nonnull ((1, 2));
 216 libc_hidden_proto(strpbrk)
 217 /* Find the first occurrence of NEEDLE in HAYSTACK.  */
 218 extern char *strstr (const char *__haystack, const char *__needle)
 219      __THROW __attribute_pure__ __nonnull ((1, 2));
 220 libc_hidden_proto(strstr)
 221
 222
 223 /* Divide S into tokens separated by characters in DELIM.  */
 224 extern char *strtok (char *__restrict __s, const char *__restrict __delim)
 225      __THROW __nonnull ((2));
 226 libc_hidden_proto(strtok)
 227 __END_NAMESPACE_STD
 228
 229 /* Divide S into tokens separated by characters in DELIM.  Information
 230    passed between calls are stored in SAVE_PTR.  */
 231 #if 0 /* uClibc: disabled */
 232 extern char *__strtok_r (char *__restrict __s,
 233                          const char *__restrict __delim,
 234                          char **__restrict __save_ptr)
 235      __THROW __nonnull ((2, 3));
 236 #endif
 237 #if defined __USE_POSIX || defined __USE_MISC
 238 extern char *strtok_r (char *__restrict __s, const char *__restrict __delim,
 239                        char **__restrict __save_ptr)
 240      __THROW __nonnull ((2, 3));
 241 libc_hidden_proto(strtok_r)
 242 #endif
 243
 244 #ifdef __USE_GNU
 245 /* Similar to `strstr' but this function ignores the case of both strings.  */
 246 extern char *strcasestr (const char *__haystack, const char *__needle)
 247      __THROW __attribute_pure__ __nonnull ((1, 2));
 248 libc_hidden_proto(strcasestr)
 249 #endif
 250
 251 #ifdef __USE_GNU
 252 /* Find the first occurrence of NEEDLE in HAYSTACK.
 253    NEEDLE is NEEDLELEN bytes long;
 254    HAYSTACK is HAYSTACKLEN bytes long.  */
 255 extern void *memmem (const void *__haystack, size_t __haystacklen,
 256                      const void *__needle, size_t __needlelen)
 257      __THROW __attribute_pure__ __nonnull ((1, 3));
 258
 259 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
 260    last written byte.  */
 261 #if 0 /* uClibc: disabled */
 262 extern void *__mempcpy (void *__restrict __dest,
 263                         const void *__restrict __src, size_t __n)
 264      __THROW __nonnull ((1, 2));
 265 #endif
 266 extern void *mempcpy (void *__restrict __dest,
 267                       const void *__restrict __src, size_t __n)
 268      __THROW __nonnull ((1, 2));
 269 libc_hidden_proto(mempcpy)
 270 #endif
 271
 272
 273 __BEGIN_NAMESPACE_STD
 274 /* Return the length of S.  */
 275 extern size_t strlen (const char *__s)
 276      __THROW __attribute_pure__ __nonnull ((1));
 277 libc_hidden_proto(strlen)
 278 __END_NAMESPACE_STD
 279
 280 #ifdef  __USE_XOPEN2K8
 281 /* Find the length of STRING, but scan at most MAXLEN characters.
 282    If no '\0' terminator is found in that many characters, return MAXLEN.  */
 283 extern size_t strnlen (const char *__string, size_t __maxlen)
 284      __THROW __attribute_pure__ __nonnull ((1));
 285 libc_hidden_proto(strnlen)
 286 #endif
 287
 288
 289 __BEGIN_NAMESPACE_STD
 290 /* Return a string describing the meaning of the `errno' code in ERRNUM.  */
 291 extern char *strerror (int __errnum) __THROW;
 292 libc_hidden_proto(strerror)
 293 __END_NAMESPACE_STD
 294 #if defined __USE_XOPEN2K || defined __USE_MISC
 295 /* Reentrant version of `strerror'.
 296    There are 2 flavors of `strerror_r', GNU which returns the string
 297    and may or may not use the supplied temporary buffer and POSIX one
 298    which fills the string into the buffer.
 299    To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
 300    without -D_GNU_SOURCE is needed, otherwise the GNU version is
 301    preferred.  */
 302 # if defined __USE_XOPEN2K && !defined __USE_GNU
 303 /* Fill BUF with a string describing the meaning of the `errno' code in
 304    ERRNUM.  */
 305 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
 306      __THROW __nonnull ((2));
 307 libc_hidden_proto(__xpg_strerror_r)
 308 #  ifdef __REDIRECT_NTH
 309 extern int __REDIRECT_NTH (strerror_r,
 310                            (int __errnum, char *__buf, size_t __buflen),
 311                            __xpg_strerror_r) __nonnull ((2));
 312 #  else
 313 #   define strerror_r __xpg_strerror_r
 314 #  endif
 315 # else
 316 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
 317    used.  */
 318 extern char *__glibc_strerror_r (int __errnum, char *__buf, size_t __buflen)
 319      __THROW __nonnull ((2));
 320 libc_hidden_proto(__glibc_strerror_r)
 321 #  ifdef __REDIRECT_NTH
 322 extern char * __REDIRECT_NTH (strerror_r,
 323                            (int __errnum, char *__buf, size_t __buflen),
 324                            __glibc_strerror_r) __nonnull ((2));
 325 #  else
 326 #   define strerror_r __glibc_strerror_r
 327 #  endif
 328 # endif
 329 #endif
 330
 331 #if 0 /*defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__*/
 332 /* Translate error number to string according to the locale L.  */
 333 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
 334 #endif
 335
 336
 337 /* We define this function always since `bzero' is sometimes needed when
 338    the namespace rules does not allow this.  */
 339 #if 0 /* uClibc: disabled */
 340 extern void __bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 341 #endif
 342
 343 #ifdef __USE_BSD
 344 # ifdef __UCLIBC_SUSV3_LEGACY__
 345 /* Copy N bytes of SRC to DEST (like memmove, but args reversed).  */
 346 extern void bcopy (const void *__src, void *__dest, size_t __n)
 347      __THROW __nonnull ((1, 2));
 348
 349 /* Set N bytes of S to 0.  */
 350 extern void bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 351
 352 /* Compare N bytes of S1 and S2 (same as memcmp).  */
 353 extern int bcmp (const void *__s1, const void *__s2, size_t __n)
 354      __THROW __attribute_pure__ __nonnull ((1, 2));
 355
 356 /* Find the first occurrence of C in S (same as strchr).  */
 357 extern char *index (const char *__s, int __c)
 358      __THROW __attribute_pure__ __nonnull ((1));
 359
 360 /* Find the last occurrence of C in S (same as strrchr).  */
 361 extern char *rindex (const char *__s, int __c)
 362      __THROW __attribute_pure__ __nonnull ((1));
 363 # else
 364 #  ifdef __UCLIBC_SUSV3_LEGACY_MACROS__
 365 /* bcopy/bzero/bcmp/index/rindex are marked LEGACY in SuSv3.
 366  * They are replaced as proposed by SuSv3. Don't sync this part
 367  * with glibc and keep it in sync with strings.h.  */
 368
 369 #  define bcopy(src,dest,n) (memmove((dest), (src), (n)), (void) 0)
 370 #  define bzero(s,n) (memset((s), '\0', (n)), (void) 0)
 371 #  define bcmp(s1,s2,n) memcmp((s1), (s2), (size_t)(n))
 372 #  define index(s,c) strchr((s), (c))
 373 #  define rindex(s,c) strrchr((s), (c))
 374 #  endif
 375 # endif
 376
 377 /* Return the position of the first bit set in I, or 0 if none are set.
 378    The least-significant bit is position 1, the most-significant 32.  */
 379 extern int ffs (int __i) __THROW __attribute__ ((__const__));
 380 libc_hidden_proto(ffs)
 381
 382 /* The following two functions are non-standard but necessary for non-32 bit
 383    platforms.  */
 384 #ifdef __USE_GNU
 385 extern int ffsl (long int __l) __THROW __attribute__ ((__const__));
 386 #  ifdef __GNUC__
 387 __extension__ extern int ffsll (long long int __ll)
 388      __THROW __attribute__ ((__const__));
 389 #  endif
 390 # endif
 391
 392 /* Compare S1 and S2, ignoring case.  */
 393 extern int strcasecmp (const char *__s1, const char *__s2)
 394      __THROW __attribute_pure__ __nonnull ((1, 2));
 395 libc_hidden_proto(strcasecmp)
 396
 397 /* Compare no more than N chars of S1 and S2, ignoring case.  */
 398 extern int strncasecmp (const char *__s1, const char *__s2, size_t __n)
 399      __THROW __attribute_pure__ __nonnull ((1, 2));
 400 libc_hidden_proto(strncasecmp)
 401 #endif /* Use BSD.  */
 402
 403 #if defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__
 404 /* Again versions of a few functions which use the given locale instead
 405    of the global one.  */
 406 extern int strcasecmp_l (const char *__s1, const char *__s2,
 407                          __locale_t __loc)
 408      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
 409 libc_hidden_proto(strcasecmp_l)
 410
 411 extern int strncasecmp_l (const char *__s1, const char *__s2,
 412                           size_t __n, __locale_t __loc)
 413      __THROW __attribute_pure__ __nonnull ((1, 2, 4));
 414 libc_hidden_proto(strncasecmp_l)
 415 #endif
 416
 417 #ifdef  __USE_BSD
 418 /* Return the next DELIM-delimited token from *STRINGP,
 419    terminating it with a '\0', and update *STRINGP to point past it.  */
 420 extern char *strsep (char **__restrict __stringp,
 421                      const char *__restrict __delim)
 422      __THROW __nonnull ((1, 2));
 423 libc_hidden_proto(strsep)
 424 #endif
 425
 426 #ifdef  __USE_XOPEN2K8
 427 /* Return a string describing the meaning of the signal number in SIG.  */
 428 extern char *strsignal (int __sig) __THROW;
 429 libc_hidden_proto(strsignal)
 430
 431 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST.  */
 432 # if 0 /* uClibc: disabled */
 433 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
 434      __THROW __nonnull ((1, 2));
 435 # endif
 436 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
 437      __THROW __nonnull ((1, 2));
 438 libc_hidden_proto(stpcpy)
 439
 440 /* Copy no more than N characters of SRC to DEST, returning the address of
 441    the last character written into DEST.  */
 442 # if 0 /* uClibc: disabled */
 443 extern char *__stpncpy (char *__restrict __dest,
 444                         const char *__restrict __src, size_t __n)
 445      __THROW __nonnull ((1, 2));
 446 # endif
 447 extern char *stpncpy (char *__restrict __dest,
 448                       const char *__restrict __src, size_t __n)
 449      __THROW __nonnull ((1, 2));
 450 #endif
 451
 452 #ifdef __USE_GNU
 453 /* Compare S1 and S2 as strings holding name & indices/version numbers.  */
 454 extern int strverscmp (const char *__s1, const char *__s2)
 455      __THROW __attribute_pure__ __nonnull ((1, 2));
 456 libc_hidden_proto(strverscmp)
 457
 458 # if 0                  /* uClibc does not support strfry or memfrob. */
 459 /* Sautee STRING briskly.  */
 460 extern char *strfry (char *__string) __THROW __nonnull ((1));
 461
 462 /* Frobnicate N bytes of S.  */
 463 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
 464 # endif
 465
 466 # ifndef basename
 467 /* Return the file name within directory of FILENAME.  We don't
 468    declare the function if the `basename' macro is available (defined
 469    in <libgen.h>) which makes the XPG version of this function
 470    available.  */
 471 extern char *basename (const char *__filename) __THROW __nonnull ((1));
 472 # endif
 473 #endif /* __USE_GNU */
 474
 475
 476 #ifdef  __USE_BSD
 477 /* Two OpenBSD extension functions. */
 478 extern size_t strlcat(char *__restrict dst, const char *__restrict src,
 479                       size_t n) __THROW __nonnull ((1, 2));
 480 libc_hidden_proto(strlcat)
 481 extern size_t strlcpy(char *__restrict dst, const char *__restrict src,
 482                       size_t n) __THROW __nonnull ((1, 2));
 483 libc_hidden_proto(strlcpy)
 484 #endif
 485
 486 __END_DECLS
 487
 488
 489 #if defined(_LIBC) && defined(__UCLIBC_HAS_STRING_ARCH_OPT__)
 490 # if defined __i386__
 491 #  include <../libc/string/i386/string.h>
 492 # endif
 493 #endif
 494
 495 #endif /* string.h */