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 || \
 145         defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K8
 146 /* Duplicate S, returning an identical malloc'd string.  */
 147 extern char *strdup (const char *__s)
 148      __THROW __attribute_malloc__ __nonnull ((1));
 149 libc_hidden_proto(strdup)
 150 #endif
 151
 152 /* Return a malloc'd copy of at most N bytes of STRING.  The
 153    resultant string is terminated even if no null terminator
 154    appears before STRING[N].  */
 155 #if defined __USE_XOPEN2K8
 156 extern char *strndup (const char *__string, size_t __n)
 157      __THROW __attribute_malloc__ __nonnull ((1));
 158 libc_hidden_proto(strndup)
 159 #endif
 160
 161 #if defined __USE_GNU && defined __GNUC__
 162 /* Duplicate S, returning an identical alloca'd string.  */
 163 # define strdupa(s)                                                           \
 164   (__extension__                                                              \
 165     ({                                                                        \
 166       const char *__old = (s);                                        \
 167       size_t __len = strlen (__old) + 1;                                      \
 168       char *__new = (char *) __builtin_alloca (__len);                        \
 169       (char *) memcpy (__new, __old, __len);                                  \
 170     }))
 171
 172 /* Return an alloca'd copy of at most N bytes of string.  */
 173 # define strndupa(s, n)                                                       \
 174   (__extension__                                                              \
 175     ({                                                                        \
 176       const char *__old = (s);                                        \
 177       size_t __len = strnlen (__old, (n));                                    \
 178       char *__new = (char *) __builtin_alloca (__len + 1);                    \
 179       __new[__len] = '\0';                                                    \
 180       (char *) memcpy (__new, __old, __len);                                  \
 181     }))
 182 #endif
 183
 184 __BEGIN_NAMESPACE_STD
 185 /* Find the first occurrence of C in S.  */
 186 extern char *strchr (const char *__s, int __c)
 187      __THROW __attribute_pure__ __nonnull ((1));
 188 libc_hidden_proto(strchr)
 189 /* Find the last occurrence of C in S.  */
 190 extern char *strrchr (const char *__s, int __c)
 191      __THROW __attribute_pure__ __nonnull ((1));
 192 libc_hidden_proto(strrchr)
 193 __END_NAMESPACE_STD
 194
 195 #ifdef __USE_GNU
 196 /* This function is similar to `strchr'.  But it returns a pointer to
 197    the closing NUL byte in case C is not found in S.  */
 198 extern char *strchrnul (const char *__s, int __c)
 199      __THROW __attribute_pure__ __nonnull ((1));
 200 libc_hidden_proto(strchrnul)
 201 #endif
 202
 203 __BEGIN_NAMESPACE_STD
 204 /* Return the length of the initial segment of S which
 205    consists entirely of characters not in REJECT.  */
 206 extern size_t strcspn (const char *__s, const char *__reject)
 207      __THROW __attribute_pure__ __nonnull ((1, 2));
 208 libc_hidden_proto(strcspn)
 209 /* Return the length of the initial segment of S which
 210    consists entirely of characters in ACCEPT.  */
 211 extern size_t strspn (const char *__s, const char *__accept)
 212      __THROW __attribute_pure__ __nonnull ((1, 2));
 213 libc_hidden_proto(strspn)
 214 /* Find the first occurrence in S of any character in ACCEPT.  */
 215 extern char *strpbrk (const char *__s, const char *__accept)
 216      __THROW __attribute_pure__ __nonnull ((1, 2));
 217 libc_hidden_proto(strpbrk)
 218 /* Find the first occurrence of NEEDLE in HAYSTACK.  */
 219 extern char *strstr (const char *__haystack, const char *__needle)
 220      __THROW __attribute_pure__ __nonnull ((1, 2));
 221 libc_hidden_proto(strstr)
 222
 223
 224 /* Divide S into tokens separated by characters in DELIM.  */
 225 extern char *strtok (char *__restrict __s, const char *__restrict __delim)
 226      __THROW __nonnull ((2));
 227 libc_hidden_proto(strtok)
 228 __END_NAMESPACE_STD
 229
 230 /* Divide S into tokens separated by characters in DELIM.  Information
 231    passed between calls are stored in SAVE_PTR.  */
 232 #if 0 /* uClibc: disabled */
 233 extern char *__strtok_r (char *__restrict __s,
 234                          const char *__restrict __delim,
 235                          char **__restrict __save_ptr)
 236      __THROW __nonnull ((2, 3));
 237 #endif
 238 #if defined __USE_POSIX || defined __USE_MISC
 239 extern char *strtok_r (char *__restrict __s, const char *__restrict __delim,
 240                        char **__restrict __save_ptr)
 241      __THROW __nonnull ((2, 3));
 242 libc_hidden_proto(strtok_r)
 243 #endif
 244
 245 #ifdef __USE_GNU
 246 /* Similar to `strstr' but this function ignores the case of both strings.  */
 247 extern char *strcasestr (const char *__haystack, const char *__needle)
 248      __THROW __attribute_pure__ __nonnull ((1, 2));
 249 libc_hidden_proto(strcasestr)
 250 #endif
 251
 252 #ifdef __USE_GNU
 253 /* Find the first occurrence of NEEDLE in HAYSTACK.
 254    NEEDLE is NEEDLELEN bytes long;
 255    HAYSTACK is HAYSTACKLEN bytes long.  */
 256 extern void *memmem (const void *__haystack, size_t __haystacklen,
 257                      const void *__needle, size_t __needlelen)
 258      __THROW __attribute_pure__ __nonnull ((1, 3));
 259
 260 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
 261    last written byte.  */
 262 #if __GNUC_PREREQ (3, 4)
 263 # define __mempcpy(dest, src, n) __builtin_mempcpy(dest, src, n)
 264 #else /* uClibc: disabled */
 265 extern void *__mempcpy (void *__restrict __dest,
 266                         const void *__restrict __src, size_t __n)
 267      __THROW __nonnull ((1, 2));
 268 #endif
 269 extern void *mempcpy (void *__restrict __dest,
 270                       const void *__restrict __src, size_t __n)
 271      __THROW __nonnull ((1, 2));
 272 libc_hidden_proto(mempcpy)
 273 #endif
 274
 275
 276 __BEGIN_NAMESPACE_STD
 277 /* Return the length of S.  */
 278 extern size_t strlen (const char *__s)
 279      __THROW __attribute_pure__ __nonnull ((1));
 280 libc_hidden_proto(strlen)
 281 __END_NAMESPACE_STD
 282
 283 #ifdef  __USE_XOPEN2K8
 284 /* Find the length of STRING, but scan at most MAXLEN characters.
 285    If no '\0' terminator is found in that many characters, return MAXLEN.  */
 286 extern size_t strnlen (const char *__string, size_t __maxlen)
 287      __THROW __attribute_pure__ __nonnull ((1));
 288 libc_hidden_proto(strnlen)
 289 #endif
 290
 291
 292 __BEGIN_NAMESPACE_STD
 293 /* Return a string describing the meaning of the `errno' code in ERRNUM.  */
 294 extern char *strerror (int __errnum) __THROW;
 295 libc_hidden_proto(strerror)
 296 __END_NAMESPACE_STD
 297 #if defined __USE_XOPEN2K || defined __USE_MISC
 298 /* Reentrant version of `strerror'.
 299    There are 2 flavors of `strerror_r', GNU which returns the string
 300    and may or may not use the supplied temporary buffer and POSIX one
 301    which fills the string into the buffer.
 302    To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
 303    without -D_GNU_SOURCE is needed, otherwise the GNU version is
 304    preferred.  */
 305 # if defined __USE_XOPEN2K && !defined __USE_GNU
 306 /* Fill BUF with a string describing the meaning of the `errno' code in
 307    ERRNUM.  */
 308 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
 309      __THROW __nonnull ((2));
 310 libc_hidden_proto(__xpg_strerror_r)
 311 #  ifdef __REDIRECT_NTH
 312 extern int __REDIRECT_NTH (strerror_r,
 313                            (int __errnum, char *__buf, size_t __buflen),
 314                            __xpg_strerror_r) __nonnull ((2));
 315 #  else
 316 #   define strerror_r __xpg_strerror_r
 317 #  endif
 318 # else
 319 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
 320    used.  */
 321 extern char *__glibc_strerror_r (int __errnum, char *__buf, size_t __buflen)
 322      __THROW __nonnull ((2));
 323 libc_hidden_proto(__glibc_strerror_r)
 324 #  ifdef __REDIRECT_NTH
 325 extern char * __REDIRECT_NTH (strerror_r,
 326                            (int __errnum, char *__buf, size_t __buflen),
 327                            __glibc_strerror_r) __nonnull ((2));
 328 #  else
 329 #   define strerror_r __glibc_strerror_r
 330 #  endif
 331 # endif
 332 #endif
 333
 334 #if 0 /*defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__*/
 335 /* Translate error number to string according to the locale L.  */
 336 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
 337 #endif
 338
 339
 340 /* We define this function always since `bzero' is sometimes needed when
 341    the namespace rules does not allow this.  */
 342 #if 0 /* uClibc: disabled */
 343 extern void __bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 344 #endif
 345
 346 #ifdef __USE_BSD
 347 # ifdef __UCLIBC_SUSV3_LEGACY__
 348 /* Copy N bytes of SRC to DEST (like memmove, but args reversed).  */
 349 extern void bcopy (const void *__src, void *__dest, size_t __n)
 350      __THROW __nonnull ((1, 2));
 351
 352 /* Set N bytes of S to 0.  */
 353 extern void bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 354
 355 /* Compare N bytes of S1 and S2 (same as memcmp).  */
 356 extern int bcmp (const void *__s1, const void *__s2, size_t __n)
 357      __THROW __attribute_pure__ __nonnull ((1, 2));
 358
 359 /* Find the first occurrence of C in S (same as strchr).  */
 360 extern char *index (const char *__s, int __c)
 361      __THROW __attribute_pure__ __nonnull ((1));
 362
 363 /* Find the last occurrence of C in S (same as strrchr).  */
 364 extern char *rindex (const char *__s, int __c)
 365      __THROW __attribute_pure__ __nonnull ((1));
 366 # elif defined(__UCLIBC_SUSV3_LEGACY_MACROS__) && !defined(_STRINGS_H)
 367 /* bcopy/bzero/bcmp/index/rindex are marked LEGACY in SuSv3.
 368  * They are replaced as proposed by SuSv3. Don't sync this part
 369  * with glibc and keep it in sync with strings.h.  */
 370
 371 /* Copy N bytes of SRC to DEST (like memmove, but args reversed).  */
 372 static __inline__ void bcopy (__const void *__src, void *__dest, size_t __n)
 373 {
 374         memmove(__dest, __src, __n);
 375 }
 376
 377 /* Set N bytes of S to 0.  */
 378 static __inline__ void bzero (void *__s, size_t __n)
 379 {
 380         memset(__s, 0, __n);
 381 }
 382
 383 /* Compare N bytes of S1 and S2 (same as memcmp).  */
 384 static __inline__ int bcmp (__const void *__s1, __const void *__s2, size_t __n)
 385 {
 386         return memcmp(__s1, __s2, __n);
 387 }
 388
 389 /* Find the first occurrence of C in S (same as strchr).  */
 390 static __inline__ char *index (__const char *__s, int __c)
 391 {
 392         return strchr(__s, __c);
 393 }
 394
 395 /* Find the last occurrence of C in S (same as strrchr).  */
 396 static __inline__ char *rindex (__const char *__s, int __c)
 397 {
 398         return strrchr(__s, __c);
 399 }
 400 # endif
 401
 402 /* Return the position of the first bit set in I, or 0 if none are set.
 403    The least-significant bit is position 1, the most-significant 32.  */
 404 extern int ffs (int __i) __THROW __attribute__ ((__const__));
 405 libc_hidden_proto(ffs)
 406
 407 /* The following two functions are non-standard but necessary for non-32 bit
 408    platforms.  */
 409 #ifdef __USE_GNU
 410 extern int ffsl (long int __l) __THROW __attribute__ ((__const__));
 411 #  ifdef __GNUC__
 412 __extension__ extern int ffsll (long long int __ll)
 413      __THROW __attribute__ ((__const__));
 414 #  endif
 415 # endif
 416
 417 /* Compare S1 and S2, ignoring case.  */
 418 extern int strcasecmp (const char *__s1, const char *__s2)
 419      __THROW __attribute_pure__ __nonnull ((1, 2));
 420 libc_hidden_proto(strcasecmp)
 421
 422 /* Compare no more than N chars of S1 and S2, ignoring case.  */
 423 extern int strncasecmp (const char *__s1, const char *__s2, size_t __n)
 424      __THROW __attribute_pure__ __nonnull ((1, 2));
 425 libc_hidden_proto(strncasecmp)
 426 #endif /* Use BSD.  */
 427
 428 #if defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__
 429 /* Again versions of a few functions which use the given locale instead
 430    of the global one.  */
 431 extern int strcasecmp_l (const char *__s1, const char *__s2,
 432                          __locale_t __loc)
 433      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
 434 libc_hidden_proto(strcasecmp_l)
 435
 436 extern int strncasecmp_l (const char *__s1, const char *__s2,
 437                           size_t __n, __locale_t __loc)
 438      __THROW __attribute_pure__ __nonnull ((1, 2, 4));
 439 libc_hidden_proto(strncasecmp_l)
 440 #endif
 441
 442 #ifdef  __USE_BSD
 443 /* Return the next DELIM-delimited token from *STRINGP,
 444    terminating it with a '\0', and update *STRINGP to point past it.  */
 445 extern char *strsep (char **__restrict __stringp,
 446                      const char *__restrict __delim)
 447      __THROW __nonnull ((1, 2));
 448 libc_hidden_proto(strsep)
 449 #endif
 450
 451 #ifdef  __USE_XOPEN2K8
 452 /* Return a string describing the meaning of the signal number in SIG.  */
 453 extern char *strsignal (int __sig) __THROW;
 454 libc_hidden_proto(strsignal)
 455
 456 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST.  */
 457 # if 0 /* uClibc: disabled */
 458 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
 459      __THROW __nonnull ((1, 2));
 460 # endif
 461 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
 462      __THROW __nonnull ((1, 2));
 463 libc_hidden_proto(stpcpy)
 464
 465 /* Copy no more than N characters of SRC to DEST, returning the address of
 466    the last character written into DEST.  */
 467 # if 0 /* uClibc: disabled */
 468 extern char *__stpncpy (char *__restrict __dest,
 469                         const char *__restrict __src, size_t __n)
 470      __THROW __nonnull ((1, 2));
 471 # endif
 472 extern char *stpncpy (char *__restrict __dest,
 473                       const char *__restrict __src, size_t __n)
 474      __THROW __nonnull ((1, 2));
 475 #endif
 476
 477 #ifdef __USE_GNU
 478 /* Compare S1 and S2 as strings holding name & indices/version numbers.  */
 479 extern int strverscmp (const char *__s1, const char *__s2)
 480      __THROW __attribute_pure__ __nonnull ((1, 2));
 481 libc_hidden_proto(strverscmp)
 482
 483 # if 0                  /* uClibc does not support strfry or memfrob. */
 484 /* Sautee STRING briskly.  */
 485 extern char *strfry (char *__string) __THROW __nonnull ((1));
 486
 487 /* Frobnicate N bytes of S.  */
 488 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
 489 # endif
 490
 491 # ifndef basename
 492 /* Return the file name within directory of FILENAME.  We don't
 493    declare the function if the `basename' macro is available (defined
 494    in <libgen.h>) which makes the XPG version of this function
 495    available.  */
 496 extern char *basename (const char *__filename) __THROW __nonnull ((1));
 497 # endif
 498 #endif /* __USE_GNU */
 499
 500
 501 #ifdef  __USE_BSD
 502 /* Two OpenBSD extension functions. */
 503 extern size_t strlcat(char *__restrict dst, const char *__restrict src,
 504                       size_t n) __THROW __nonnull ((1, 2));
 505 libc_hidden_proto(strlcat)
 506 extern size_t strlcpy(char *__restrict dst, const char *__restrict src,
 507                       size_t n) __THROW __nonnull ((1, 2));
 508 libc_hidden_proto(strlcpy)
 509 #endif
 510
 511 __END_DECLS
 512
 513
 514 #if defined(_LIBC) && defined(__UCLIBC_HAS_STRING_ARCH_OPT__)
 515 # if defined __i386__
 516 #  include <../libc/string/i386/string.h>
 517 # endif
 518 #endif
 519
 520 #endif /* string.h */