lib/string.in.h

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