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