lib/string.in.h

   1 /* A GNU-like <string.h>.
   2
   3    Copyright (C) 1995-1996, 2001-2010 Free Software Foundation, Inc.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2, or (at your option)
   8    any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software Foundation,
  17    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  18
  19 #ifndef _GL_STRING_H
  20
  21 #if __GNUC__ >= 3
  22 @PRAGMA_SYSTEM_HEADER@
  23 #endif
  24
  25 /* The include_next requires a split double-inclusion guard.  */
  26 #@INCLUDE_NEXT@ @NEXT_STRING_H@
  27
  28 #ifndef _GL_STRING_H
  29 #define _GL_STRING_H
  30
  31 /* NetBSD 5.0 mis-defines NULL.  */
  32 #include <stddef.h>
  33
  34 /* MirBSD defines mbslen as a macro.  */
  35 #if @GNULIB_MBSLEN@ && defined __MirBSD__
  36 # include <wchar.h>
  37 #endif
  38
  39 #ifndef __attribute__
  40 /* This feature is available in gcc versions 2.5 and later.  */
  41 # if __GNUC__ < 2 || (__GNUC__ == 2 && __GNUC_MINOR__ < 5)
  42 #  define __attribute__(Spec) /* empty */
  43 # endif
  44 #endif
  45 /* The attribute __pure__ was added in gcc 2.96.  */
  46 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
  47 # define _GL_ATTRIBUTE_PURE __attribute__ ((__pure__))
  48 #else
  49 # define _GL_ATTRIBUTE_PURE /* empty */
  50 #endif
  51
  52
  53 /* The definitions of _GL_FUNCDECL_RPL etc. are copied here.  */
  54
  55 /* The definition of _GL_ARG_NONNULL is copied here.  */
  56
  57 /* The definition of _GL_WARN_ON_USE is copied here.  */
  58
  59
  60 /* Return the first instance of C within N bytes of S, or NULL.  */
  61 #if @GNULIB_MEMCHR@
  62 # if @REPLACE_MEMCHR@
  63 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
  64 #   define memchr rpl_memchr
  65 #  endif
  66 _GL_FUNCDECL_RPL (memchr, void *, (void const *__s, int __c, size_t __n)
  67                                   _GL_ATTRIBUTE_PURE
  68                                   _GL_ARG_NONNULL ((1)));
  69 _GL_CXXALIAS_RPL (memchr, void *, (void const *__s, int __c, size_t __n));
  70 # else
  71 #  if ! @HAVE_MEMCHR@
  72 _GL_FUNCDECL_SYS (memchr, void *, (void const *__s, int __c, size_t __n)
  73                                   _GL_ATTRIBUTE_PURE
  74                                   _GL_ARG_NONNULL ((1)));
  75 #  endif
  76   /* On some systems, this function is defined as an overloaded function:
  77        extern "C" { const void * std::memchr (const void *, int, size_t); }
  78        extern "C++" { void * std::memchr (void *, int, size_t); }  */
  79 _GL_CXXALIAS_SYS_CAST2 (memchr,
  80                         void *, (void const *__s, int __c, size_t __n),
  81                         void const *, (void const *__s, int __c, size_t __n));
  82 # endif
  83 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
  84      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
  85 _GL_CXXALIASWARN1 (memchr, void *, (void *__s, int __c, size_t __n));
  86 _GL_CXXALIASWARN1 (memchr, void const *,
  87                    (void const *__s, int __c, size_t __n));
  88 # else
  89 _GL_CXXALIASWARN (memchr);
  90 # endif
  91 #elif defined GNULIB_POSIXCHECK
  92 # undef memchr
  93 /* Assume memchr is always declared.  */
  94 _GL_WARN_ON_USE (memchr, "memchr has platform-specific bugs - "
  95                  "use gnulib module memchr for portability" );
  96 #endif
  97
  98 /* Return the first occurrence of NEEDLE in HAYSTACK.  */
  99 #if @GNULIB_MEMMEM@
 100 # if @REPLACE_MEMMEM@
 101 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 102 #   define memmem rpl_memmem
 103 #  endif
 104 _GL_FUNCDECL_RPL (memmem, void *,
 105                   (void const *__haystack, size_t __haystack_len,
 106                    void const *__needle, size_t __needle_len)
 107                   _GL_ATTRIBUTE_PURE
 108                   _GL_ARG_NONNULL ((1, 3)));
 109 _GL_CXXALIAS_RPL (memmem, void *,
 110                   (void const *__haystack, size_t __haystack_len,
 111                    void const *__needle, size_t __needle_len));
 112 # else
 113 #  if ! @HAVE_DECL_MEMMEM@
 114 _GL_FUNCDECL_SYS (memmem, void *,
 115                   (void const *__haystack, size_t __haystack_len,
 116                    void const *__needle, size_t __needle_len)
 117                   _GL_ATTRIBUTE_PURE
 118                   _GL_ARG_NONNULL ((1, 3)));
 119 #  endif
 120 _GL_CXXALIAS_SYS (memmem, void *,
 121                   (void const *__haystack, size_t __haystack_len,
 122                    void const *__needle, size_t __needle_len));
 123 # endif
 124 _GL_CXXALIASWARN (memmem);
 125 #elif defined GNULIB_POSIXCHECK
 126 # undef memmem
 127 # if HAVE_RAW_DECL_MEMMEM
 128 _GL_WARN_ON_USE (memmem, "memmem is unportable and often quadratic - "
 129                  "use gnulib module memmem-simple for portability, "
 130                  "and module memmem for speed" );
 131 # endif
 132 #endif
 133
 134 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
 135    last written byte.  */
 136 #if @GNULIB_MEMPCPY@
 137 # if ! @HAVE_MEMPCPY@
 138 _GL_FUNCDECL_SYS (mempcpy, void *,
 139                   (void *restrict __dest, void const *restrict __src,
 140                    size_t __n)
 141                   _GL_ARG_NONNULL ((1, 2)));
 142 # endif
 143 _GL_CXXALIAS_SYS (mempcpy, void *,
 144                   (void *restrict __dest, void const *restrict __src,
 145                    size_t __n));
 146 _GL_CXXALIASWARN (mempcpy);
 147 #elif defined GNULIB_POSIXCHECK
 148 # undef mempcpy
 149 # if HAVE_RAW_DECL_MEMPCPY
 150 _GL_WARN_ON_USE (mempcpy, "mempcpy is unportable - "
 151                  "use gnulib module mempcpy for portability");
 152 # endif
 153 #endif
 154
 155 /* Search backwards through a block for a byte (specified as an int).  */
 156 #if @GNULIB_MEMRCHR@
 157 # if ! @HAVE_DECL_MEMRCHR@
 158 _GL_FUNCDECL_SYS (memrchr, void *, (void const *, int, size_t)
 159                                    _GL_ATTRIBUTE_PURE
 160                                    _GL_ARG_NONNULL ((1)));
 161 # endif
 162   /* On some systems, this function is defined as an overloaded function:
 163        extern "C++" { const void * std::memrchr (const void *, int, size_t); }
 164        extern "C++" { void * std::memrchr (void *, int, size_t); }  */
 165 _GL_CXXALIAS_SYS_CAST2 (memrchr,
 166                         void *, (void const *, int, size_t),
 167                         void const *, (void const *, int, size_t));
 168 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 169      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 170 _GL_CXXALIASWARN1 (memrchr, void *, (void *, int, size_t));
 171 _GL_CXXALIASWARN1 (memrchr, void const *, (void const *, int, size_t));
 172 # else
 173 _GL_CXXALIASWARN (memrchr);
 174 # endif
 175 #elif defined GNULIB_POSIXCHECK
 176 # undef memrchr
 177 # if HAVE_RAW_DECL_MEMRCHR
 178 _GL_WARN_ON_USE (memrchr, "memrchr is unportable - "
 179                  "use gnulib module memrchr for portability");
 180 # endif
 181 #endif
 182
 183 /* Find the first occurrence of C in S.  More efficient than
 184    memchr(S,C,N), at the expense of undefined behavior if C does not
 185    occur within N bytes.  */
 186 #if @GNULIB_RAWMEMCHR@
 187 # if ! @HAVE_RAWMEMCHR@
 188 _GL_FUNCDECL_SYS (rawmemchr, void *, (void const *__s, int __c_in)
 189                                      _GL_ATTRIBUTE_PURE
 190                                      _GL_ARG_NONNULL ((1)));
 191 # endif
 192   /* On some systems, this function is defined as an overloaded function:
 193        extern "C++" { const void * std::rawmemchr (const void *, int); }
 194        extern "C++" { void * std::rawmemchr (void *, int); }  */
 195 _GL_CXXALIAS_SYS_CAST2 (rawmemchr,
 196                         void *, (void const *__s, int __c_in),
 197                         void const *, (void const *__s, int __c_in));
 198 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 199      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 200 _GL_CXXALIASWARN1 (rawmemchr, void *, (void *__s, int __c_in));
 201 _GL_CXXALIASWARN1 (rawmemchr, void const *, (void const *__s, int __c_in));
 202 # else
 203 _GL_CXXALIASWARN (rawmemchr);
 204 # endif
 205 #elif defined GNULIB_POSIXCHECK
 206 # undef rawmemchr
 207 # if HAVE_RAW_DECL_RAWMEMCHR
 208 _GL_WARN_ON_USE (rawmemchr, "rawmemchr is unportable - "
 209                  "use gnulib module rawmemchr for portability");
 210 # endif
 211 #endif
 212
 213 /* Copy SRC to DST, returning the address of the terminating '\0' in DST.  */
 214 #if @GNULIB_STPCPY@
 215 # if ! @HAVE_STPCPY@
 216 _GL_FUNCDECL_SYS (stpcpy, char *,
 217                   (char *restrict __dst, char const *restrict __src)
 218                   _GL_ARG_NONNULL ((1, 2)));
 219 # endif
 220 _GL_CXXALIAS_SYS (stpcpy, char *,
 221                   (char *restrict __dst, char const *restrict __src));
 222 _GL_CXXALIASWARN (stpcpy);
 223 #elif defined GNULIB_POSIXCHECK
 224 # undef stpcpy
 225 # if HAVE_RAW_DECL_STPCPY
 226 _GL_WARN_ON_USE (stpcpy, "stpcpy is unportable - "
 227                  "use gnulib module stpcpy for portability");
 228 # endif
 229 #endif
 230
 231 /* Copy no more than N bytes of SRC to DST, returning a pointer past the
 232    last non-NUL byte written into DST.  */
 233 #if @GNULIB_STPNCPY@
 234 # if @REPLACE_STPNCPY@
 235 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 236 #   undef stpncpy
 237 #   define stpncpy rpl_stpncpy
 238 #  endif
 239 _GL_FUNCDECL_RPL (stpncpy, char *,
 240                   (char *restrict __dst, char const *restrict __src,
 241                    size_t __n)
 242                   _GL_ARG_NONNULL ((1, 2)));
 243 _GL_CXXALIAS_RPL (stpncpy, char *,
 244                   (char *restrict __dst, char const *restrict __src,
 245                    size_t __n));
 246 # else
 247 #  if ! @HAVE_STPNCPY@
 248 _GL_FUNCDECL_SYS (stpncpy, char *,
 249                   (char *restrict __dst, char const *restrict __src,
 250                    size_t __n)
 251                   _GL_ARG_NONNULL ((1, 2)));
 252 #  endif
 253 _GL_CXXALIAS_SYS (stpncpy, char *,
 254                   (char *restrict __dst, char const *restrict __src,
 255                    size_t __n));
 256 # endif
 257 _GL_CXXALIASWARN (stpncpy);
 258 #elif defined GNULIB_POSIXCHECK
 259 # undef stpncpy
 260 # if HAVE_RAW_DECL_STPNCPY
 261 _GL_WARN_ON_USE (stpncpy, "stpncpy is unportable - "
 262                  "use gnulib module stpncpy for portability");
 263 # endif
 264 #endif
 265
 266 #if defined GNULIB_POSIXCHECK
 267 /* strchr() does not work with multibyte strings if the locale encoding is
 268    GB18030 and the character to be searched is a digit.  */
 269 # undef strchr
 270 /* Assume strchr is always declared.  */
 271 _GL_WARN_ON_USE (strchr, "strchr cannot work correctly on character strings "
 272                  "in some multibyte locales - "
 273                  "use mbschr if you care about internationalization");
 274 #endif
 275
 276 /* Find the first occurrence of C in S or the final NUL byte.  */
 277 #if @GNULIB_STRCHRNUL@
 278 # if ! @HAVE_STRCHRNUL@
 279 _GL_FUNCDECL_SYS (strchrnul, char *, (char const *__s, int __c_in)
 280                                      _GL_ATTRIBUTE_PURE
 281                                      _GL_ARG_NONNULL ((1)));
 282 # endif
 283   /* On some systems, this function is defined as an overloaded function:
 284        extern "C++" { const char * std::strchrnul (const char *, int); }
 285        extern "C++" { char * std::strchrnul (char *, int); }  */
 286 _GL_CXXALIAS_SYS_CAST2 (strchrnul,
 287                         char *, (char const *__s, int __c_in),
 288                         char const *, (char const *__s, int __c_in));
 289 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 290      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 291 _GL_CXXALIASWARN1 (strchrnul, char *, (char *__s, int __c_in));
 292 _GL_CXXALIASWARN1 (strchrnul, char const *, (char const *__s, int __c_in));
 293 # else
 294 _GL_CXXALIASWARN (strchrnul);
 295 # endif
 296 #elif defined GNULIB_POSIXCHECK
 297 # undef strchrnul
 298 # if HAVE_RAW_DECL_STRCHRNUL
 299 _GL_WARN_ON_USE (strchrnul, "strchrnul is unportable - "
 300                  "use gnulib module strchrnul for portability");
 301 # endif
 302 #endif
 303
 304 /* Duplicate S, returning an identical malloc'd string.  */
 305 #if @GNULIB_STRDUP@
 306 # if @REPLACE_STRDUP@
 307 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 308 #   undef strdup
 309 #   define strdup rpl_strdup
 310 #  endif
 311 _GL_FUNCDECL_RPL (strdup, char *, (char const *__s) _GL_ARG_NONNULL ((1)));
 312 _GL_CXXALIAS_RPL (strdup, char *, (char const *__s));
 313 # else
 314 #  if !(@HAVE_DECL_STRDUP@ || defined strdup)
 315 _GL_FUNCDECL_SYS (strdup, char *, (char const *__s) _GL_ARG_NONNULL ((1)));
 316 #  endif
 317 _GL_CXXALIAS_SYS (strdup, char *, (char const *__s));
 318 # endif
 319 _GL_CXXALIASWARN (strdup);
 320 #elif defined GNULIB_POSIXCHECK
 321 # undef strdup
 322 # if HAVE_RAW_DECL_STRDUP
 323 _GL_WARN_ON_USE (strdup, "strdup is unportable - "
 324                  "use gnulib module strdup for portability");
 325 # endif
 326 #endif
 327
 328 /* Append no more than N characters from SRC onto DEST.  */
 329 #if @GNULIB_STRNCAT@
 330 # if @REPLACE_STRNCAT@
 331 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 332 #   undef strncat
 333 #   define strncat rpl_strncat
 334 #  endif
 335 _GL_FUNCDECL_RPL (strncat, char *, (char *dest, const char *src, size_t n)
 336                                    _GL_ARG_NONNULL ((1, 2)));
 337 _GL_CXXALIAS_RPL (strncat, char *, (char *dest, const char *src, size_t n));
 338 # else
 339 _GL_CXXALIAS_SYS (strncat, char *, (char *dest, const char *src, size_t n));
 340 # endif
 341 _GL_CXXALIASWARN (strncat);
 342 #elif defined GNULIB_POSIXCHECK
 343 # undef strncat
 344 # if HAVE_RAW_DECL_STRNCAT
 345 _GL_WARN_ON_USE (strncat, "strncat is unportable - "
 346                  "use gnulib module strncat for portability");
 347 # endif
 348 #endif
 349
 350 /* Return a newly allocated copy of at most N bytes of STRING.  */
 351 #if @GNULIB_STRNDUP@
 352 # if @REPLACE_STRNDUP@
 353 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 354 #   undef strndup
 355 #   define strndup rpl_strndup
 356 #  endif
 357 _GL_FUNCDECL_RPL (strndup, char *, (char const *__string, size_t __n)
 358                                    _GL_ARG_NONNULL ((1)));
 359 _GL_CXXALIAS_RPL (strndup, char *, (char const *__string, size_t __n));
 360 # else
 361 #  if ! @HAVE_DECL_STRNDUP@
 362 _GL_FUNCDECL_SYS (strndup, char *, (char const *__string, size_t __n)
 363                                    _GL_ARG_NONNULL ((1)));
 364 #  endif
 365 _GL_CXXALIAS_SYS (strndup, char *, (char const *__string, size_t __n));
 366 # endif
 367 _GL_CXXALIASWARN (strndup);
 368 #elif defined GNULIB_POSIXCHECK
 369 # undef strndup
 370 # if HAVE_RAW_DECL_STRNDUP
 371 _GL_WARN_ON_USE (strndup, "strndup is unportable - "
 372                  "use gnulib module strndup for portability");
 373 # endif
 374 #endif
 375
 376 /* Find the length (number of bytes) of STRING, but scan at most
 377    MAXLEN bytes.  If no '\0' terminator is found in that many bytes,
 378    return MAXLEN.  */
 379 #if @GNULIB_STRNLEN@
 380 # if @REPLACE_STRNLEN@
 381 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 382 #   undef strnlen
 383 #   define strnlen rpl_strnlen
 384 #  endif
 385 _GL_FUNCDECL_RPL (strnlen, size_t, (char const *__string, size_t __maxlen)
 386                                    _GL_ATTRIBUTE_PURE
 387                                    _GL_ARG_NONNULL ((1)));
 388 _GL_CXXALIAS_RPL (strnlen, size_t, (char const *__string, size_t __maxlen));
 389 # else
 390 #  if ! @HAVE_DECL_STRNLEN@
 391 _GL_FUNCDECL_SYS (strnlen, size_t, (char const *__string, size_t __maxlen)
 392                                    _GL_ATTRIBUTE_PURE
 393                                    _GL_ARG_NONNULL ((1)));
 394 #  endif
 395 _GL_CXXALIAS_SYS (strnlen, size_t, (char const *__string, size_t __maxlen));
 396 # endif
 397 _GL_CXXALIASWARN (strnlen);
 398 #elif defined GNULIB_POSIXCHECK
 399 # undef strnlen
 400 # if HAVE_RAW_DECL_STRNLEN
 401 _GL_WARN_ON_USE (strnlen, "strnlen is unportable - "
 402                  "use gnulib module strnlen for portability");
 403 # endif
 404 #endif
 405
 406 #if defined GNULIB_POSIXCHECK
 407 /* strcspn() assumes the second argument is a list of single-byte characters.
 408    Even in this simple case, it does not work with multibyte strings if the
 409    locale encoding is GB18030 and one of the characters to be searched is a
 410    digit.  */
 411 # undef strcspn
 412 /* Assume strcspn is always declared.  */
 413 _GL_WARN_ON_USE (strcspn, "strcspn cannot work correctly on character strings "
 414                  "in multibyte locales - "
 415                  "use mbscspn if you care about internationalization");
 416 #endif
 417
 418 /* Find the first occurrence in S of any character in ACCEPT.  */
 419 #if @GNULIB_STRPBRK@
 420 # if ! @HAVE_STRPBRK@
 421 _GL_FUNCDECL_SYS (strpbrk, char *, (char const *__s, char const *__accept)
 422                                    _GL_ATTRIBUTE_PURE
 423                                    _GL_ARG_NONNULL ((1, 2)));
 424 # endif
 425   /* On some systems, this function is defined as an overloaded function:
 426        extern "C" { const char * strpbrk (const char *, const char *); }
 427        extern "C++" { char * strpbrk (char *, const char *); }  */
 428 _GL_CXXALIAS_SYS_CAST2 (strpbrk,
 429                         char *, (char const *__s, char const *__accept),
 430                         const char *, (char const *__s, char const *__accept));
 431 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 432      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 433 _GL_CXXALIASWARN1 (strpbrk, char *, (char *__s, char const *__accept));
 434 _GL_CXXALIASWARN1 (strpbrk, char const *,
 435                    (char const *__s, char const *__accept));
 436 # else
 437 _GL_CXXALIASWARN (strpbrk);
 438 # endif
 439 # if defined GNULIB_POSIXCHECK
 440 /* strpbrk() assumes the second argument is a list of single-byte characters.
 441    Even in this simple case, it does not work with multibyte strings if the
 442    locale encoding is GB18030 and one of the characters to be searched is a
 443    digit.  */
 444 #  undef strpbrk
 445 _GL_WARN_ON_USE (strpbrk, "strpbrk cannot work correctly on character strings "
 446                  "in multibyte locales - "
 447                  "use mbspbrk if you care about internationalization");
 448 # endif
 449 #elif defined GNULIB_POSIXCHECK
 450 # undef strpbrk
 451 # if HAVE_RAW_DECL_STRPBRK
 452 _GL_WARN_ON_USE (strpbrk, "strpbrk is unportable - "
 453                  "use gnulib module strpbrk for portability");
 454 # endif
 455 #endif
 456
 457 #if defined GNULIB_POSIXCHECK
 458 /* strspn() assumes the second argument is a list of single-byte characters.
 459    Even in this simple case, it cannot work with multibyte strings.  */
 460 # undef strspn
 461 /* Assume strspn is always declared.  */
 462 _GL_WARN_ON_USE (strspn, "strspn cannot work correctly on character strings "
 463                  "in multibyte locales - "
 464                  "use mbsspn if you care about internationalization");
 465 #endif
 466
 467 #if defined GNULIB_POSIXCHECK
 468 /* strrchr() does not work with multibyte strings if the locale encoding is
 469    GB18030 and the character to be searched is a digit.  */
 470 # undef strrchr
 471 /* Assume strrchr is always declared.  */
 472 _GL_WARN_ON_USE (strrchr, "strrchr cannot work correctly on character strings "
 473                  "in some multibyte locales - "
 474                  "use mbsrchr if you care about internationalization");
 475 #endif
 476
 477 /* Search the next delimiter (char listed in DELIM) starting at *STRINGP.
 478    If one is found, overwrite it with a NUL, and advance *STRINGP
 479    to point to the next char after it.  Otherwise, set *STRINGP to NULL.
 480    If *STRINGP was already NULL, nothing happens.
 481    Return the old value of *STRINGP.
 482
 483    This is a variant of strtok() that is multithread-safe and supports
 484    empty fields.
 485
 486    Caveat: It modifies the original string.
 487    Caveat: These functions cannot be used on constant strings.
 488    Caveat: The identity of the delimiting character is lost.
 489    Caveat: It doesn't work with multibyte strings unless all of the delimiter
 490            characters are ASCII characters < 0x30.
 491
 492    See also strtok_r().  */
 493 #if @GNULIB_STRSEP@
 494 # if ! @HAVE_STRSEP@
 495 _GL_FUNCDECL_SYS (strsep, char *,
 496                   (char **restrict __stringp, char const *restrict __delim)
 497                   _GL_ARG_NONNULL ((1, 2)));
 498 # endif
 499 _GL_CXXALIAS_SYS (strsep, char *,
 500                   (char **restrict __stringp, char const *restrict __delim));
 501 _GL_CXXALIASWARN (strsep);
 502 # if defined GNULIB_POSIXCHECK
 503 #  undef strsep
 504 _GL_WARN_ON_USE (strsep, "strsep cannot work correctly on character strings "
 505                  "in multibyte locales - "
 506                  "use mbssep if you care about internationalization");
 507 # endif
 508 #elif defined GNULIB_POSIXCHECK
 509 # undef strsep
 510 # if HAVE_RAW_DECL_STRSEP
 511 _GL_WARN_ON_USE (strsep, "strsep is unportable - "
 512                  "use gnulib module strsep for portability");
 513 # endif
 514 #endif
 515
 516 #if @GNULIB_STRSTR@
 517 # if @REPLACE_STRSTR@
 518 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 519 #   define strstr rpl_strstr
 520 #  endif
 521 _GL_FUNCDECL_RPL (strstr, char *, (const char *haystack, const char *needle)
 522                                   _GL_ATTRIBUTE_PURE
 523                                   _GL_ARG_NONNULL ((1, 2)));
 524 _GL_CXXALIAS_RPL (strstr, char *, (const char *haystack, const char *needle));
 525 # else
 526   /* On some systems, this function is defined as an overloaded function:
 527        extern "C++" { const char * strstr (const char *, const char *); }
 528        extern "C++" { char * strstr (char *, const char *); }  */
 529 _GL_CXXALIAS_SYS_CAST2 (strstr,
 530                         char *, (const char *haystack, const char *needle),
 531                         const char *, (const char *haystack, const char *needle));
 532 # endif
 533 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 534      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 535 _GL_CXXALIASWARN1 (strstr, char *, (char *haystack, const char *needle));
 536 _GL_CXXALIASWARN1 (strstr, const char *,
 537                    (const char *haystack, const char *needle));
 538 # else
 539 _GL_CXXALIASWARN (strstr);
 540 # endif
 541 #elif defined GNULIB_POSIXCHECK
 542 /* strstr() does not work with multibyte strings if the locale encoding is
 543    different from UTF-8:
 544    POSIX says that it operates on "strings", and "string" in POSIX is defined
 545    as a sequence of bytes, not of characters.  */
 546 # undef strstr
 547 /* Assume strstr is always declared.  */
 548 _GL_WARN_ON_USE (strstr, "strstr is quadratic on many systems, and cannot "
 549                  "work correctly on character strings in most "
 550                  "multibyte locales - "
 551                  "use mbsstr if you care about internationalization, "
 552                  "or use strstr if you care about speed");
 553 #endif
 554
 555 /* Find the first occurrence of NEEDLE in HAYSTACK, using case-insensitive
 556    comparison.  */
 557 #if @GNULIB_STRCASESTR@
 558 # if @REPLACE_STRCASESTR@
 559 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 560 #   define strcasestr rpl_strcasestr
 561 #  endif
 562 _GL_FUNCDECL_RPL (strcasestr, char *,
 563                   (const char *haystack, const char *needle)
 564                   _GL_ATTRIBUTE_PURE
 565                   _GL_ARG_NONNULL ((1, 2)));
 566 _GL_CXXALIAS_RPL (strcasestr, char *,
 567                   (const char *haystack, const char *needle));
 568 # else
 569 #  if ! @HAVE_STRCASESTR@
 570 _GL_FUNCDECL_SYS (strcasestr, char *,
 571                   (const char *haystack, const char *needle)
 572                   _GL_ATTRIBUTE_PURE
 573                   _GL_ARG_NONNULL ((1, 2)));
 574 #  endif
 575   /* On some systems, this function is defined as an overloaded function:
 576        extern "C++" { const char * strcasestr (const char *, const char *); }
 577        extern "C++" { char * strcasestr (char *, const char *); }  */
 578 _GL_CXXALIAS_SYS_CAST2 (strcasestr,
 579                         char *, (const char *haystack, const char *needle),
 580                         const char *, (const char *haystack, const char *needle));
 581 # endif
 582 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 583      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 584 _GL_CXXALIASWARN1 (strcasestr, char *, (char *haystack, const char *needle));
 585 _GL_CXXALIASWARN1 (strcasestr, const char *,
 586                    (const char *haystack, const char *needle));
 587 # else
 588 _GL_CXXALIASWARN (strcasestr);
 589 # endif
 590 #elif defined GNULIB_POSIXCHECK
 591 /* strcasestr() does not work with multibyte strings:
 592    It is a glibc extension, and glibc implements it only for unibyte
 593    locales.  */
 594 # undef strcasestr
 595 # if HAVE_RAW_DECL_STRCASESTR
 596 _GL_WARN_ON_USE (strcasestr, "strcasestr does work correctly on character "
 597                  "strings in multibyte locales - "
 598                  "use mbscasestr if you care about "
 599                  "internationalization, or use c-strcasestr if you want "
 600                  "a locale independent function");
 601 # endif
 602 #endif
 603
 604 /* Parse S into tokens separated by characters in DELIM.
 605    If S is NULL, the saved pointer in SAVE_PTR is used as
 606    the next starting point.  For example:
 607         char s[] = "-abc-=-def";
 608         char *sp;
 609         x = strtok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
 610         x = strtok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
 611         x = strtok_r(NULL, "=", &sp);   // x = NULL
 612                 // s = "abc\0-def\0"
 613
 614    This is a variant of strtok() that is multithread-safe.
 615
 616    For the POSIX documentation for this function, see:
 617    http://www.opengroup.org/susv3xsh/strtok.html
 618
 619    Caveat: It modifies the original string.
 620    Caveat: These functions cannot be used on constant strings.
 621    Caveat: The identity of the delimiting character is lost.
 622    Caveat: It doesn't work with multibyte strings unless all of the delimiter
 623            characters are ASCII characters < 0x30.
 624
 625    See also strsep().  */
 626 #if @GNULIB_STRTOK_R@
 627 # if @REPLACE_STRTOK_R@
 628 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 629 #   undef strtok_r
 630 #   define strtok_r rpl_strtok_r
 631 #  endif
 632 _GL_FUNCDECL_RPL (strtok_r, char *,
 633                   (char *restrict s, char const *restrict delim,
 634                    char **restrict save_ptr)
 635                   _GL_ARG_NONNULL ((2, 3)));
 636 _GL_CXXALIAS_RPL (strtok_r, char *,
 637                   (char *restrict s, char const *restrict delim,
 638                    char **restrict save_ptr));
 639 # else
 640 #  if @UNDEFINE_STRTOK_R@ || defined GNULIB_POSIXCHECK
 641 #   undef strtok_r
 642 #  endif
 643 #  if ! @HAVE_DECL_STRTOK_R@
 644 _GL_FUNCDECL_SYS (strtok_r, char *,
 645                   (char *restrict s, char const *restrict delim,
 646                    char **restrict save_ptr)
 647                   _GL_ARG_NONNULL ((2, 3)));
 648 #  endif
 649 _GL_CXXALIAS_SYS (strtok_r, char *,
 650                   (char *restrict s, char const *restrict delim,
 651                    char **restrict save_ptr));
 652 # endif
 653 _GL_CXXALIASWARN (strtok_r);
 654 # if defined GNULIB_POSIXCHECK
 655 _GL_WARN_ON_USE (strtok_r, "strtok_r cannot work correctly on character "
 656                  "strings in multibyte locales - "
 657                  "use mbstok_r if you care about internationalization");
 658 # endif
 659 #elif defined GNULIB_POSIXCHECK
 660 # undef strtok_r
 661 # if HAVE_RAW_DECL_STRTOK_R
 662 _GL_WARN_ON_USE (strtok_r, "strtok_r is unportable - "
 663                  "use gnulib module strtok_r for portability");
 664 # endif
 665 #endif
 666
 667
 668 /* The following functions are not specified by POSIX.  They are gnulib
 669    extensions.  */
 670
 671 #if @GNULIB_MBSLEN@
 672 /* Return the number of multibyte characters in the character string STRING.
 673    This considers multibyte characters, unlike strlen, which counts bytes.  */
 674 # ifdef __MirBSD__  /* MirBSD defines mbslen as a macro.  Override it.  */
 675 #  undef mbslen
 676 # endif
 677 # if @HAVE_MBSLEN@  /* AIX, OSF/1, MirBSD define mbslen already in libc.  */
 678 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 679 #   define mbslen rpl_mbslen
 680 #  endif
 681 _GL_FUNCDECL_RPL (mbslen, size_t, (const char *string) _GL_ARG_NONNULL ((1)));
 682 _GL_CXXALIAS_RPL (mbslen, size_t, (const char *string));
 683 # else
 684 _GL_FUNCDECL_SYS (mbslen, size_t, (const char *string) _GL_ARG_NONNULL ((1)));
 685 _GL_CXXALIAS_SYS (mbslen, size_t, (const char *string));
 686 # endif
 687 _GL_CXXALIASWARN (mbslen);
 688 #endif
 689
 690 #if @GNULIB_MBSNLEN@
 691 /* Return the number of multibyte characters in the character string starting
 692    at STRING and ending at STRING + LEN.  */
 693 _GL_EXTERN_C size_t mbsnlen (const char *string, size_t len)
 694      _GL_ARG_NONNULL ((1));
 695 #endif
 696
 697 #if @GNULIB_MBSCHR@
 698 /* Locate the first single-byte character C in the character string STRING,
 699    and return a pointer to it.  Return NULL if C is not found in STRING.
 700    Unlike strchr(), this function works correctly in multibyte locales with
 701    encodings such as GB18030.  */
 702 # if defined __hpux
 703 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 704 #   define mbschr rpl_mbschr /* avoid collision with HP-UX function */
 705 #  endif
 706 _GL_FUNCDECL_RPL (mbschr, char *, (const char *string, int c)
 707                                   _GL_ARG_NONNULL ((1)));
 708 _GL_CXXALIAS_RPL (mbschr, char *, (const char *string, int c));
 709 # else
 710 _GL_FUNCDECL_SYS (mbschr, char *, (const char *string, int c)
 711                                   _GL_ARG_NONNULL ((1)));
 712 _GL_CXXALIAS_SYS (mbschr, char *, (const char *string, int c));
 713 # endif
 714 _GL_CXXALIASWARN (mbschr);
 715 #endif
 716
 717 #if @GNULIB_MBSRCHR@
 718 /* Locate the last single-byte character C in the character string STRING,
 719    and return a pointer to it.  Return NULL if C is not found in STRING.
 720    Unlike strrchr(), this function works correctly in multibyte locales with
 721    encodings such as GB18030.  */
 722 # if defined __hpux
 723 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 724 #   define mbsrchr rpl_mbsrchr /* avoid collision with HP-UX function */
 725 #  endif
 726 _GL_FUNCDECL_RPL (mbsrchr, char *, (const char *string, int c)
 727                                    _GL_ARG_NONNULL ((1)));
 728 _GL_CXXALIAS_RPL (mbsrchr, char *, (const char *string, int c));
 729 # else
 730 _GL_FUNCDECL_SYS (mbsrchr, char *, (const char *string, int c)
 731                                    _GL_ARG_NONNULL ((1)));
 732 _GL_CXXALIAS_SYS (mbsrchr, char *, (const char *string, int c));
 733 # endif
 734 _GL_CXXALIASWARN (mbsrchr);
 735 #endif
 736
 737 #if @GNULIB_MBSSTR@
 738 /* Find the first occurrence of the character string NEEDLE in the character
 739    string HAYSTACK.  Return NULL if NEEDLE is not found in HAYSTACK.
 740    Unlike strstr(), this function works correctly in multibyte locales with
 741    encodings different from UTF-8.  */
 742 _GL_EXTERN_C char * mbsstr (const char *haystack, const char *needle)
 743      _GL_ARG_NONNULL ((1, 2));
 744 #endif
 745
 746 #if @GNULIB_MBSCASECMP@
 747 /* Compare the character strings S1 and S2, ignoring case, returning less than,
 748    equal to or greater than zero if S1 is lexicographically less than, equal to
 749    or greater than S2.
 750    Note: This function may, in multibyte locales, return 0 for strings of
 751    different lengths!
 752    Unlike strcasecmp(), this function works correctly in multibyte locales.  */
 753 _GL_EXTERN_C int mbscasecmp (const char *s1, const char *s2)
 754      _GL_ARG_NONNULL ((1, 2));
 755 #endif
 756
 757 #if @GNULIB_MBSNCASECMP@
 758 /* Compare the initial segment of the character string S1 consisting of at most
 759    N characters with the initial segment of the character string S2 consisting
 760    of at most N characters, ignoring case, returning less than, equal to or
 761    greater than zero if the initial segment of S1 is lexicographically less
 762    than, equal to or greater than the initial segment of S2.
 763    Note: This function may, in multibyte locales, return 0 for initial segments
 764    of different lengths!
 765    Unlike strncasecmp(), this function works correctly in multibyte locales.
 766    But beware that N is not a byte count but a character count!  */
 767 _GL_EXTERN_C int mbsncasecmp (const char *s1, const char *s2, size_t n)
 768      _GL_ARG_NONNULL ((1, 2));
 769 #endif
 770
 771 #if @GNULIB_MBSPCASECMP@
 772 /* Compare the initial segment of the character string STRING consisting of
 773    at most mbslen (PREFIX) characters with the character string PREFIX,
 774    ignoring case.  If the two match, return a pointer to the first byte
 775    after this prefix in STRING.  Otherwise, return NULL.
 776    Note: This function may, in multibyte locales, return non-NULL if STRING
 777    is of smaller length than PREFIX!
 778    Unlike strncasecmp(), this function works correctly in multibyte
 779    locales.  */
 780 _GL_EXTERN_C char * mbspcasecmp (const char *string, const char *prefix)
 781      _GL_ARG_NONNULL ((1, 2));
 782 #endif
 783
 784 #if @GNULIB_MBSCASESTR@
 785 /* Find the first occurrence of the character string NEEDLE in the character
 786    string HAYSTACK, using case-insensitive comparison.
 787    Note: This function may, in multibyte locales, return success even if
 788    strlen (haystack) < strlen (needle) !
 789    Unlike strcasestr(), this function works correctly in multibyte locales.  */
 790 _GL_EXTERN_C char * mbscasestr (const char *haystack, const char *needle)
 791      _GL_ARG_NONNULL ((1, 2));
 792 #endif
 793
 794 #if @GNULIB_MBSCSPN@
 795 /* Find the first occurrence in the character string STRING of any character
 796    in the character string ACCEPT.  Return the number of bytes from the
 797    beginning of the string to this occurrence, or to the end of the string
 798    if none exists.
 799    Unlike strcspn(), this function works correctly in multibyte locales.  */
 800 _GL_EXTERN_C size_t mbscspn (const char *string, const char *accept)
 801      _GL_ARG_NONNULL ((1, 2));
 802 #endif
 803
 804 #if @GNULIB_MBSPBRK@
 805 /* Find the first occurrence in the character string STRING of any character
 806    in the character string ACCEPT.  Return the pointer to it, or NULL if none
 807    exists.
 808    Unlike strpbrk(), this function works correctly in multibyte locales.  */
 809 # if defined __hpux
 810 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 811 #   define mbspbrk rpl_mbspbrk /* avoid collision with HP-UX function */
 812 #  endif
 813 _GL_FUNCDECL_RPL (mbspbrk, char *, (const char *string, const char *accept)
 814                                    _GL_ARG_NONNULL ((1, 2)));
 815 _GL_CXXALIAS_RPL (mbspbrk, char *, (const char *string, const char *accept));
 816 # else
 817 _GL_FUNCDECL_SYS (mbspbrk, char *, (const char *string, const char *accept)
 818                                    _GL_ARG_NONNULL ((1, 2)));
 819 _GL_CXXALIAS_SYS (mbspbrk, char *, (const char *string, const char *accept));
 820 # endif
 821 _GL_CXXALIASWARN (mbspbrk);
 822 #endif
 823
 824 #if @GNULIB_MBSSPN@
 825 /* Find the first occurrence in the character string STRING of any character
 826    not in the character string REJECT.  Return the number of bytes from the
 827    beginning of the string to this occurrence, or to the end of the string
 828    if none exists.
 829    Unlike strspn(), this function works correctly in multibyte locales.  */
 830 _GL_EXTERN_C size_t mbsspn (const char *string, const char *reject)
 831      _GL_ARG_NONNULL ((1, 2));
 832 #endif
 833
 834 #if @GNULIB_MBSSEP@
 835 /* Search the next delimiter (multibyte character listed in the character
 836    string DELIM) starting at the character string *STRINGP.
 837    If one is found, overwrite it with a NUL, and advance *STRINGP to point
 838    to the next multibyte character after it.  Otherwise, set *STRINGP to NULL.
 839    If *STRINGP was already NULL, nothing happens.
 840    Return the old value of *STRINGP.
 841
 842    This is a variant of mbstok_r() that supports empty fields.
 843
 844    Caveat: It modifies the original string.
 845    Caveat: These functions cannot be used on constant strings.
 846    Caveat: The identity of the delimiting character is lost.
 847
 848    See also mbstok_r().  */
 849 _GL_EXTERN_C char * mbssep (char **stringp, const char *delim)
 850      _GL_ARG_NONNULL ((1, 2));
 851 #endif
 852
 853 #if @GNULIB_MBSTOK_R@
 854 /* Parse the character string STRING into tokens separated by characters in
 855    the character string DELIM.
 856    If STRING is NULL, the saved pointer in SAVE_PTR is used as
 857    the next starting point.  For example:
 858         char s[] = "-abc-=-def";
 859         char *sp;
 860         x = mbstok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
 861         x = mbstok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
 862         x = mbstok_r(NULL, "=", &sp);   // x = NULL
 863                 // s = "abc\0-def\0"
 864
 865    Caveat: It modifies the original string.
 866    Caveat: These functions cannot be used on constant strings.
 867    Caveat: The identity of the delimiting character is lost.
 868
 869    See also mbssep().  */
 870 _GL_EXTERN_C char * mbstok_r (char *string, const char *delim, char **save_ptr)
 871      _GL_ARG_NONNULL ((2, 3));
 872 #endif
 873
 874 /* Map any int, typically from errno, into an error message.  */
 875 #if @GNULIB_STRERROR@
 876 # if @REPLACE_STRERROR@
 877 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 878 #   undef strerror
 879 #   define strerror rpl_strerror
 880 #  endif
 881 _GL_FUNCDECL_RPL (strerror, char *, (int));
 882 _GL_CXXALIAS_RPL (strerror, char *, (int));
 883 # else
 884 _GL_CXXALIAS_SYS (strerror, char *, (int));
 885 # endif
 886 _GL_CXXALIASWARN (strerror);
 887 #elif defined GNULIB_POSIXCHECK
 888 # undef strerror
 889 /* Assume strerror is always declared.  */
 890 _GL_WARN_ON_USE (strerror, "strerror is unportable - "
 891                  "use gnulib module strerror to guarantee non-NULL result");
 892 #endif
 893
 894 #if @GNULIB_STRSIGNAL@
 895 # if @REPLACE_STRSIGNAL@
 896 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 897 #   define strsignal rpl_strsignal
 898 #  endif
 899 _GL_FUNCDECL_RPL (strsignal, char *, (int __sig));
 900 _GL_CXXALIAS_RPL (strsignal, char *, (int __sig));
 901 # else
 902 #  if ! @HAVE_DECL_STRSIGNAL@
 903 _GL_FUNCDECL_SYS (strsignal, char *, (int __sig));
 904 #  endif
 905 /* Need to cast, because on Cygwin 1.5.x systems, the return type is
 906    'const char *'.  */
 907 _GL_CXXALIAS_SYS_CAST (strsignal, char *, (int __sig));
 908 # endif
 909 _GL_CXXALIASWARN (strsignal);
 910 #elif defined GNULIB_POSIXCHECK
 911 # undef strsignal
 912 # if HAVE_RAW_DECL_STRSIGNAL
 913 _GL_WARN_ON_USE (strsignal, "strsignal is unportable - "
 914                  "use gnulib module strsignal for portability");
 915 # endif
 916 #endif
 917
 918 #if @GNULIB_STRVERSCMP@
 919 # if !@HAVE_STRVERSCMP@
 920 _GL_FUNCDECL_SYS (strverscmp, int, (const char *, const char *)
 921                                    _GL_ARG_NONNULL ((1, 2)));
 922 # endif
 923 _GL_CXXALIAS_SYS (strverscmp, int, (const char *, const char *));
 924 _GL_CXXALIASWARN (strverscmp);
 925 #elif defined GNULIB_POSIXCHECK
 926 # undef strverscmp
 927 # if HAVE_RAW_DECL_STRVERSCMP
 928 _GL_WARN_ON_USE (strverscmp, "strverscmp is unportable - "
 929                  "use gnulib module strverscmp for portability");
 930 # endif
 931 #endif
 932
 933
 934 #endif /* _GL_STRING_H */
 935 #endif /* _GL_STRING_H */