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 __GNUC_PREREQ (3, 4)
 262 # define __mempcpy(dest, src, n) __builtin_mempcpy(dest, src, n)
 263 #else /* uClibc: disabled */
 264 extern void *__mempcpy (void *__restrict __dest,
 265                         const void *__restrict __src, size_t __n)
 266      __THROW __nonnull ((1, 2));
 267 #endif
 268 extern void *mempcpy (void *__restrict __dest,
 269                       const void *__restrict __src, size_t __n)
 270      __THROW __nonnull ((1, 2));
 271 libc_hidden_proto(mempcpy)
 272 #endif
 273
 274
 275 __BEGIN_NAMESPACE_STD
 276 /* Return the length of S.  */
 277 extern size_t strlen (const char *__s)
 278      __THROW __attribute_pure__ __nonnull ((1));
 279 libc_hidden_proto(strlen)
 280 __END_NAMESPACE_STD
 281
 282 #ifdef  __USE_XOPEN2K8
 283 /* Find the length of STRING, but scan at most MAXLEN characters.
 284    If no '\0' terminator is found in that many characters, return MAXLEN.  */
 285 extern size_t strnlen (const char *__string, size_t __maxlen)
 286      __THROW __attribute_pure__ __nonnull ((1));
 287 libc_hidden_proto(strnlen)
 288 #endif
 289
 290
 291 __BEGIN_NAMESPACE_STD
 292 /* Return a string describing the meaning of the `errno' code in ERRNUM.  */
 293 extern char *strerror (int __errnum) __THROW;
 294 libc_hidden_proto(strerror)
 295 __END_NAMESPACE_STD
 296 #if defined __USE_XOPEN2K || defined __USE_MISC
 297 /* Reentrant version of `strerror'.
 298    There are 2 flavors of `strerror_r', GNU which returns the string
 299    and may or may not use the supplied temporary buffer and POSIX one
 300    which fills the string into the buffer.
 301    To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
 302    without -D_GNU_SOURCE is needed, otherwise the GNU version is
 303    preferred.  */
 304 # if defined __USE_XOPEN2K && !defined __USE_GNU
 305 /* Fill BUF with a string describing the meaning of the `errno' code in
 306    ERRNUM.  */
 307 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
 308      __THROW __nonnull ((2));
 309 libc_hidden_proto(__xpg_strerror_r)
 310 #  ifdef __REDIRECT_NTH
 311 extern int __REDIRECT_NTH (strerror_r,
 312                            (int __errnum, char *__buf, size_t __buflen),
 313                            __xpg_strerror_r) __nonnull ((2));
 314 #  else
 315 #   define strerror_r __xpg_strerror_r
 316 #  endif
 317 # else
 318 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
 319    used.  */
 320 extern char *__glibc_strerror_r (int __errnum, char *__buf, size_t __buflen)
 321      __THROW __nonnull ((2));
 322 libc_hidden_proto(__glibc_strerror_r)
 323 #  ifdef __REDIRECT_NTH
 324 extern char * __REDIRECT_NTH (strerror_r,
 325                            (int __errnum, char *__buf, size_t __buflen),
 326                            __glibc_strerror_r) __nonnull ((2));
 327 #  else
 328 #   define strerror_r __glibc_strerror_r
 329 #  endif
 330 # endif
 331 #endif
 332
 333 #if 0 /*defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__*/
 334 /* Translate error number to string according to the locale L.  */
 335 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
 336 #endif
 337
 338
 339 /* We define this function always since `bzero' is sometimes needed when
 340    the namespace rules does not allow this.  */
 341 #if 0 /* uClibc: disabled */
 342 extern void __bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 343 #endif
 344
 345 #ifdef __USE_BSD
 346 # ifdef __UCLIBC_SUSV3_LEGACY__
 347 /* Copy N bytes of SRC to DEST (like memmove, but args reversed).  */
 348 extern void bcopy (const void *__src, void *__dest, size_t __n)
 349      __THROW __nonnull ((1, 2));
 350
 351 /* Set N bytes of S to 0.  */
 352 extern void bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 353
 354 /* Compare N bytes of S1 and S2 (same as memcmp).  */
 355 extern int bcmp (const void *__s1, const void *__s2, size_t __n)
 356      __THROW __attribute_pure__ __nonnull ((1, 2));
 357
 358 /* Find the first occurrence of C in S (same as strchr).  */
 359 extern char *index (const char *__s, int __c)
 360      __THROW __attribute_pure__ __nonnull ((1));
 361
 362 /* Find the last occurrence of C in S (same as strrchr).  */
 363 extern char *rindex (const char *__s, int __c)
 364      __THROW __attribute_pure__ __nonnull ((1));
 365 # elif defined(__UCLIBC_SUSV3_LEGACY_MACROS__) && !defined(_STRINGS_H)
 366 /* bcopy/bzero/bcmp/index/rindex are marked LEGACY in SuSv3.
 367  * They are replaced as proposed by SuSv3. Don't sync this part
 368  * with glibc and keep it in sync with strings.h.  */
 369
 370 /* Copy N bytes of SRC to DEST (like memmove, but args reversed).  */
 371 static __inline__ void bcopy (__const void *__src, void *__dest, size_t __n)
 372 {
 373         memmove(__dest, __src, __n);
 374 }
 375
 376 /* Set N bytes of S to 0.  */
 377 static __inline__ void bzero (void *__s, size_t __n)
 378 {
 379         memset(__s, 0, __n);
 380 }
 381
 382 /* Compare N bytes of S1 and S2 (same as memcmp).  */
 383 static __inline__ int bcmp (__const void *__s1, __const void *__s2, size_t __n)
 384 {
 385         return memcmp(__s1, __s2, __n);
 386 }
 387
 388 /* Find the first occurrence of C in S (same as strchr).  */
 389 static __inline__ char *index (__const char *__s, int __c)
 390 {
 391         return strchr(__s, __c);
 392 }
 393
 394 /* Find the last occurrence of C in S (same as strrchr).  */
 395 static __inline__ char *rindex (__const char *__s, int __c)
 396 {
 397         return strrchr(__s, __c);
 398 }
 399 # endif
 400
 401 /* Return the position of the first bit set in I, or 0 if none are set.
 402    The least-significant bit is position 1, the most-significant 32.  */
 403 extern int ffs (int __i) __THROW __attribute__ ((__const__));
 404 libc_hidden_proto(ffs)
 405
 406 /* The following two functions are non-standard but necessary for non-32 bit
 407    platforms.  */
 408 #ifdef __USE_GNU
 409 extern int ffsl (long int __l) __THROW __attribute__ ((__const__));
 410 #  ifdef __GNUC__
 411 __extension__ extern int ffsll (long long int __ll)
 412      __THROW __attribute__ ((__const__));
 413 #  endif
 414 # endif
 415
 416 /* Compare S1 and S2, ignoring case.  */
 417 extern int strcasecmp (const char *__s1, const char *__s2)
 418      __THROW __attribute_pure__ __nonnull ((1, 2));
 419 libc_hidden_proto(strcasecmp)
 420
 421 /* Compare no more than N chars of S1 and S2, ignoring case.  */
 422 extern int strncasecmp (const char *__s1, const char *__s2, size_t __n)
 423      __THROW __attribute_pure__ __nonnull ((1, 2));
 424 libc_hidden_proto(strncasecmp)
 425 #endif /* Use BSD.  */
 426
 427 #if defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__
 428 /* Again versions of a few functions which use the given locale instead
 429    of the global one.  */
 430 extern int strcasecmp_l (const char *__s1, const char *__s2,
 431                          __locale_t __loc)
 432      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
 433 libc_hidden_proto(strcasecmp_l)
 434
 435 extern int strncasecmp_l (const char *__s1, const char *__s2,
 436                           size_t __n, __locale_t __loc)
 437      __THROW __attribute_pure__ __nonnull ((1, 2, 4));
 438 libc_hidden_proto(strncasecmp_l)
 439 #endif
 440
 441 #ifdef  __USE_BSD
 442 /* Return the next DELIM-delimited token from *STRINGP,
 443    terminating it with a '\0', and update *STRINGP to point past it.  */
 444 extern char *strsep (char **__restrict __stringp,
 445                      const char *__restrict __delim)
 446      __THROW __nonnull ((1, 2));
 447 libc_hidden_proto(strsep)
 448 #endif
 449
 450 #ifdef  __USE_XOPEN2K8
 451 /* Return a string describing the meaning of the signal number in SIG.  */
 452 extern char *strsignal (int __sig) __THROW;
 453 libc_hidden_proto(strsignal)
 454
 455 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST.  */
 456 # if 0 /* uClibc: disabled */
 457 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
 458      __THROW __nonnull ((1, 2));
 459 # endif
 460 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
 461      __THROW __nonnull ((1, 2));
 462 libc_hidden_proto(stpcpy)
 463
 464 /* Copy no more than N characters of SRC to DEST, returning the address of
 465    the last character written into DEST.  */
 466 # if 0 /* uClibc: disabled */
 467 extern char *__stpncpy (char *__restrict __dest,
 468                         const char *__restrict __src, size_t __n)
 469      __THROW __nonnull ((1, 2));
 470 # endif
 471 extern char *stpncpy (char *__restrict __dest,
 472                       const char *__restrict __src, size_t __n)
 473      __THROW __nonnull ((1, 2));
 474 #endif
 475
 476 #ifdef __USE_GNU
 477 /* Compare S1 and S2 as strings holding name & indices/version numbers.  */
 478 extern int strverscmp (const char *__s1, const char *__s2)
 479      __THROW __attribute_pure__ __nonnull ((1, 2));
 480 libc_hidden_proto(strverscmp)
 481
 482 # if 0                  /* uClibc does not support strfry or memfrob. */
 483 /* Sautee STRING briskly.  */
 484 extern char *strfry (char *__string) __THROW __nonnull ((1));
 485
 486 /* Frobnicate N bytes of S.  */
 487 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
 488 # endif
 489
 490 # ifndef basename
 491 /* Return the file name within directory of FILENAME.  We don't
 492    declare the function if the `basename' macro is available (defined
 493    in <libgen.h>) which makes the XPG version of this function
 494    available.  */
 495 extern char *basename (const char *__filename) __THROW __nonnull ((1));
 496 # endif
 497 #endif /* __USE_GNU */
 498
 499
 500 #ifdef  __USE_BSD
 501 /* Two OpenBSD extension functions. */
 502 extern size_t strlcat(char *__restrict dst, const char *__restrict src,
 503                       size_t n) __THROW __nonnull ((1, 2));
 504 libc_hidden_proto(strlcat)
 505 extern size_t strlcpy(char *__restrict dst, const char *__restrict src,
 506                       size_t n) __THROW __nonnull ((1, 2));
 507 libc_hidden_proto(strlcpy)
 508 #endif
 509
 510 __END_DECLS
 511
 512
 513 #if defined(_LIBC) && defined(__UCLIBC_HAS_STRING_ARCH_OPT__)
 514 # if defined __i386__
 515 #  include <../libc/string/i386/string.h>
 516 # endif
 517 #endif
 518
 519 #endif /* string.h */