string/string.h

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