string/string.h

   1 /* Copyright (C) 1991-2017 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 #define __GLIBC_INTERNAL_STARTING_HEADER_IMPLEMENTATION
  26 #include <bits/libc-header-start.h>
  27
  28 __BEGIN_DECLS
  29
  30 /* Get size_t and NULL from <stddef.h>.  */
  31 #define __need_size_t
  32 #define __need_NULL
  33 #include <stddef.h>
  34
  35 /* Tell the caller that we provide correct C++ prototypes.  */
  36 #if defined __cplusplus && __GNUC_PREREQ (4, 4)
  37 # define __CORRECT_ISO_CPP_STRING_H_PROTO
  38 #endif
  39
  40
  41 /* Copy N bytes of SRC to DEST.  */
  42 extern void *memcpy (void *__restrict __dest, const void *__restrict __src,
  43                      size_t __n) __THROW __nonnull ((1, 2));
  44 /* Copy N bytes of SRC to DEST, guaranteeing
  45    correct behavior for overlapping strings.  */
  46 extern void *memmove (void *__dest, const void *__src, size_t __n)
  47      __THROW __nonnull ((1, 2));
  48
  49 /* Copy no more than N bytes of SRC to DEST, stopping when C is found.
  50    Return the position in DEST one byte past where C was copied,
  51    or NULL if C was not found in the first N bytes of SRC.  */
  52 #if defined __USE_MISC || defined __USE_XOPEN
  53 extern void *memccpy (void *__restrict __dest, const void *__restrict __src,
  54                       int __c, size_t __n)
  55      __THROW __nonnull ((1, 2));
  56 #endif /* Misc || X/Open.  */
  57
  58
  59 /* Set N bytes of S to C.  */
  60 extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
  61
  62 /* Compare N bytes of S1 and S2.  */
  63 extern int memcmp (const void *__s1, const void *__s2, size_t __n)
  64      __THROW __attribute_pure__ __nonnull ((1, 2));
  65
  66 /* Search N bytes of S for C.  */
  67 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
  68 extern "C++"
  69 {
  70 extern void *memchr (void *__s, int __c, size_t __n)
  71       __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
  72 extern const void *memchr (const void *__s, int __c, size_t __n)
  73       __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
  74
  75 # ifdef __OPTIMIZE__
  76 __extern_always_inline void *
  77 memchr (void *__s, int __c, size_t __n) __THROW
  78 {
  79   return __builtin_memchr (__s, __c, __n);
  80 }
  81
  82 __extern_always_inline const void *
  83 memchr (const void *__s, int __c, size_t __n) __THROW
  84 {
  85   return __builtin_memchr (__s, __c, __n);
  86 }
  87 # endif
  88 }
  89 #else
  90 extern void *memchr (const void *__s, int __c, size_t __n)
  91       __THROW __attribute_pure__ __nonnull ((1));
  92 #endif
  93
  94 #ifdef __USE_GNU
  95 /* Search in S for C.  This is similar to `memchr' but there is no
  96    length limit.  */
  97 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
  98 extern "C++" void *rawmemchr (void *__s, int __c)
  99      __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
 100 extern "C++" const void *rawmemchr (const void *__s, int __c)
 101      __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
 102 # else
 103 extern void *rawmemchr (const void *__s, int __c)
 104      __THROW __attribute_pure__ __nonnull ((1));
 105 # endif
 106
 107 /* Search N bytes of S for the final occurrence of C.  */
 108 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 109 extern "C++" void *memrchr (void *__s, int __c, size_t __n)
 110       __THROW __asm ("memrchr") __attribute_pure__ __nonnull ((1));
 111 extern "C++" const void *memrchr (const void *__s, int __c, size_t __n)
 112       __THROW __asm ("memrchr") __attribute_pure__ __nonnull ((1));
 113 # else
 114 extern void *memrchr (const void *__s, int __c, size_t __n)
 115       __THROW __attribute_pure__ __nonnull ((1));
 116 # endif
 117 #endif
 118
 119
 120 /* Copy SRC to DEST.  */
 121 extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
 122      __THROW __nonnull ((1, 2));
 123 /* Copy no more than N characters of SRC to DEST.  */
 124 extern char *strncpy (char *__restrict __dest,
 125                       const char *__restrict __src, size_t __n)
 126      __THROW __nonnull ((1, 2));
 127
 128 /* Append SRC onto DEST.  */
 129 extern char *strcat (char *__restrict __dest, const char *__restrict __src)
 130      __THROW __nonnull ((1, 2));
 131 /* Append no more than N characters from SRC onto DEST.  */
 132 extern char *strncat (char *__restrict __dest, const char *__restrict __src,
 133                       size_t __n) __THROW __nonnull ((1, 2));
 134
 135 /* Compare S1 and S2.  */
 136 extern int strcmp (const char *__s1, const char *__s2)
 137      __THROW __attribute_pure__ __nonnull ((1, 2));
 138 /* Compare N characters of S1 and S2.  */
 139 extern int strncmp (const char *__s1, const char *__s2, size_t __n)
 140      __THROW __attribute_pure__ __nonnull ((1, 2));
 141
 142 /* Compare the collated forms of S1 and S2.  */
 143 extern int strcoll (const char *__s1, const char *__s2)
 144      __THROW __attribute_pure__ __nonnull ((1, 2));
 145 /* Put a transformation of SRC into no more than N bytes of DEST.  */
 146 extern size_t strxfrm (char *__restrict __dest,
 147                        const char *__restrict __src, size_t __n)
 148      __THROW __nonnull ((2));
 149
 150 #ifdef __USE_XOPEN2K8
 151 # include <xlocale.h>
 152
 153 /* Compare the collated forms of S1 and S2, using sorting rules from L.  */
 154 extern int strcoll_l (const char *__s1, const char *__s2, __locale_t __l)
 155      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
 156 /* Put a transformation of SRC into no more than N bytes of DEST,
 157    using sorting rules from L.  */
 158 extern size_t strxfrm_l (char *__dest, const char *__src, size_t __n,
 159                          __locale_t __l) __THROW __nonnull ((2, 4));
 160 #endif
 161
 162 #if (defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K8     \
 163      || __GLIBC_USE (LIB_EXT2))
 164 /* Duplicate S, returning an identical malloc'd string.  */
 165 extern char *strdup (const char *__s)
 166      __THROW __attribute_malloc__ __nonnull ((1));
 167 #endif
 168
 169 /* Return a malloc'd copy of at most N bytes of STRING.  The
 170    resultant string is terminated even if no null terminator
 171    appears before STRING[N].  */
 172 #if defined __USE_XOPEN2K8 || __GLIBC_USE (LIB_EXT2)
 173 extern char *strndup (const char *__string, size_t __n)
 174      __THROW __attribute_malloc__ __nonnull ((1));
 175 #endif
 176
 177 #if defined __USE_GNU && defined __GNUC__
 178 /* Duplicate S, returning an identical alloca'd string.  */
 179 # define strdupa(s)                                                           \
 180   (__extension__                                                              \
 181     ({                                                                        \
 182       const char *__old = (s);                                                \
 183       size_t __len = strlen (__old) + 1;                                      \
 184       char *__new = (char *) __builtin_alloca (__len);                        \
 185       (char *) memcpy (__new, __old, __len);                                  \
 186     }))
 187
 188 /* Return an alloca'd copy of at most N bytes of string.  */
 189 # define strndupa(s, n)                                                       \
 190   (__extension__                                                              \
 191     ({                                                                        \
 192       const char *__old = (s);                                                \
 193       size_t __len = strnlen (__old, (n));                                    \
 194       char *__new = (char *) __builtin_alloca (__len + 1);                    \
 195       __new[__len] = '\0';                                                    \
 196       (char *) memcpy (__new, __old, __len);                                  \
 197     }))
 198 #endif
 199
 200 /* Find the first occurrence of C in S.  */
 201 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 202 extern "C++"
 203 {
 204 extern char *strchr (char *__s, int __c)
 205      __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
 206 extern const char *strchr (const char *__s, int __c)
 207      __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
 208
 209 # ifdef __OPTIMIZE__
 210 __extern_always_inline char *
 211 strchr (char *__s, int __c) __THROW
 212 {
 213   return __builtin_strchr (__s, __c);
 214 }
 215
 216 __extern_always_inline const char *
 217 strchr (const char *__s, int __c) __THROW
 218 {
 219   return __builtin_strchr (__s, __c);
 220 }
 221 # endif
 222 }
 223 #else
 224 extern char *strchr (const char *__s, int __c)
 225      __THROW __attribute_pure__ __nonnull ((1));
 226 #endif
 227 /* Find the last occurrence of C in S.  */
 228 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 229 extern "C++"
 230 {
 231 extern char *strrchr (char *__s, int __c)
 232      __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
 233 extern const char *strrchr (const char *__s, int __c)
 234      __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
 235
 236 # ifdef __OPTIMIZE__
 237 __extern_always_inline char *
 238 strrchr (char *__s, int __c) __THROW
 239 {
 240   return __builtin_strrchr (__s, __c);
 241 }
 242
 243 __extern_always_inline const char *
 244 strrchr (const char *__s, int __c) __THROW
 245 {
 246   return __builtin_strrchr (__s, __c);
 247 }
 248 # endif
 249 }
 250 #else
 251 extern char *strrchr (const char *__s, int __c)
 252      __THROW __attribute_pure__ __nonnull ((1));
 253 #endif
 254
 255 #ifdef __USE_GNU
 256 /* This function is similar to `strchr'.  But it returns a pointer to
 257    the closing NUL byte in case C is not found in S.  */
 258 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 259 extern "C++" char *strchrnul (char *__s, int __c)
 260      __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
 261 extern "C++" const char *strchrnul (const char *__s, int __c)
 262      __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
 263 # else
 264 extern char *strchrnul (const char *__s, int __c)
 265      __THROW __attribute_pure__ __nonnull ((1));
 266 # endif
 267 #endif
 268
 269 /* Return the length of the initial segment of S which
 270    consists entirely of characters not in REJECT.  */
 271 extern size_t strcspn (const char *__s, const char *__reject)
 272      __THROW __attribute_pure__ __nonnull ((1, 2));
 273 /* Return the length of the initial segment of S which
 274    consists entirely of characters in ACCEPT.  */
 275 extern size_t strspn (const char *__s, const char *__accept)
 276      __THROW __attribute_pure__ __nonnull ((1, 2));
 277 /* Find the first occurrence in S of any character in ACCEPT.  */
 278 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 279 extern "C++"
 280 {
 281 extern char *strpbrk (char *__s, const char *__accept)
 282      __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
 283 extern const char *strpbrk (const char *__s, const char *__accept)
 284      __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
 285
 286 # ifdef __OPTIMIZE__
 287 __extern_always_inline char *
 288 strpbrk (char *__s, const char *__accept) __THROW
 289 {
 290   return __builtin_strpbrk (__s, __accept);
 291 }
 292
 293 __extern_always_inline const char *
 294 strpbrk (const char *__s, const char *__accept) __THROW
 295 {
 296   return __builtin_strpbrk (__s, __accept);
 297 }
 298 # endif
 299 }
 300 #else
 301 extern char *strpbrk (const char *__s, const char *__accept)
 302      __THROW __attribute_pure__ __nonnull ((1, 2));
 303 #endif
 304 /* Find the first occurrence of NEEDLE in HAYSTACK.  */
 305 #ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 306 extern "C++"
 307 {
 308 extern char *strstr (char *__haystack, const char *__needle)
 309      __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
 310 extern const char *strstr (const char *__haystack, const char *__needle)
 311      __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
 312
 313 # ifdef __OPTIMIZE__
 314 __extern_always_inline char *
 315 strstr (char *__haystack, const char *__needle) __THROW
 316 {
 317   return __builtin_strstr (__haystack, __needle);
 318 }
 319
 320 __extern_always_inline const char *
 321 strstr (const char *__haystack, const char *__needle) __THROW
 322 {
 323   return __builtin_strstr (__haystack, __needle);
 324 }
 325 # endif
 326 }
 327 #else
 328 extern char *strstr (const char *__haystack, const char *__needle)
 329      __THROW __attribute_pure__ __nonnull ((1, 2));
 330 #endif
 331
 332
 333 /* Divide S into tokens separated by characters in DELIM.  */
 334 extern char *strtok (char *__restrict __s, const char *__restrict __delim)
 335      __THROW __nonnull ((2));
 336
 337 /* Divide S into tokens separated by characters in DELIM.  Information
 338    passed between calls are stored in SAVE_PTR.  */
 339 extern char *__strtok_r (char *__restrict __s,
 340                          const char *__restrict __delim,
 341                          char **__restrict __save_ptr)
 342      __THROW __nonnull ((2, 3));
 343 #ifdef __USE_POSIX
 344 extern char *strtok_r (char *__restrict __s, const char *__restrict __delim,
 345                        char **__restrict __save_ptr)
 346      __THROW __nonnull ((2, 3));
 347 #endif
 348
 349 #ifdef __USE_GNU
 350 /* Similar to `strstr' but this function ignores the case of both strings.  */
 351 # ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 352 extern "C++" char *strcasestr (char *__haystack, const char *__needle)
 353      __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
 354 extern "C++" const char *strcasestr (const char *__haystack,
 355                                      const char *__needle)
 356      __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
 357 # else
 358 extern char *strcasestr (const char *__haystack, const char *__needle)
 359      __THROW __attribute_pure__ __nonnull ((1, 2));
 360 # endif
 361 #endif
 362
 363 #ifdef __USE_GNU
 364 /* Find the first occurrence of NEEDLE in HAYSTACK.
 365    NEEDLE is NEEDLELEN bytes long;
 366    HAYSTACK is HAYSTACKLEN bytes long.  */
 367 extern void *memmem (const void *__haystack, size_t __haystacklen,
 368                      const void *__needle, size_t __needlelen)
 369      __THROW __attribute_pure__ __nonnull ((1, 3));
 370
 371 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
 372    last written byte.  */
 373 extern void *__mempcpy (void *__restrict __dest,
 374                         const void *__restrict __src, size_t __n)
 375      __THROW __nonnull ((1, 2));
 376 extern void *mempcpy (void *__restrict __dest,
 377                       const void *__restrict __src, size_t __n)
 378      __THROW __nonnull ((1, 2));
 379 #endif
 380
 381
 382 /* Return the length of S.  */
 383 extern size_t strlen (const char *__s)
 384      __THROW __attribute_pure__ __nonnull ((1));
 385
 386 #ifdef  __USE_XOPEN2K8
 387 /* Find the length of STRING, but scan at most MAXLEN characters.
 388    If no '\0' terminator is found in that many characters, return MAXLEN.  */
 389 extern size_t strnlen (const char *__string, size_t __maxlen)
 390      __THROW __attribute_pure__ __nonnull ((1));
 391 #endif
 392
 393
 394 /* Return a string describing the meaning of the `errno' code in ERRNUM.  */
 395 extern char *strerror (int __errnum) __THROW;
 396 #ifdef __USE_XOPEN2K
 397 /* Reentrant version of `strerror'.
 398    There are 2 flavors of `strerror_r', GNU which returns the string
 399    and may or may not use the supplied temporary buffer and POSIX one
 400    which fills the string into the buffer.
 401    To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
 402    without -D_GNU_SOURCE is needed, otherwise the GNU version is
 403    preferred.  */
 404 # if defined __USE_XOPEN2K && !defined __USE_GNU
 405 /* Fill BUF with a string describing the meaning of the `errno' code in
 406    ERRNUM.  */
 407 #  ifdef __REDIRECT_NTH
 408 extern int __REDIRECT_NTH (strerror_r,
 409                            (int __errnum, char *__buf, size_t __buflen),
 410                            __xpg_strerror_r) __nonnull ((2));
 411 #  else
 412 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
 413      __THROW __nonnull ((2));
 414 #   define strerror_r __xpg_strerror_r
 415 #  endif
 416 # else
 417 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
 418    used.  */
 419 extern char *strerror_r (int __errnum, char *__buf, size_t __buflen)
 420      __THROW __nonnull ((2)) __wur;
 421 # endif
 422 #endif
 423
 424 #ifdef __USE_XOPEN2K8
 425 /* Translate error number to string according to the locale L.  */
 426 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
 427 #endif
 428
 429 #ifdef __USE_MISC
 430 # include <strings.h>
 431
 432 /* Set N bytes of S to 0.  The compiler will not delete a call to this
 433    function, even if S is dead after the call.  */
 434 extern void explicit_bzero (void *__s, size_t __n) __THROW __nonnull ((1));
 435
 436 /* Return the next DELIM-delimited token from *STRINGP,
 437    terminating it with a '\0', and update *STRINGP to point past it.  */
 438 extern char *strsep (char **__restrict __stringp,
 439                      const char *__restrict __delim)
 440      __THROW __nonnull ((1, 2));
 441 #endif
 442
 443 #ifdef  __USE_XOPEN2K8
 444 /* Return a string describing the meaning of the signal number in SIG.  */
 445 extern char *strsignal (int __sig) __THROW;
 446
 447 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST.  */
 448 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
 449      __THROW __nonnull ((1, 2));
 450 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
 451      __THROW __nonnull ((1, 2));
 452
 453 /* Copy no more than N characters of SRC to DEST, returning the address of
 454    the last character written into DEST.  */
 455 extern char *__stpncpy (char *__restrict __dest,
 456                         const char *__restrict __src, size_t __n)
 457      __THROW __nonnull ((1, 2));
 458 extern char *stpncpy (char *__restrict __dest,
 459                       const char *__restrict __src, size_t __n)
 460      __THROW __nonnull ((1, 2));
 461 #endif
 462
 463 #ifdef  __USE_GNU
 464 /* Compare S1 and S2 as strings holding name & indices/version numbers.  */
 465 extern int strverscmp (const char *__s1, const char *__s2)
 466      __THROW __attribute_pure__ __nonnull ((1, 2));
 467
 468 /* Sautee STRING briskly.  */
 469 extern char *strfry (char *__string) __THROW __nonnull ((1));
 470
 471 /* Frobnicate N bytes of S.  */
 472 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
 473
 474 # ifndef basename
 475 /* Return the file name within directory of FILENAME.  We don't
 476    declare the function if the `basename' macro is available (defined
 477    in <libgen.h>) which makes the XPG version of this function
 478    available.  */
 479 #  ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 480 extern "C++" char *basename (char *__filename)
 481      __THROW __asm ("basename") __nonnull ((1));
 482 extern "C++" const char *basename (const char *__filename)
 483      __THROW __asm ("basename") __nonnull ((1));
 484 #  else
 485 extern char *basename (const char *__filename) __THROW __nonnull ((1));
 486 #  endif
 487 # endif
 488 #endif
 489
 490
 491 #if __GNUC_PREREQ (3,4)
 492 # if defined __OPTIMIZE__ && !defined __OPTIMIZE_SIZE__ \
 493      && !defined __NO_INLINE__ && !defined __cplusplus
 494 /* When using GNU CC we provide some optimized versions of selected
 495    functions from this header.  There are two kinds of optimizations:
 496
 497    - machine-dependent optimizations, most probably using inline
 498      assembler code; these might be quite expensive since the code
 499      size can increase significantly.
 500      These optimizations are not used unless the symbol
 501         __USE_STRING_INLINES
 502      is defined before including this header.
 503
 504    - machine-independent optimizations which do not increase the
 505      code size significantly and which optimize mainly situations
 506      where one or more arguments are compile-time constants.
 507      These optimizations are used always when the compiler is
 508      taught to optimize.
 509
 510    One can inhibit all optimizations by defining __NO_STRING_INLINES.  */
 511
 512 /* Get the machine-dependent optimizations (if any).  */
 513 #  include <bits/string.h>
 514
 515 /* These are generic optimizations which do not add too much inline code.  */
 516 #  include <bits/string2.h>
 517 # endif
 518
 519 # if __USE_FORTIFY_LEVEL > 0 && defined __fortify_function
 520 /* Functions with security checks.  */
 521 #  include <bits/string3.h>
 522 # endif
 523 #endif
 524
 525 #if defined __USE_GNU && defined __OPTIMIZE__ \
 526     && defined __extern_always_inline && __GNUC_PREREQ (3,2)
 527 # if !defined _FORCE_INLINES && !defined _HAVE_STRING_ARCH_mempcpy
 528
 529 #define mempcpy(dest, src, n) __mempcpy_inline (dest, src, n)
 530 #define __mempcpy(dest, src, n) __mempcpy_inline (dest, src, n)
 531
 532 __extern_always_inline void *
 533 __mempcpy_inline (void *__restrict __dest,
 534                   const void *__restrict __src, size_t __n)
 535 {
 536   return (char *) memcpy (__dest, __src, __n) + __n;
 537 }
 538
 539 # endif
 540 #endif
 541
 542 __END_DECLS
 543
 544 #endif /* string.h  */