1/* A GNU-like <string.h>. 2 3 Copyright (C) 1995-1996, 2001-2007 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 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 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/* The include_next requires a split double-inclusion guard. */ 22#@INCLUDE_NEXT@ @NEXT_STRING_H@ 23 24#ifndef _GL_STRING_H 25#define _GL_STRING_H 26 27 28/* The definition of GL_LINK_WARNING is copied here. */ 29 30 31#ifdef __cplusplus 32extern "C" { 33#endif 34 35/* Return the first occurrence of NEEDLE in HAYSTACK. */ 36#if @GNULIB_MEMMEM@ 37# if ! @HAVE_DECL_MEMMEM@ 38extern void *memmem (void const *__haystack, size_t __haystack_len, 39 void const *__needle, size_t __needle_len); 40# endif 41#elif defined GNULIB_POSIXCHECK 42# undef memmem 43# define memmem(a,al,b,bl) \ 44 (GL_LINK_WARNING ("memmem is unportable - " \ 45 "use gnulib module memmem for portability"), \ 46 memmem (a, al, b, bl)) 47#endif 48 49/* Copy N bytes of SRC to DEST, return pointer to bytes after the 50 last written byte. */ 51#if @GNULIB_MEMPCPY@ 52# if ! @HAVE_MEMPCPY@ 53extern void *mempcpy (void *restrict __dest, void const *restrict __src, 54 size_t __n); 55# endif 56#elif defined GNULIB_POSIXCHECK 57# undef mempcpy 58# define mempcpy(a,b,n) \ 59 (GL_LINK_WARNING ("mempcpy is unportable - " \ 60 "use gnulib module mempcpy for portability"), \ 61 mempcpy (a, b, n)) 62#endif 63 64/* Search backwards through a block for a byte (specified as an int). */ 65#if @GNULIB_MEMRCHR@ 66# if ! @HAVE_DECL_MEMRCHR@ 67extern void *memrchr (void const *, int, size_t); 68# endif 69#elif defined GNULIB_POSIXCHECK 70# undef memrchr 71# define memrchr(a,b,c) \ 72 (GL_LINK_WARNING ("memrchr is unportable - " \ 73 "use gnulib module memrchr for portability"), \ 74 memrchr (a, b, c)) 75#endif 76 77/* Copy SRC to DST, returning the address of the terminating '\0' in DST. */ 78#if @GNULIB_STPCPY@ 79# if ! @HAVE_STPCPY@ 80extern char *stpcpy (char *restrict __dst, char const *restrict __src); 81# endif 82#elif defined GNULIB_POSIXCHECK 83# undef stpcpy 84# define stpcpy(a,b) \ 85 (GL_LINK_WARNING ("stpcpy is unportable - " \ 86 "use gnulib module stpcpy for portability"), \ 87 stpcpy (a, b)) 88#endif 89 90/* Copy no more than N bytes of SRC to DST, returning a pointer past the 91 last non-NUL byte written into DST. */ 92#if @GNULIB_STPNCPY@ 93# if ! @HAVE_STPNCPY@ 94# define stpncpy gnu_stpncpy 95extern char *stpncpy (char *restrict __dst, char const *restrict __src, 96 size_t __n); 97# endif 98#elif defined GNULIB_POSIXCHECK 99# undef stpncpy 100# define stpncpy(a,b,n) \ 101 (GL_LINK_WARNING ("stpncpy is unportable - " \ 102 "use gnulib module stpncpy for portability"), \ 103 stpncpy (a, b, n)) 104#endif 105 106/* Compare strings S1 and S2, ignoring case, returning less than, equal to or 107 greater than zero if S1 is lexicographically less than, equal to or greater 108 than S2. 109 Note: This function does not work in multibyte locales. */ 110#if ! @HAVE_STRCASECMP@ 111extern int strcasecmp (char const *s1, char const *s2); 112#endif 113#if defined GNULIB_POSIXCHECK 114/* strcasecmp() does not work with multibyte strings: 115 POSIX says that it operates on "strings", and "string" in POSIX is defined 116 as a sequence of bytes, not of characters. */ 117# undef strcasecmp 118# define strcasecmp(a,b) \ 119 (GL_LINK_WARNING ("strcasecmp cannot work correctly on character strings " \ 120 "in multibyte locales - " \ 121 "use mbscasecmp if you care about " \ 122 "internationalization, or use c_strcasecmp (from " \ 123 "gnulib module c-strcase) if you want a locale " \ 124 "independent function"), \ 125 strcasecmp (a, b)) 126#endif 127 128/* Compare no more than N bytes of strings S1 and S2, ignoring case, 129 returning less than, equal to or greater than zero if S1 is 130 lexicographically less than, equal to or greater than S2. 131 Note: This function cannot work correctly in multibyte locales. */ 132#if ! @HAVE_DECL_STRNCASECMP@ 133extern int strncasecmp (char const *s1, char const *s2, size_t n); 134#endif 135#if defined GNULIB_POSIXCHECK 136/* strncasecmp() does not work with multibyte strings: 137 POSIX says that it operates on "strings", and "string" in POSIX is defined 138 as a sequence of bytes, not of characters. */ 139# undef strncasecmp 140# define strncasecmp(a,b,n) \ 141 (GL_LINK_WARNING ("strncasecmp cannot work correctly on character " \ 142 "strings in multibyte locales - " \ 143 "use mbsncasecmp or mbspcasecmp if you care about " \ 144 "internationalization, or use c_strncasecmp (from " \ 145 "gnulib module c-strcase) if you want a locale " \ 146 "independent function"), \ 147 strncasecmp (a, b, n)) 148#endif 149 150#if defined GNULIB_POSIXCHECK 151/* strchr() does not work with multibyte strings if the locale encoding is 152 GB18030 and the character to be searched is a digit. */ 153# undef strchr 154# define strchr(s,c) \ 155 (GL_LINK_WARNING ("strchr cannot work correctly on character strings " \ 156 "in some multibyte locales - " \ 157 "use mbschr if you care about internationalization"), \ 158 strchr (s, c)) 159#endif 160 161/* Find the first occurrence of C in S or the final NUL byte. */ 162#if @GNULIB_STRCHRNUL@ 163# if ! @HAVE_STRCHRNUL@ 164extern char *strchrnul (char const *__s, int __c_in); 165# endif 166#elif defined GNULIB_POSIXCHECK 167# undef strchrnul 168# define strchrnul(a,b) \ 169 (GL_LINK_WARNING ("strchrnul is unportable - " \ 170 "use gnulib module strchrnul for portability"), \ 171 strchrnul (a, b)) 172#endif 173 174/* Duplicate S, returning an identical malloc'd string. */ 175#if @GNULIB_STRDUP@ 176# if ! @HAVE_DECL_STRDUP@ && ! defined strdup 177extern char *strdup (char const *__s); 178# endif 179#elif defined GNULIB_POSIXCHECK 180# undef strdup 181# define strdup(a) \ 182 (GL_LINK_WARNING ("strdup is unportable - " \ 183 "use gnulib module strdup for portability"), \ 184 strdup (a)) 185#endif 186 187/* Return a newly allocated copy of at most N bytes of STRING. */ 188#if @GNULIB_STRNDUP@ 189# if ! @HAVE_STRNDUP@ 190# undef strndup 191# define strndup rpl_strndup 192# endif 193# if ! @HAVE_STRNDUP@ || ! @HAVE_DECL_STRNDUP@ 194extern char *strndup (char const *__string, size_t __n); 195# endif 196#elif defined GNULIB_POSIXCHECK 197# undef strndup 198# define strndup(a,n) \ 199 (GL_LINK_WARNING ("strndup is unportable - " \ 200 "use gnulib module strndup for portability"), \ 201 strndup (a, n)) 202#endif 203 204/* Find the length (number of bytes) of STRING, but scan at most 205 MAXLEN bytes. If no '\0' terminator is found in that many bytes, 206 return MAXLEN. */ 207#if @GNULIB_STRNLEN@ 208# if ! @HAVE_DECL_STRNLEN@ 209extern size_t strnlen (char const *__string, size_t __maxlen); 210# endif 211#elif defined GNULIB_POSIXCHECK 212# undef strnlen 213# define strnlen(a,n) \ 214 (GL_LINK_WARNING ("strnlen is unportable - " \ 215 "use gnulib module strnlen for portability"), \ 216 strnlen (a, n)) 217#endif 218 219#if defined GNULIB_POSIXCHECK 220/* strcspn() assumes the second argument is a list of single-byte characters. 221 Even in this simple case, it does not work with multibyte strings if the 222 locale encoding is GB18030 and one of the characters to be searched is a 223 digit. */ 224# undef strcspn 225# define strcspn(s,a) \ 226 (GL_LINK_WARNING ("strcspn cannot work correctly on character strings " \ 227 "in multibyte locales - " \ 228 "use mbscspn if you care about internationalization"), \ 229 strcspn (s, a)) 230#endif 231 232/* Find the first occurrence in S of any character in ACCEPT. */ 233#if @GNULIB_STRPBRK@ 234# if ! @HAVE_STRPBRK@ 235extern char *strpbrk (char const *__s, char const *__accept); 236# endif 237# if defined GNULIB_POSIXCHECK 238/* strpbrk() assumes the second argument is a list of single-byte characters. 239 Even in this simple case, it does not work with multibyte strings if the 240 locale encoding is GB18030 and one of the characters to be searched is a 241 digit. */ 242# undef strpbrk 243# define strpbrk(s,a) \ 244 (GL_LINK_WARNING ("strpbrk cannot work correctly on character strings " \ 245 "in multibyte locales - " \ 246 "use mbspbrk if you care about internationalization"), \ 247 strpbrk (s, a)) 248# endif 249#elif defined GNULIB_POSIXCHECK 250# undef strpbrk 251# define strpbrk(s,a) \ 252 (GL_LINK_WARNING ("strpbrk is unportable - " \ 253 "use gnulib module strpbrk for portability"), \ 254 strpbrk (s, a)) 255#endif 256 257#if defined GNULIB_POSIXCHECK 258/* strspn() assumes the second argument is a list of single-byte characters. 259 Even in this simple case, it cannot work with multibyte strings. */ 260# undef strspn 261# define strspn(s,a) \ 262 (GL_LINK_WARNING ("strspn cannot work correctly on character strings " \ 263 "in multibyte locales - " \ 264 "use mbsspn if you care about internationalization"), \ 265 strspn (s, a)) 266#endif 267 268#if defined GNULIB_POSIXCHECK 269/* strrchr() does not work with multibyte strings if the locale encoding is 270 GB18030 and the character to be searched is a digit. */ 271# undef strrchr 272# define strrchr(s,c) \ 273 (GL_LINK_WARNING ("strrchr cannot work correctly on character strings " \ 274 "in some multibyte locales - " \ 275 "use mbsrchr if you care about internationalization"), \ 276 strrchr (s, c)) 277#endif 278 279/* Search the next delimiter (char listed in DELIM) starting at *STRINGP. 280 If one is found, overwrite it with a NUL, and advance *STRINGP 281 to point to the next char after it. Otherwise, set *STRINGP to NULL. 282 If *STRINGP was already NULL, nothing happens. 283 Return the old value of *STRINGP. 284 285 This is a variant of strtok() that is multithread-safe and supports 286 empty fields. 287 288 Caveat: It modifies the original string. 289 Caveat: These functions cannot be used on constant strings. 290 Caveat: The identity of the delimiting character is lost. 291 Caveat: It doesn't work with multibyte strings unless all of the delimiter 292 characters are ASCII characters < 0x30. 293 294 See also strtok_r(). */ 295#if @GNULIB_STRSEP@ 296# if ! @HAVE_STRSEP@ 297extern char *strsep (char **restrict __stringp, char const *restrict __delim); 298# endif 299# if defined GNULIB_POSIXCHECK 300# undef strsep 301# define strsep(s,d) \ 302 (GL_LINK_WARNING ("strsep cannot work correctly on character strings " \ 303 "in multibyte locales - " \ 304 "use mbssep if you care about internationalization"), \ 305 strsep (s, d)) 306# endif 307#elif defined GNULIB_POSIXCHECK 308# undef strsep 309# define strsep(s,d) \ 310 (GL_LINK_WARNING ("strsep is unportable - " \ 311 "use gnulib module strsep for portability"), \ 312 strsep (s, d)) 313#endif 314 315#if defined GNULIB_POSIXCHECK 316/* strstr() does not work with multibyte strings if the locale encoding is 317 different from UTF-8: 318 POSIX says that it operates on "strings", and "string" in POSIX is defined 319 as a sequence of bytes, not of characters. */ 320# undef strstr 321# define strstr(a,b) \ 322 (GL_LINK_WARNING ("strstr cannot work correctly on character strings " \ 323 "in most multibyte locales - " \ 324 "use mbsstr if you care about internationalization"), \ 325 strstr (a, b)) 326#endif 327 328/* Find the first occurrence of NEEDLE in HAYSTACK, using case-insensitive 329 comparison. */ 330#if ! @HAVE_STRCASESTR@ 331extern char *strcasestr (const char *haystack, const char *needle); 332#endif 333#if defined GNULIB_POSIXCHECK 334/* strcasestr() does not work with multibyte strings: 335 It is a glibc extension, and glibc implements it only for unibyte 336 locales. */ 337# undef strcasestr 338# define strcasestr(a,b) \ 339 (GL_LINK_WARNING ("strcasestr does work correctly on character strings " \ 340 "in multibyte locales - " \ 341 "use mbscasestr if you care about " \ 342 "internationalization, or use c-strcasestr if you want " \ 343 "a locale independent function"), \ 344 strcasestr (a, b)) 345#endif 346 347/* Parse S into tokens separated by characters in DELIM. 348 If S is NULL, the saved pointer in SAVE_PTR is used as 349 the next starting point. For example: 350 char s[] = "-abc-=-def"; 351 char *sp; 352 x = strtok_r(s, "-", &sp); // x = "abc", sp = "=-def" 353 x = strtok_r(NULL, "-=", &sp); // x = "def", sp = NULL 354 x = strtok_r(NULL, "=", &sp); // x = NULL 355 // s = "abc\0-def\0" 356 357 This is a variant of strtok() that is multithread-safe. 358 359 For the POSIX documentation for this function, see: 360 http://www.opengroup.org/susv3xsh/strtok.html 361 362 Caveat: It modifies the original string. 363 Caveat: These functions cannot be used on constant strings. 364 Caveat: The identity of the delimiting character is lost. 365 Caveat: It doesn't work with multibyte strings unless all of the delimiter 366 characters are ASCII characters < 0x30. 367 368 See also strsep(). */ 369#if @GNULIB_STRTOK_R@ 370# if ! @HAVE_DECL_STRTOK_R@ 371extern char *strtok_r (char *restrict s, char const *restrict delim, 372 char **restrict save_ptr); 373# endif 374# if defined GNULIB_POSIXCHECK 375# undef strtok_r 376# define strtok_r(s,d,p) \ 377 (GL_LINK_WARNING ("strtok_r cannot work correctly on character strings " \ 378 "in multibyte locales - " \ 379 "use mbstok_r if you care about internationalization"), \ 380 strtok_r (s, d, p)) 381# endif 382#elif defined GNULIB_POSIXCHECK 383# undef strtok_r 384# define strtok_r(s,d,p) \ 385 (GL_LINK_WARNING ("strtok_r is unportable - " \ 386 "use gnulib module strtok_r for portability"), \ 387 strtok_r (s, d, p)) 388#endif 389 390 391/* The following functions are not specified by POSIX. They are gnulib 392 extensions. */ 393 394#if @GNULIB_MBSLEN@ 395/* Return the number of multibyte characters in the character string STRING. 396 This considers multibyte characters, unlike strlen, which counts bytes. */ 397extern size_t mbslen (const char *string); 398#endif 399 400#if @GNULIB_MBSNLEN@ 401/* Return the number of multibyte characters in the character string starting 402 at STRING and ending at STRING + LEN. */ 403extern size_t mbsnlen (const char *string, size_t len); 404#endif 405 406#if @GNULIB_MBSCHR@ 407/* Locate the first single-byte character C in the character string STRING, 408 and return a pointer to it. Return NULL if C is not found in STRING. 409 Unlike strchr(), this function works correctly in multibyte locales with 410 encodings such as GB18030. */ 411# define mbschr rpl_mbschr /* avoid collision with HP-UX function */ 412extern char * mbschr (const char *string, int c); 413#endif 414 415#if @GNULIB_MBSRCHR@ 416/* Locate the last single-byte character C in the character string STRING, 417 and return a pointer to it. Return NULL if C is not found in STRING. 418 Unlike strrchr(), this function works correctly in multibyte locales with 419 encodings such as GB18030. */ 420# define mbsrchr rpl_mbsrchr /* avoid collision with HP-UX function */ 421extern char * mbsrchr (const char *string, int c); 422#endif 423 424#if @GNULIB_MBSSTR@ 425/* Find the first occurrence of the character string NEEDLE in the character 426 string HAYSTACK. Return NULL if NEEDLE is not found in HAYSTACK. 427 Unlike strstr(), this function works correctly in multibyte locales with 428 encodings different from UTF-8. */ 429extern char * mbsstr (const char *haystack, const char *needle); 430#endif 431 432#if @GNULIB_MBSCASECMP@ 433/* Compare the character strings S1 and S2, ignoring case, returning less than, 434 equal to or greater than zero if S1 is lexicographically less than, equal to 435 or greater than S2. 436 Note: This function may, in multibyte locales, return 0 for strings of 437 different lengths! 438 Unlike strcasecmp(), this function works correctly in multibyte locales. */ 439extern int mbscasecmp (const char *s1, const char *s2); 440#endif 441 442#if @GNULIB_MBSNCASECMP@ 443/* Compare the initial segment of the character string S1 consisting of at most 444 N characters with the initial segment of the character string S2 consisting 445 of at most N characters, ignoring case, returning less than, equal to or 446 greater than zero if the initial segment of S1 is lexicographically less 447 than, equal to or greater than the initial segment of S2. 448 Note: This function may, in multibyte locales, return 0 for initial segments 449 of different lengths! 450 Unlike strncasecmp(), this function works correctly in multibyte locales. 451 But beware that N is not a byte count but a character count! */ 452extern int mbsncasecmp (const char *s1, const char *s2, size_t n); 453#endif 454 455#if @GNULIB_MBSPCASECMP@ 456/* Compare the initial segment of the character string STRING consisting of 457 at most mbslen (PREFIX) characters with the character string PREFIX, 458 ignoring case, returning less than, equal to or greater than zero if this 459 initial segment is lexicographically less than, equal to or greater than 460 PREFIX. 461 Note: This function may, in multibyte locales, return 0 if STRING is of 462 smaller length than PREFIX! 463 Unlike strncasecmp(), this function works correctly in multibyte 464 locales. */ 465extern char * mbspcasecmp (const char *string, const char *prefix); 466#endif 467 468#if @GNULIB_MBSCASESTR@ 469/* Find the first occurrence of the character string NEEDLE in the character 470 string HAYSTACK, using case-insensitive comparison. 471 Note: This function may, in multibyte locales, return success even if 472 strlen (haystack) < strlen (needle) ! 473 Unlike strcasestr(), this function works correctly in multibyte locales. */ 474extern char * mbscasestr (const char *haystack, const char *needle); 475#endif 476 477#if @GNULIB_MBSCSPN@ 478/* Find the first occurrence in the character string STRING of any character 479 in the character string ACCEPT. Return the number of bytes from the 480 beginning of the string to this occurrence, or to the end of the string 481 if none exists. 482 Unlike strcspn(), this function works correctly in multibyte locales. */ 483extern size_t mbscspn (const char *string, const char *accept); 484#endif 485 486#if @GNULIB_MBSPBRK@ 487/* Find the first occurrence in the character string STRING of any character 488 in the character string ACCEPT. Return the pointer to it, or NULL if none 489 exists. 490 Unlike strpbrk(), this function works correctly in multibyte locales. */ 491# define mbspbrk rpl_mbspbrk /* avoid collision with HP-UX function */ 492extern char * mbspbrk (const char *string, const char *accept); 493#endif 494 495#if @GNULIB_MBSSPN@ 496/* Find the first occurrence in the character string STRING of any character 497 not in the character string REJECT. Return the number of bytes from the 498 beginning of the string to this occurrence, or to the end of the string 499 if none exists. 500 Unlike strspn(), this function works correctly in multibyte locales. */ 501extern size_t mbsspn (const char *string, const char *reject); 502#endif 503 504#if @GNULIB_MBSSEP@ 505/* Search the next delimiter (multibyte character listed in the character 506 string DELIM) starting at the character string *STRINGP. 507 If one is found, overwrite it with a NUL, and advance *STRINGP to point 508 to the next multibyte character after it. Otherwise, set *STRINGP to NULL. 509 If *STRINGP was already NULL, nothing happens. 510 Return the old value of *STRINGP. 511 512 This is a variant of mbstok_r() that supports empty fields. 513 514 Caveat: It modifies the original string. 515 Caveat: These functions cannot be used on constant strings. 516 Caveat: The identity of the delimiting character is lost. 517 518 See also mbstok_r(). */ 519extern char * mbssep (char **stringp, const char *delim); 520#endif 521 522#if @GNULIB_MBSTOK_R@ 523/* Parse the character string STRING into tokens separated by characters in 524 the character string DELIM. 525 If STRING is NULL, the saved pointer in SAVE_PTR is used as 526 the next starting point. For example: 527 char s[] = "-abc-=-def"; 528 char *sp; 529 x = mbstok_r(s, "-", &sp); // x = "abc", sp = "=-def" 530 x = mbstok_r(NULL, "-=", &sp); // x = "def", sp = NULL 531 x = mbstok_r(NULL, "=", &sp); // x = NULL 532 // s = "abc\0-def\0" 533 534 Caveat: It modifies the original string. 535 Caveat: These functions cannot be used on constant strings. 536 Caveat: The identity of the delimiting character is lost. 537 538 See also mbssep(). */ 539extern char * mbstok_r (char *string, const char *delim, char **save_ptr); 540#endif 541 542/* Map any int, typically from errno, into an error message. */ 543#if @GNULIB_STRERROR@ 544# if @REPLACE_STRERROR@ 545# undef strerror 546# define strerror rpl_strerror 547extern char *strerror (int); 548# endif 549#elif defined GNULIB_POSIXCHECK 550# undef strerror 551# define strerror(e) \ 552 (GL_LINK_WARNING ("strerror is unportable - " \ 553 "use gnulib module strerror to guarantee non-NULL result"), \ 554 strerror (e)) 555#endif 556 557 558#ifdef __cplusplus 559} 560#endif 561 562#endif /* _GL_STRING_H */ 563#endif /* _GL_STRING_H */ 564