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 #endif
 432
 433 #ifdef __USE_XOPEN2K8
 434 /* Translate error number to string according to the locale L.  */
 435 extern char *strerror_l (int __errnum, locale_t __l) __THROW;
 436 #endif
 437
 438 #ifdef __USE_MISC
 439 # include <strings.h>
 440
 441 /* Set N bytes of S to 0.  The compiler will not delete a call to this
 442    function, even if S is dead after the call.  */
 443 extern void explicit_bzero (void *__s, size_t __n) __THROW __nonnull ((1))
 444     __attr_access ((__write_only__, 1, 2));
 445
 446 /* Return the next DELIM-delimited token from *STRINGP,
 447    terminating it with a '\0', and update *STRINGP to point past it.  */
 448 extern char *strsep (char **__restrict __stringp,
 449                      const char *__restrict __delim)
 450      __THROW __nonnull ((1, 2));
 451 #endif
 452
 453 #ifdef  __USE_XOPEN2K8
 454 /* Return a string describing the meaning of the signal number in SIG.  */
 455 extern char *strsignal (int __sig) __THROW;
 456
 457 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST.  */
 458 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
 459      __THROW __nonnull ((1, 2));
 460 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
 461      __THROW __nonnull ((1, 2));
 462
 463 /* Copy no more than N characters of SRC to DEST, returning the address of
 464    the last character written into DEST.  */
 465 extern char *__stpncpy (char *__restrict __dest,
 466                         const char *__restrict __src, size_t __n)
 467      __THROW __nonnull ((1, 2));
 468 extern char *stpncpy (char *__restrict __dest,
 469                       const char *__restrict __src, size_t __n)
 470      __THROW __nonnull ((1, 2));
 471 #endif
 472
 473 #ifdef  __USE_GNU
 474 /* Compare S1 and S2 as strings holding name & indices/version numbers.  */
 475 extern int strverscmp (const char *__s1, const char *__s2)
 476      __THROW __attribute_pure__ __nonnull ((1, 2));
 477
 478 /* Sautee STRING briskly.  */
 479 extern char *strfry (char *__string) __THROW __nonnull ((1));
 480
 481 /* Frobnicate N bytes of S.  */
 482 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1))
 483     __attr_access ((__write_only__, 1, 2));
 484
 485 # ifndef basename
 486 /* Return the file name within directory of FILENAME.  We don't
 487    declare the function if the `basename' macro is available (defined
 488    in <libgen.h>) which makes the XPG version of this function
 489    available.  */
 490 #  ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
 491 extern "C++" char *basename (char *__filename)
 492      __THROW __asm ("basename") __nonnull ((1));
 493 extern "C++" const char *basename (const char *__filename)
 494      __THROW __asm ("basename") __nonnull ((1));
 495 #  else
 496 extern char *basename (const char *__filename) __THROW __nonnull ((1));
 497 #  endif
 498 # endif
 499 #endif
 500
 501 #if __GNUC_PREREQ (3,4)
 502 # if __USE_FORTIFY_LEVEL > 0 && defined __fortify_function
 503 /* Functions with security checks.  */
 504 #  include <bits/string_fortified.h>
 505 # endif
 506 #endif
 507
 508 __END_DECLS
 509
 510 #endif /* string.h  */