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