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