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