git.cworth.org Git - tar/blob - gnu/string.in.h

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