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