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 #   define stpncpy rpl_stpncpy
 237 #  endif
 238 _GL_FUNCDECL_RPL (stpncpy, char *,
 239                   (char *restrict __dst, char const *restrict __src,
 240                    size_t __n)
 241                   _GL_ARG_NONNULL ((1, 2)));
 242 _GL_CXXALIAS_RPL (stpncpy, char *,
 243                   (char *restrict __dst, char const *restrict __src,
 244                    size_t __n));
 245 # else
 246 #  if ! @HAVE_STPNCPY@
 247 _GL_FUNCDECL_SYS (stpncpy, char *,
 248                   (char *restrict __dst, char const *restrict __src,
 249                    size_t __n)
 250                   _GL_ARG_NONNULL ((1, 2)));
 251 #  endif
 252 _GL_CXXALIAS_SYS (stpncpy, char *,
 253                   (char *restrict __dst, char const *restrict __src,
 254                    size_t __n));
 255 # endif
 256 _GL_CXXALIASWARN (stpncpy);
 257 #elif defined GNULIB_POSIXCHECK
 258 # undef stpncpy
 259 # if HAVE_RAW_DECL_STPNCPY
 260 _GL_WARN_ON_USE (stpncpy, "stpncpy is unportable - "
 261                  "use gnulib module stpncpy for portability");
 262 # endif
 263 #endif
 264
 265 #if defined GNULIB_POSIXCHECK
 266 /* strchr() does not work with multibyte strings if the locale encoding is
 267    GB18030 and the character to be searched is a digit.  */
 268 # undef strchr
 269 /* Assume strchr is always declared.  */
 270 _GL_WARN_ON_USE (strchr, "strchr cannot work correctly on character strings "
 271                  "in some multibyte locales - "
 272                  "use mbschr if you care about internationalization");
 273 #endif
 274
 275 /* Find the first occurrence of C in S or the final NUL byte.  */
 276 #if @GNULIB_STRCHRNUL@
 277 # if ! @HAVE_STRCHRNUL@
 278 _GL_FUNCDECL_SYS (strchrnul, char *, (char const *__s, int __c_in)
 279                                      _GL_ATTRIBUTE_PURE
 280                                      _GL_ARG_NONNULL ((1)));
 281 # endif
 282   /* On some systems, this function is defined as an overloaded function:
 283        extern "C++" { const char * std::strchrnul (const char *, int); }
 284        extern "C++" { char * std::strchrnul (char *, int); }  */
 285 _GL_CXXALIAS_SYS_CAST2 (strchrnul,
 286                         char *, (char const *__s, int __c_in),
 287                         char const *, (char const *__s, int __c_in));
 288 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 289      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 290 _GL_CXXALIASWARN1 (strchrnul, char *, (char *__s, int __c_in));
 291 _GL_CXXALIASWARN1 (strchrnul, char const *, (char const *__s, int __c_in));
 292 # else
 293 _GL_CXXALIASWARN (strchrnul);
 294 # endif
 295 #elif defined GNULIB_POSIXCHECK
 296 # undef strchrnul
 297 # if HAVE_RAW_DECL_STRCHRNUL
 298 _GL_WARN_ON_USE (strchrnul, "strchrnul is unportable - "
 299                  "use gnulib module strchrnul for portability");
 300 # endif
 301 #endif
 302
 303 /* Duplicate S, returning an identical malloc'd string.  */
 304 #if @GNULIB_STRDUP@
 305 # if @REPLACE_STRDUP@
 306 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 307 #   undef strdup
 308 #   define strdup rpl_strdup
 309 #  endif
 310 _GL_FUNCDECL_RPL (strdup, char *, (char const *__s) _GL_ARG_NONNULL ((1)));
 311 _GL_CXXALIAS_RPL (strdup, char *, (char const *__s));
 312 # else
 313 #  if !(@HAVE_DECL_STRDUP@ || defined strdup)
 314 _GL_FUNCDECL_SYS (strdup, char *, (char const *__s) _GL_ARG_NONNULL ((1)));
 315 #  endif
 316 _GL_CXXALIAS_SYS (strdup, char *, (char const *__s));
 317 # endif
 318 _GL_CXXALIASWARN (strdup);
 319 #elif defined GNULIB_POSIXCHECK
 320 # undef strdup
 321 # if HAVE_RAW_DECL_STRDUP
 322 _GL_WARN_ON_USE (strdup, "strdup is unportable - "
 323                  "use gnulib module strdup for portability");
 324 # endif
 325 #endif
 326
 327 /* Append no more than N characters from SRC onto DEST.  */
 328 #if @GNULIB_STRNCAT@
 329 # if @REPLACE_STRNCAT@
 330 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 331 #   undef strncat
 332 #   define strncat rpl_strncat
 333 #  endif
 334 _GL_FUNCDECL_RPL (strncat, char *, (char *dest, const char *src, size_t n)
 335                                    _GL_ARG_NONNULL ((1, 2)));
 336 _GL_CXXALIAS_RPL (strncat, char *, (char *dest, const char *src, size_t n));
 337 # else
 338 _GL_CXXALIAS_SYS (strncat, char *, (char *dest, const char *src, size_t n));
 339 # endif
 340 _GL_CXXALIASWARN (strncat);
 341 #elif defined GNULIB_POSIXCHECK
 342 # undef strncat
 343 # if HAVE_RAW_DECL_STRNCAT
 344 _GL_WARN_ON_USE (strncat, "strncat is unportable - "
 345                  "use gnulib module strncat for portability");
 346 # endif
 347 #endif
 348
 349 /* Return a newly allocated copy of at most N bytes of STRING.  */
 350 #if @GNULIB_STRNDUP@
 351 # if @REPLACE_STRNDUP@
 352 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 353 #   undef strndup
 354 #   define strndup rpl_strndup
 355 #  endif
 356 _GL_FUNCDECL_RPL (strndup, char *, (char const *__string, size_t __n)
 357                                    _GL_ARG_NONNULL ((1)));
 358 _GL_CXXALIAS_RPL (strndup, char *, (char const *__string, size_t __n));
 359 # else
 360 #  if ! @HAVE_DECL_STRNDUP@
 361 _GL_FUNCDECL_SYS (strndup, char *, (char const *__string, size_t __n)
 362                                    _GL_ARG_NONNULL ((1)));
 363 #  endif
 364 _GL_CXXALIAS_SYS (strndup, char *, (char const *__string, size_t __n));
 365 # endif
 366 _GL_CXXALIASWARN (strndup);
 367 #elif defined GNULIB_POSIXCHECK
 368 # undef strndup
 369 # if HAVE_RAW_DECL_STRNDUP
 370 _GL_WARN_ON_USE (strndup, "strndup is unportable - "
 371                  "use gnulib module strndup for portability");
 372 # endif
 373 #endif
 374
 375 /* Find the length (number of bytes) of STRING, but scan at most
 376    MAXLEN bytes.  If no '\0' terminator is found in that many bytes,
 377    return MAXLEN.  */
 378 #if @GNULIB_STRNLEN@
 379 # if @REPLACE_STRNLEN@
 380 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 381 #   undef strnlen
 382 #   define strnlen rpl_strnlen
 383 #  endif
 384 _GL_FUNCDECL_RPL (strnlen, size_t, (char const *__string, size_t __maxlen)
 385                                    _GL_ATTRIBUTE_PURE
 386                                    _GL_ARG_NONNULL ((1)));
 387 _GL_CXXALIAS_RPL (strnlen, size_t, (char const *__string, size_t __maxlen));
 388 # else
 389 #  if ! @HAVE_DECL_STRNLEN@
 390 _GL_FUNCDECL_SYS (strnlen, size_t, (char const *__string, size_t __maxlen)
 391                                    _GL_ATTRIBUTE_PURE
 392                                    _GL_ARG_NONNULL ((1)));
 393 #  endif
 394 _GL_CXXALIAS_SYS (strnlen, size_t, (char const *__string, size_t __maxlen));
 395 # endif
 396 _GL_CXXALIASWARN (strnlen);
 397 #elif defined GNULIB_POSIXCHECK
 398 # undef strnlen
 399 # if HAVE_RAW_DECL_STRNLEN
 400 _GL_WARN_ON_USE (strnlen, "strnlen is unportable - "
 401                  "use gnulib module strnlen for portability");
 402 # endif
 403 #endif
 404
 405 #if defined GNULIB_POSIXCHECK
 406 /* strcspn() assumes the second argument is a list of single-byte characters.
 407    Even in this simple case, it does not work with multibyte strings if the
 408    locale encoding is GB18030 and one of the characters to be searched is a
 409    digit.  */
 410 # undef strcspn
 411 /* Assume strcspn is always declared.  */
 412 _GL_WARN_ON_USE (strcspn, "strcspn cannot work correctly on character strings "
 413                  "in multibyte locales - "
 414                  "use mbscspn if you care about internationalization");
 415 #endif
 416
 417 /* Find the first occurrence in S of any character in ACCEPT.  */
 418 #if @GNULIB_STRPBRK@
 419 # if ! @HAVE_STRPBRK@
 420 _GL_FUNCDECL_SYS (strpbrk, char *, (char const *__s, char const *__accept)
 421                                    _GL_ATTRIBUTE_PURE
 422                                    _GL_ARG_NONNULL ((1, 2)));
 423 # endif
 424   /* On some systems, this function is defined as an overloaded function:
 425        extern "C" { const char * strpbrk (const char *, const char *); }
 426        extern "C++" { char * strpbrk (char *, const char *); }  */
 427 _GL_CXXALIAS_SYS_CAST2 (strpbrk,
 428                         char *, (char const *__s, char const *__accept),
 429                         const char *, (char const *__s, char const *__accept));
 430 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 431      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 432 _GL_CXXALIASWARN1 (strpbrk, char *, (char *__s, char const *__accept));
 433 _GL_CXXALIASWARN1 (strpbrk, char const *,
 434                    (char const *__s, char const *__accept));
 435 # else
 436 _GL_CXXALIASWARN (strpbrk);
 437 # endif
 438 # if defined GNULIB_POSIXCHECK
 439 /* strpbrk() assumes the second argument is a list of single-byte characters.
 440    Even in this simple case, it does not work with multibyte strings if the
 441    locale encoding is GB18030 and one of the characters to be searched is a
 442    digit.  */
 443 #  undef strpbrk
 444 _GL_WARN_ON_USE (strpbrk, "strpbrk cannot work correctly on character strings "
 445                  "in multibyte locales - "
 446                  "use mbspbrk if you care about internationalization");
 447 # endif
 448 #elif defined GNULIB_POSIXCHECK
 449 # undef strpbrk
 450 # if HAVE_RAW_DECL_STRPBRK
 451 _GL_WARN_ON_USE (strpbrk, "strpbrk is unportable - "
 452                  "use gnulib module strpbrk for portability");
 453 # endif
 454 #endif
 455
 456 #if defined GNULIB_POSIXCHECK
 457 /* strspn() assumes the second argument is a list of single-byte characters.
 458    Even in this simple case, it cannot work with multibyte strings.  */
 459 # undef strspn
 460 /* Assume strspn is always declared.  */
 461 _GL_WARN_ON_USE (strspn, "strspn cannot work correctly on character strings "
 462                  "in multibyte locales - "
 463                  "use mbsspn if you care about internationalization");
 464 #endif
 465
 466 #if defined GNULIB_POSIXCHECK
 467 /* strrchr() does not work with multibyte strings if the locale encoding is
 468    GB18030 and the character to be searched is a digit.  */
 469 # undef strrchr
 470 /* Assume strrchr is always declared.  */
 471 _GL_WARN_ON_USE (strrchr, "strrchr cannot work correctly on character strings "
 472                  "in some multibyte locales - "
 473                  "use mbsrchr if you care about internationalization");
 474 #endif
 475
 476 /* Search the next delimiter (char listed in DELIM) starting at *STRINGP.
 477    If one is found, overwrite it with a NUL, and advance *STRINGP
 478    to point to the next char after it.  Otherwise, set *STRINGP to NULL.
 479    If *STRINGP was already NULL, nothing happens.
 480    Return the old value of *STRINGP.
 481
 482    This is a variant of strtok() that is multithread-safe and supports
 483    empty fields.
 484
 485    Caveat: It modifies the original string.
 486    Caveat: These functions cannot be used on constant strings.
 487    Caveat: The identity of the delimiting character is lost.
 488    Caveat: It doesn't work with multibyte strings unless all of the delimiter
 489            characters are ASCII characters < 0x30.
 490
 491    See also strtok_r().  */
 492 #if @GNULIB_STRSEP@
 493 # if ! @HAVE_STRSEP@
 494 _GL_FUNCDECL_SYS (strsep, char *,
 495                   (char **restrict __stringp, char const *restrict __delim)
 496                   _GL_ARG_NONNULL ((1, 2)));
 497 # endif
 498 _GL_CXXALIAS_SYS (strsep, char *,
 499                   (char **restrict __stringp, char const *restrict __delim));
 500 _GL_CXXALIASWARN (strsep);
 501 # if defined GNULIB_POSIXCHECK
 502 #  undef strsep
 503 _GL_WARN_ON_USE (strsep, "strsep cannot work correctly on character strings "
 504                  "in multibyte locales - "
 505                  "use mbssep if you care about internationalization");
 506 # endif
 507 #elif defined GNULIB_POSIXCHECK
 508 # undef strsep
 509 # if HAVE_RAW_DECL_STRSEP
 510 _GL_WARN_ON_USE (strsep, "strsep is unportable - "
 511                  "use gnulib module strsep for portability");
 512 # endif
 513 #endif
 514
 515 #if @GNULIB_STRSTR@
 516 # if @REPLACE_STRSTR@
 517 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 518 #   define strstr rpl_strstr
 519 #  endif
 520 _GL_FUNCDECL_RPL (strstr, char *, (const char *haystack, const char *needle)
 521                                   _GL_ATTRIBUTE_PURE
 522                                   _GL_ARG_NONNULL ((1, 2)));
 523 _GL_CXXALIAS_RPL (strstr, char *, (const char *haystack, const char *needle));
 524 # else
 525   /* On some systems, this function is defined as an overloaded function:
 526        extern "C++" { const char * strstr (const char *, const char *); }
 527        extern "C++" { char * strstr (char *, const char *); }  */
 528 _GL_CXXALIAS_SYS_CAST2 (strstr,
 529                         char *, (const char *haystack, const char *needle),
 530                         const char *, (const char *haystack, const char *needle));
 531 # endif
 532 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 533      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 534 _GL_CXXALIASWARN1 (strstr, char *, (char *haystack, const char *needle));
 535 _GL_CXXALIASWARN1 (strstr, const char *,
 536                    (const char *haystack, const char *needle));
 537 # else
 538 _GL_CXXALIASWARN (strstr);
 539 # endif
 540 #elif defined GNULIB_POSIXCHECK
 541 /* strstr() does not work with multibyte strings if the locale encoding is
 542    different from UTF-8:
 543    POSIX says that it operates on "strings", and "string" in POSIX is defined
 544    as a sequence of bytes, not of characters.  */
 545 # undef strstr
 546 /* Assume strstr is always declared.  */
 547 _GL_WARN_ON_USE (strstr, "strstr is quadratic on many systems, and cannot "
 548                  "work correctly on character strings in most "
 549                  "multibyte locales - "
 550                  "use mbsstr if you care about internationalization, "
 551                  "or use strstr if you care about speed");
 552 #endif
 553
 554 /* Find the first occurrence of NEEDLE in HAYSTACK, using case-insensitive
 555    comparison.  */
 556 #if @GNULIB_STRCASESTR@
 557 # if @REPLACE_STRCASESTR@
 558 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 559 #   define strcasestr rpl_strcasestr
 560 #  endif
 561 _GL_FUNCDECL_RPL (strcasestr, char *,
 562                   (const char *haystack, const char *needle)
 563                   _GL_ATTRIBUTE_PURE
 564                   _GL_ARG_NONNULL ((1, 2)));
 565 _GL_CXXALIAS_RPL (strcasestr, char *,
 566                   (const char *haystack, const char *needle));
 567 # else
 568 #  if ! @HAVE_STRCASESTR@
 569 _GL_FUNCDECL_SYS (strcasestr, char *,
 570                   (const char *haystack, const char *needle)
 571                   _GL_ATTRIBUTE_PURE
 572                   _GL_ARG_NONNULL ((1, 2)));
 573 #  endif
 574   /* On some systems, this function is defined as an overloaded function:
 575        extern "C++" { const char * strcasestr (const char *, const char *); }
 576        extern "C++" { char * strcasestr (char *, const char *); }  */
 577 _GL_CXXALIAS_SYS_CAST2 (strcasestr,
 578                         char *, (const char *haystack, const char *needle),
 579                         const char *, (const char *haystack, const char *needle));
 580 # endif
 581 # if __GLIBC__ == 2 && __GLIBC_MINOR__ >= 10 \
 582      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
 583 _GL_CXXALIASWARN1 (strcasestr, char *, (char *haystack, const char *needle));
 584 _GL_CXXALIASWARN1 (strcasestr, const char *,
 585                    (const char *haystack, const char *needle));
 586 # else
 587 _GL_CXXALIASWARN (strcasestr);
 588 # endif
 589 #elif defined GNULIB_POSIXCHECK
 590 /* strcasestr() does not work with multibyte strings:
 591    It is a glibc extension, and glibc implements it only for unibyte
 592    locales.  */
 593 # undef strcasestr
 594 # if HAVE_RAW_DECL_STRCASESTR
 595 _GL_WARN_ON_USE (strcasestr, "strcasestr does work correctly on character "
 596                  "strings in multibyte locales - "
 597                  "use mbscasestr if you care about "
 598                  "internationalization, or use c-strcasestr if you want "
 599                  "a locale independent function");
 600 # endif
 601 #endif
 602
 603 /* Parse S into tokens separated by characters in DELIM.
 604    If S is NULL, the saved pointer in SAVE_PTR is used as
 605    the next starting point.  For example:
 606         char s[] = "-abc-=-def";
 607         char *sp;
 608         x = strtok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
 609         x = strtok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
 610         x = strtok_r(NULL, "=", &sp);   // x = NULL
 611                 // s = "abc\0-def\0"
 612
 613    This is a variant of strtok() that is multithread-safe.
 614
 615    For the POSIX documentation for this function, see:
 616    http://www.opengroup.org/susv3xsh/strtok.html
 617
 618    Caveat: It modifies the original string.
 619    Caveat: These functions cannot be used on constant strings.
 620    Caveat: The identity of the delimiting character is lost.
 621    Caveat: It doesn't work with multibyte strings unless all of the delimiter
 622            characters are ASCII characters < 0x30.
 623
 624    See also strsep().  */
 625 #if @GNULIB_STRTOK_R@
 626 # if @REPLACE_STRTOK_R@
 627 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 628 #   undef strtok_r
 629 #   define strtok_r rpl_strtok_r
 630 #  endif
 631 _GL_FUNCDECL_RPL (strtok_r, char *,
 632                   (char *restrict s, char const *restrict delim,
 633                    char **restrict save_ptr)
 634                   _GL_ARG_NONNULL ((2, 3)));
 635 _GL_CXXALIAS_RPL (strtok_r, char *,
 636                   (char *restrict s, char const *restrict delim,
 637                    char **restrict save_ptr));
 638 # else
 639 #  if @UNDEFINE_STRTOK_R@ || defined GNULIB_POSIXCHECK
 640 #   undef strtok_r
 641 #  endif
 642 #  if ! @HAVE_DECL_STRTOK_R@
 643 _GL_FUNCDECL_SYS (strtok_r, char *,
 644                   (char *restrict s, char const *restrict delim,
 645                    char **restrict save_ptr)
 646                   _GL_ARG_NONNULL ((2, 3)));
 647 #  endif
 648 _GL_CXXALIAS_SYS (strtok_r, char *,
 649                   (char *restrict s, char const *restrict delim,
 650                    char **restrict save_ptr));
 651 # endif
 652 _GL_CXXALIASWARN (strtok_r);
 653 # if defined GNULIB_POSIXCHECK
 654 _GL_WARN_ON_USE (strtok_r, "strtok_r cannot work correctly on character "
 655                  "strings in multibyte locales - "
 656                  "use mbstok_r if you care about internationalization");
 657 # endif
 658 #elif defined GNULIB_POSIXCHECK
 659 # undef strtok_r
 660 # if HAVE_RAW_DECL_STRTOK_R
 661 _GL_WARN_ON_USE (strtok_r, "strtok_r is unportable - "
 662                  "use gnulib module strtok_r for portability");
 663 # endif
 664 #endif
 665
 666
 667 /* The following functions are not specified by POSIX.  They are gnulib
 668    extensions.  */
 669
 670 #if @GNULIB_MBSLEN@
 671 /* Return the number of multibyte characters in the character string STRING.
 672    This considers multibyte characters, unlike strlen, which counts bytes.  */
 673 # ifdef __MirBSD__  /* MirBSD defines mbslen as a macro.  Override it.  */
 674 #  undef mbslen
 675 # endif
 676 # if @HAVE_MBSLEN@  /* AIX, OSF/1, MirBSD define mbslen already in libc.  */
 677 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 678 #   define mbslen rpl_mbslen
 679 #  endif
 680 _GL_FUNCDECL_RPL (mbslen, size_t, (const char *string) _GL_ARG_NONNULL ((1)));
 681 _GL_CXXALIAS_RPL (mbslen, size_t, (const char *string));
 682 # else
 683 _GL_FUNCDECL_SYS (mbslen, size_t, (const char *string) _GL_ARG_NONNULL ((1)));
 684 _GL_CXXALIAS_SYS (mbslen, size_t, (const char *string));
 685 # endif
 686 _GL_CXXALIASWARN (mbslen);
 687 #endif
 688
 689 #if @GNULIB_MBSNLEN@
 690 /* Return the number of multibyte characters in the character string starting
 691    at STRING and ending at STRING + LEN.  */
 692 _GL_EXTERN_C size_t mbsnlen (const char *string, size_t len)
 693      _GL_ARG_NONNULL ((1));
 694 #endif
 695
 696 #if @GNULIB_MBSCHR@
 697 /* Locate the first single-byte character C in the character string STRING,
 698    and return a pointer to it.  Return NULL if C is not found in STRING.
 699    Unlike strchr(), this function works correctly in multibyte locales with
 700    encodings such as GB18030.  */
 701 # if defined __hpux
 702 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 703 #   define mbschr rpl_mbschr /* avoid collision with HP-UX function */
 704 #  endif
 705 _GL_FUNCDECL_RPL (mbschr, char *, (const char *string, int c)
 706                                   _GL_ARG_NONNULL ((1)));
 707 _GL_CXXALIAS_RPL (mbschr, char *, (const char *string, int c));
 708 # else
 709 _GL_FUNCDECL_SYS (mbschr, char *, (const char *string, int c)
 710                                   _GL_ARG_NONNULL ((1)));
 711 _GL_CXXALIAS_SYS (mbschr, char *, (const char *string, int c));
 712 # endif
 713 _GL_CXXALIASWARN (mbschr);
 714 #endif
 715
 716 #if @GNULIB_MBSRCHR@
 717 /* Locate the last single-byte character C in the character string STRING,
 718    and return a pointer to it.  Return NULL if C is not found in STRING.
 719    Unlike strrchr(), this function works correctly in multibyte locales with
 720    encodings such as GB18030.  */
 721 # if defined __hpux
 722 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 723 #   define mbsrchr rpl_mbsrchr /* avoid collision with HP-UX function */
 724 #  endif
 725 _GL_FUNCDECL_RPL (mbsrchr, char *, (const char *string, int c)
 726                                    _GL_ARG_NONNULL ((1)));
 727 _GL_CXXALIAS_RPL (mbsrchr, char *, (const char *string, int c));
 728 # else
 729 _GL_FUNCDECL_SYS (mbsrchr, char *, (const char *string, int c)
 730                                    _GL_ARG_NONNULL ((1)));
 731 _GL_CXXALIAS_SYS (mbsrchr, char *, (const char *string, int c));
 732 # endif
 733 _GL_CXXALIASWARN (mbsrchr);
 734 #endif
 735
 736 #if @GNULIB_MBSSTR@
 737 /* Find the first occurrence of the character string NEEDLE in the character
 738    string HAYSTACK.  Return NULL if NEEDLE is not found in HAYSTACK.
 739    Unlike strstr(), this function works correctly in multibyte locales with
 740    encodings different from UTF-8.  */
 741 _GL_EXTERN_C char * mbsstr (const char *haystack, const char *needle)
 742      _GL_ARG_NONNULL ((1, 2));
 743 #endif
 744
 745 #if @GNULIB_MBSCASECMP@
 746 /* Compare the character strings S1 and S2, ignoring case, returning less than,
 747    equal to or greater than zero if S1 is lexicographically less than, equal to
 748    or greater than S2.
 749    Note: This function may, in multibyte locales, return 0 for strings of
 750    different lengths!
 751    Unlike strcasecmp(), this function works correctly in multibyte locales.  */
 752 _GL_EXTERN_C int mbscasecmp (const char *s1, const char *s2)
 753      _GL_ARG_NONNULL ((1, 2));
 754 #endif
 755
 756 #if @GNULIB_MBSNCASECMP@
 757 /* Compare the initial segment of the character string S1 consisting of at most
 758    N characters with the initial segment of the character string S2 consisting
 759    of at most N characters, ignoring case, returning less than, equal to or
 760    greater than zero if the initial segment of S1 is lexicographically less
 761    than, equal to or greater than the initial segment of S2.
 762    Note: This function may, in multibyte locales, return 0 for initial segments
 763    of different lengths!
 764    Unlike strncasecmp(), this function works correctly in multibyte locales.
 765    But beware that N is not a byte count but a character count!  */
 766 _GL_EXTERN_C int mbsncasecmp (const char *s1, const char *s2, size_t n)
 767      _GL_ARG_NONNULL ((1, 2));
 768 #endif
 769
 770 #if @GNULIB_MBSPCASECMP@
 771 /* Compare the initial segment of the character string STRING consisting of
 772    at most mbslen (PREFIX) characters with the character string PREFIX,
 773    ignoring case.  If the two match, return a pointer to the first byte
 774    after this prefix in STRING.  Otherwise, return NULL.
 775    Note: This function may, in multibyte locales, return non-NULL if STRING
 776    is of smaller length than PREFIX!
 777    Unlike strncasecmp(), this function works correctly in multibyte
 778    locales.  */
 779 _GL_EXTERN_C char * mbspcasecmp (const char *string, const char *prefix)
 780      _GL_ARG_NONNULL ((1, 2));
 781 #endif
 782
 783 #if @GNULIB_MBSCASESTR@
 784 /* Find the first occurrence of the character string NEEDLE in the character
 785    string HAYSTACK, using case-insensitive comparison.
 786    Note: This function may, in multibyte locales, return success even if
 787    strlen (haystack) < strlen (needle) !
 788    Unlike strcasestr(), this function works correctly in multibyte locales.  */
 789 _GL_EXTERN_C char * mbscasestr (const char *haystack, const char *needle)
 790      _GL_ARG_NONNULL ((1, 2));
 791 #endif
 792
 793 #if @GNULIB_MBSCSPN@
 794 /* Find the first occurrence in the character string STRING of any character
 795    in the character string ACCEPT.  Return the number of bytes from the
 796    beginning of the string to this occurrence, or to the end of the string
 797    if none exists.
 798    Unlike strcspn(), this function works correctly in multibyte locales.  */
 799 _GL_EXTERN_C size_t mbscspn (const char *string, const char *accept)
 800      _GL_ARG_NONNULL ((1, 2));
 801 #endif
 802
 803 #if @GNULIB_MBSPBRK@
 804 /* Find the first occurrence in the character string STRING of any character
 805    in the character string ACCEPT.  Return the pointer to it, or NULL if none
 806    exists.
 807    Unlike strpbrk(), this function works correctly in multibyte locales.  */
 808 # if defined __hpux
 809 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 810 #   define mbspbrk rpl_mbspbrk /* avoid collision with HP-UX function */
 811 #  endif
 812 _GL_FUNCDECL_RPL (mbspbrk, char *, (const char *string, const char *accept)
 813                                    _GL_ARG_NONNULL ((1, 2)));
 814 _GL_CXXALIAS_RPL (mbspbrk, char *, (const char *string, const char *accept));
 815 # else
 816 _GL_FUNCDECL_SYS (mbspbrk, char *, (const char *string, const char *accept)
 817                                    _GL_ARG_NONNULL ((1, 2)));
 818 _GL_CXXALIAS_SYS (mbspbrk, char *, (const char *string, const char *accept));
 819 # endif
 820 _GL_CXXALIASWARN (mbspbrk);
 821 #endif
 822
 823 #if @GNULIB_MBSSPN@
 824 /* Find the first occurrence in the character string STRING of any character
 825    not in the character string REJECT.  Return the number of bytes from the
 826    beginning of the string to this occurrence, or to the end of the string
 827    if none exists.
 828    Unlike strspn(), this function works correctly in multibyte locales.  */
 829 _GL_EXTERN_C size_t mbsspn (const char *string, const char *reject)
 830      _GL_ARG_NONNULL ((1, 2));
 831 #endif
 832
 833 #if @GNULIB_MBSSEP@
 834 /* Search the next delimiter (multibyte character listed in the character
 835    string DELIM) starting at the character string *STRINGP.
 836    If one is found, overwrite it with a NUL, and advance *STRINGP to point
 837    to the next multibyte character after it.  Otherwise, set *STRINGP to NULL.
 838    If *STRINGP was already NULL, nothing happens.
 839    Return the old value of *STRINGP.
 840
 841    This is a variant of mbstok_r() that supports empty fields.
 842
 843    Caveat: It modifies the original string.
 844    Caveat: These functions cannot be used on constant strings.
 845    Caveat: The identity of the delimiting character is lost.
 846
 847    See also mbstok_r().  */
 848 _GL_EXTERN_C char * mbssep (char **stringp, const char *delim)
 849      _GL_ARG_NONNULL ((1, 2));
 850 #endif
 851
 852 #if @GNULIB_MBSTOK_R@
 853 /* Parse the character string STRING into tokens separated by characters in
 854    the character string DELIM.
 855    If STRING is NULL, the saved pointer in SAVE_PTR is used as
 856    the next starting point.  For example:
 857         char s[] = "-abc-=-def";
 858         char *sp;
 859         x = mbstok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
 860         x = mbstok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
 861         x = mbstok_r(NULL, "=", &sp);   // x = NULL
 862                 // s = "abc\0-def\0"
 863
 864    Caveat: It modifies the original string.
 865    Caveat: These functions cannot be used on constant strings.
 866    Caveat: The identity of the delimiting character is lost.
 867
 868    See also mbssep().  */
 869 _GL_EXTERN_C char * mbstok_r (char *string, const char *delim, char **save_ptr)
 870      _GL_ARG_NONNULL ((2, 3));
 871 #endif
 872
 873 /* Map any int, typically from errno, into an error message.  */
 874 #if @GNULIB_STRERROR@
 875 # if @REPLACE_STRERROR@
 876 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 877 #   undef strerror
 878 #   define strerror rpl_strerror
 879 #  endif
 880 _GL_FUNCDECL_RPL (strerror, char *, (int));
 881 _GL_CXXALIAS_RPL (strerror, char *, (int));
 882 # else
 883 _GL_CXXALIAS_SYS (strerror, char *, (int));
 884 # endif
 885 _GL_CXXALIASWARN (strerror);
 886 #elif defined GNULIB_POSIXCHECK
 887 # undef strerror
 888 /* Assume strerror is always declared.  */
 889 _GL_WARN_ON_USE (strerror, "strerror is unportable - "
 890                  "use gnulib module strerror to guarantee non-NULL result");
 891 #endif
 892
 893 #if @GNULIB_STRSIGNAL@
 894 # if @REPLACE_STRSIGNAL@
 895 #  if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 896 #   define strsignal rpl_strsignal
 897 #  endif
 898 _GL_FUNCDECL_RPL (strsignal, char *, (int __sig));
 899 _GL_CXXALIAS_RPL (strsignal, char *, (int __sig));
 900 # else
 901 #  if ! @HAVE_DECL_STRSIGNAL@
 902 _GL_FUNCDECL_SYS (strsignal, char *, (int __sig));
 903 #  endif
 904 /* Need to cast, because on Cygwin 1.5.x systems, the return type is
 905    'const char *'.  */
 906 _GL_CXXALIAS_SYS_CAST (strsignal, char *, (int __sig));
 907 # endif
 908 _GL_CXXALIASWARN (strsignal);
 909 #elif defined GNULIB_POSIXCHECK
 910 # undef strsignal
 911 # if HAVE_RAW_DECL_STRSIGNAL
 912 _GL_WARN_ON_USE (strsignal, "strsignal is unportable - "
 913                  "use gnulib module strsignal for portability");
 914 # endif
 915 #endif
 916
 917 #if @GNULIB_STRVERSCMP@
 918 # if !@HAVE_STRVERSCMP@
 919 _GL_FUNCDECL_SYS (strverscmp, int, (const char *, const char *)
 920                                    _GL_ARG_NONNULL ((1, 2)));
 921 # endif
 922 _GL_CXXALIAS_SYS (strverscmp, int, (const char *, const char *));
 923 _GL_CXXALIASWARN (strverscmp);
 924 #elif defined GNULIB_POSIXCHECK
 925 # undef strverscmp
 926 # if HAVE_RAW_DECL_STRVERSCMP
 927 _GL_WARN_ON_USE (strverscmp, "strverscmp is unportable - "
 928                  "use gnulib module strverscmp for portability");
 929 # endif
 930 #endif
 931
 932
 933 #endif /* _GL_STRING_H */
 934 #endif /* _GL_STRING_H */