1 /* A GNU-like <string.h>.
3 Copyright (C) 1995-1996, 2001-2010 Free Software Foundation, Inc.
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)
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.
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. */
22 @PRAGMA_SYSTEM_HEADER@
25 /* The include_next requires a split double-inclusion guard. */
26 #@INCLUDE_NEXT@ @NEXT_STRING_H@
31 /* NetBSD 5.0 mis-defines NULL. */
34 /* MirBSD defines mbslen as a macro. */
35 #if @GNULIB_MBSLEN@ && defined __MirBSD__
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 */
44 /* The attribute __pure__ was added in gcc 2.96. */
45 # if __GNUC__ < 2 || (__GNUC__ == 2 && __GNUC_MINOR__ < 96)
46 # define __pure__ /* empty */
51 /* The definition of _GL_ARG_NONNULL is copied here. */
53 /* The definition of _GL_WARN_ON_USE is copied here. */
61 /* Return the first instance of C within N bytes of S, or NULL. */
64 # define memchr rpl_memchr
65 extern void *memchr (void const *__s
, int __c
, size_t __n
)
66 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1));
68 #elif defined GNULIB_POSIXCHECK
70 /* Assume memchr is always declared. */
71 _GL_WARN_ON_USE (memchr
, "memchr has platform-specific bugs - "
72 "use gnulib module memchr for portability" );
75 /* Return the first occurrence of NEEDLE in HAYSTACK. */
78 # define memmem rpl_memmem
80 # if ! @HAVE_DECL_MEMMEM@ || @REPLACE_MEMMEM@
81 extern void *memmem (void const *__haystack
, size_t __haystack_len
,
82 void const *__needle
, size_t __needle_len
)
83 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1, 3));
85 #elif defined GNULIB_POSIXCHECK
87 # if HAVE_RAW_DECL_MEMMEM
88 _GL_WARN_ON_USE (memmem
, "memmem is unportable and often quadratic - "
89 "use gnulib module memmem-simple for portability, "
90 "and module memmem for speed" );
94 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
98 extern void *mempcpy (void *restrict __dest
, void const *restrict __src
,
100 _GL_ARG_NONNULL ((1, 2));
102 #elif defined GNULIB_POSIXCHECK
104 # if HAVE_RAW_DECL_MEMPCPY
105 _GL_WARN_ON_USE (mempcpy
, "mempcpy is unportable - "
106 "use gnulib module mempcpy for portability");
110 /* Search backwards through a block for a byte (specified as an int). */
112 # if ! @HAVE_DECL_MEMRCHR@
113 extern void *memrchr (void const *, int, size_t)
114 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1));
116 #elif defined GNULIB_POSIXCHECK
118 # if HAVE_RAW_DECL_MEMRCHR
119 _GL_WARN_ON_USE (memrchr
, "memrchr is unportable - "
120 "use gnulib module memrchr for portability");
124 /* Find the first occurrence of C in S. More efficient than
125 memchr(S,C,N), at the expense of undefined behavior if C does not
126 occur within N bytes. */
127 #if @GNULIB_RAWMEMCHR@
128 # if ! @HAVE_RAWMEMCHR@
129 extern void *rawmemchr (void const *__s
, int __c_in
)
130 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1));
132 #elif defined GNULIB_POSIXCHECK
134 # if HAVE_RAW_DECL_RAWMEMCHR
135 _GL_WARN_ON_USE (rawmemchr
, "rawmemchr is unportable - "
136 "use gnulib module rawmemchr for portability");
140 /* Copy SRC to DST, returning the address of the terminating '\0' in DST. */
143 extern char *stpcpy (char *restrict __dst
, char const *restrict __src
)
144 _GL_ARG_NONNULL ((1, 2));
146 #elif defined GNULIB_POSIXCHECK
148 # if HAVE_RAW_DECL_STPCPY
149 _GL_WARN_ON_USE (stpcpy
, "stpcpy is unportable - "
150 "use gnulib module stpcpy for portability");
154 /* Copy no more than N bytes of SRC to DST, returning a pointer past the
155 last non-NUL byte written into DST. */
157 # if ! @HAVE_STPNCPY@
158 # define stpncpy gnu_stpncpy
159 extern char *stpncpy (char *restrict __dst
, char const *restrict __src
,
161 _GL_ARG_NONNULL ((1, 2));
163 #elif defined GNULIB_POSIXCHECK
165 # if HAVE_RAW_DECL_STPNCPY
166 _GL_WARN_ON_USE (stpncpy
, "stpncpy is unportable - "
167 "use gnulib module stpncpy for portability");
171 #if defined GNULIB_POSIXCHECK
172 /* strchr() does not work with multibyte strings if the locale encoding is
173 GB18030 and the character to be searched is a digit. */
175 /* Assume strchr is always declared. */
176 _GL_WARN_ON_USE (strchr
, "strchr cannot work correctly on character strings "
177 "in some multibyte locales - "
178 "use mbschr if you care about internationalization");
181 /* Find the first occurrence of C in S or the final NUL byte. */
182 #if @GNULIB_STRCHRNUL@
183 # if ! @HAVE_STRCHRNUL@
184 extern char *strchrnul (char const *__s
, int __c_in
)
185 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1));
187 #elif defined GNULIB_POSIXCHECK
189 # if HAVE_RAW_DECL_STRCHRNUL
190 _GL_WARN_ON_USE (strchrnul
, "strchrnul is unportable - "
191 "use gnulib module strchrnul for portability");
195 /* Duplicate S, returning an identical malloc'd string. */
197 # if @REPLACE_STRDUP@
199 # define strdup rpl_strdup
201 # if !(@HAVE_DECL_STRDUP@ || defined strdup) || @REPLACE_STRDUP@
202 extern char *strdup (char const *__s
) _GL_ARG_NONNULL ((1));
204 #elif defined GNULIB_POSIXCHECK
206 # if HAVE_RAW_DECL_STRDUP
207 _GL_WARN_ON_USE (strdup
, "strdup is unportable - "
208 "use gnulib module strdup for portability");
212 /* Return a newly allocated copy of at most N bytes of STRING. */
214 # if @REPLACE_STRNDUP@
216 # define strndup rpl_strndup
218 # if @REPLACE_STRNDUP@ || ! @HAVE_DECL_STRNDUP@
219 extern char *strndup (char const *__string
, size_t __n
) _GL_ARG_NONNULL ((1));
221 #elif defined GNULIB_POSIXCHECK
223 # if HAVE_RAW_DECL_STRNDUP
224 _GL_WARN_ON_USE (strndup
, "strndup is unportable - "
225 "use gnulib module strndup for portability");
229 /* Find the length (number of bytes) of STRING, but scan at most
230 MAXLEN bytes. If no '\0' terminator is found in that many bytes,
233 # if ! @HAVE_DECL_STRNLEN@
234 extern size_t strnlen (char const *__string
, size_t __maxlen
)
235 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1));
237 #elif defined GNULIB_POSIXCHECK
239 # if HAVE_RAW_DECL_STRNLEN
240 _GL_WARN_ON_USE (strnlen
, "strnlen is unportable - "
241 "use gnulib module strnlen for portability");
245 #if defined GNULIB_POSIXCHECK
246 /* strcspn() assumes the second argument is a list of single-byte characters.
247 Even in this simple case, it does not work with multibyte strings if the
248 locale encoding is GB18030 and one of the characters to be searched is a
251 /* Assume strcspn is always declared. */
252 _GL_WARN_ON_USE (strcspn
, "strcspn cannot work correctly on character strings "
253 "in multibyte locales - "
254 "use mbscspn if you care about internationalization");
257 /* Find the first occurrence in S of any character in ACCEPT. */
259 # if ! @HAVE_STRPBRK@
260 extern char *strpbrk (char const *__s
, char const *__accept
)
261 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1, 2));
263 # if defined GNULIB_POSIXCHECK
264 /* strpbrk() assumes the second argument is a list of single-byte characters.
265 Even in this simple case, it does not work with multibyte strings if the
266 locale encoding is GB18030 and one of the characters to be searched is a
269 _GL_WARN_ON_USE (strpbrk
, "strpbrk cannot work correctly on character strings "
270 "in multibyte locales - "
271 "use mbspbrk if you care about internationalization");
273 #elif defined GNULIB_POSIXCHECK
275 # if HAVE_RAW_DECL_STRPBRK
276 _GL_WARN_ON_USE (strpbrk
, "strpbrk is unportable - "
277 "use gnulib module strpbrk for portability");
281 #if defined GNULIB_POSIXCHECK
282 /* strspn() assumes the second argument is a list of single-byte characters.
283 Even in this simple case, it cannot work with multibyte strings. */
285 /* Assume strspn is always declared. */
286 _GL_WARN_ON_USE (strspn
, "strspn cannot work correctly on character strings "
287 "in multibyte locales - "
288 "use mbsspn if you care about internationalization");
291 #if defined GNULIB_POSIXCHECK
292 /* strrchr() does not work with multibyte strings if the locale encoding is
293 GB18030 and the character to be searched is a digit. */
295 /* Assume strrchr is always declared. */
296 _GL_WARN_ON_USE (strrchr
, "strrchr cannot work correctly on character strings "
297 "in some multibyte locales - "
298 "use mbsrchr if you care about internationalization");
301 /* Search the next delimiter (char listed in DELIM) starting at *STRINGP.
302 If one is found, overwrite it with a NUL, and advance *STRINGP
303 to point to the next char after it. Otherwise, set *STRINGP to NULL.
304 If *STRINGP was already NULL, nothing happens.
305 Return the old value of *STRINGP.
307 This is a variant of strtok() that is multithread-safe and supports
310 Caveat: It modifies the original string.
311 Caveat: These functions cannot be used on constant strings.
312 Caveat: The identity of the delimiting character is lost.
313 Caveat: It doesn't work with multibyte strings unless all of the delimiter
314 characters are ASCII characters < 0x30.
316 See also strtok_r(). */
319 extern char *strsep (char **restrict __stringp
, char const *restrict __delim
)
320 _GL_ARG_NONNULL ((1, 2));
322 # if defined GNULIB_POSIXCHECK
324 _GL_WARN_ON_USE (strsep
, "strsep cannot work correctly on character strings "
325 "in multibyte locales - "
326 "use mbssep if you care about internationalization");
328 #elif defined GNULIB_POSIXCHECK
330 # if HAVE_RAW_DECL_STRSEP
331 _GL_WARN_ON_USE (strsep
, "strsep is unportable - "
332 "use gnulib module strsep for portability");
337 # if @REPLACE_STRSTR@
338 # define strstr rpl_strstr
339 extern char *strstr (const char *haystack
, const char *needle
)
340 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1, 2));
342 #elif defined GNULIB_POSIXCHECK
343 /* strstr() does not work with multibyte strings if the locale encoding is
344 different from UTF-8:
345 POSIX says that it operates on "strings", and "string" in POSIX is defined
346 as a sequence of bytes, not of characters. */
348 /* Assume strstr is always declared. */
349 _GL_WARN_ON_USE (strstr
, "strstr is quadratic on many systems, and cannot "
350 "work correctly on character strings in most "
351 "multibyte locales - "
352 "use mbsstr if you care about internationalization, "
353 "or use strstr if you care about speed");
356 /* Find the first occurrence of NEEDLE in HAYSTACK, using case-insensitive
358 #if @GNULIB_STRCASESTR@
359 # if @REPLACE_STRCASESTR@
360 # define strcasestr rpl_strcasestr
362 # if ! @HAVE_STRCASESTR@ || @REPLACE_STRCASESTR@
363 extern char *strcasestr (const char *haystack
, const char *needle
)
364 __attribute__ ((__pure__
)) _GL_ARG_NONNULL ((1, 2));
366 #elif defined GNULIB_POSIXCHECK
367 /* strcasestr() does not work with multibyte strings:
368 It is a glibc extension, and glibc implements it only for unibyte
371 # if HAVE_RAW_DECL_STRCASESTR
372 _GL_WARN_ON_USE (strcasestr
, "strcasestr does work correctly on character "
373 "strings in multibyte locales - "
374 "use mbscasestr if you care about "
375 "internationalization, or use c-strcasestr if you want "
376 "a locale independent function");
380 /* Parse S into tokens separated by characters in DELIM.
381 If S is NULL, the saved pointer in SAVE_PTR is used as
382 the next starting point. For example:
383 char s[] = "-abc-=-def";
385 x = strtok_r(s, "-", &sp); // x = "abc", sp = "=-def"
386 x = strtok_r(NULL, "-=", &sp); // x = "def", sp = NULL
387 x = strtok_r(NULL, "=", &sp); // x = NULL
390 This is a variant of strtok() that is multithread-safe.
392 For the POSIX documentation for this function, see:
393 http://www.opengroup.org/susv3xsh/strtok.html
395 Caveat: It modifies the original string.
396 Caveat: These functions cannot be used on constant strings.
397 Caveat: The identity of the delimiting character is lost.
398 Caveat: It doesn't work with multibyte strings unless all of the delimiter
399 characters are ASCII characters < 0x30.
401 See also strsep(). */
402 #if @GNULIB_STRTOK_R@
403 # if @REPLACE_STRTOK_R@
405 # define strtok_r rpl_strtok_r
406 # elif @UNDEFINE_STRTOK_R@ || defined GNULIB_POSIXCHECK
409 # if ! @HAVE_DECL_STRTOK_R@ || @REPLACE_STRTOK_R@
410 extern char *strtok_r (char *restrict s
, char const *restrict delim
,
411 char **restrict save_ptr
)
412 _GL_ARG_NONNULL ((2, 3));
414 # if defined GNULIB_POSIXCHECK
415 _GL_WARN_ON_USE (strtok_r
, "strtok_r cannot work correctly on character "
416 "strings in multibyte locales - "
417 "use mbstok_r if you care about internationalization");
419 #elif defined GNULIB_POSIXCHECK
421 # if HAVE_RAW_DECL_STRTOK_R
422 _GL_WARN_ON_USE (strtok_r
, "strtok_r is unportable - "
423 "use gnulib module strtok_r for portability");
428 /* The following functions are not specified by POSIX. They are gnulib
432 /* Return the number of multibyte characters in the character string STRING.
433 This considers multibyte characters, unlike strlen, which counts bytes. */
434 # ifdef __MirBSD__ /* MirBSD defines mbslen as a macro. Override it. */
437 # if @HAVE_MBSLEN@ /* AIX, OSF/1, MirBSD define mbslen already in libc. */
438 # define mbslen rpl_mbslen
440 extern size_t mbslen (const char *string
) _GL_ARG_NONNULL ((1));
444 /* Return the number of multibyte characters in the character string starting
445 at STRING and ending at STRING + LEN. */
446 extern size_t mbsnlen (const char *string
, size_t len
) _GL_ARG_NONNULL ((1));
450 /* Locate the first single-byte character C in the character string STRING,
451 and return a pointer to it. Return NULL if C is not found in STRING.
452 Unlike strchr(), this function works correctly in multibyte locales with
453 encodings such as GB18030. */
454 # define mbschr rpl_mbschr /* avoid collision with HP-UX function */
455 extern char * mbschr (const char *string
, int c
) _GL_ARG_NONNULL ((1));
459 /* Locate the last single-byte character C in the character string STRING,
460 and return a pointer to it. Return NULL if C is not found in STRING.
461 Unlike strrchr(), this function works correctly in multibyte locales with
462 encodings such as GB18030. */
463 # define mbsrchr rpl_mbsrchr /* avoid collision with HP-UX function */
464 extern char * mbsrchr (const char *string
, int c
) _GL_ARG_NONNULL ((1));
468 /* Find the first occurrence of the character string NEEDLE in the character
469 string HAYSTACK. Return NULL if NEEDLE is not found in HAYSTACK.
470 Unlike strstr(), this function works correctly in multibyte locales with
471 encodings different from UTF-8. */
472 extern char * mbsstr (const char *haystack
, const char *needle
)
473 _GL_ARG_NONNULL ((1, 2));
476 #if @GNULIB_MBSCASECMP@
477 /* Compare the character strings S1 and S2, ignoring case, returning less than,
478 equal to or greater than zero if S1 is lexicographically less than, equal to
480 Note: This function may, in multibyte locales, return 0 for strings of
482 Unlike strcasecmp(), this function works correctly in multibyte locales. */
483 extern int mbscasecmp (const char *s1
, const char *s2
)
484 _GL_ARG_NONNULL ((1, 2));
487 #if @GNULIB_MBSNCASECMP@
488 /* Compare the initial segment of the character string S1 consisting of at most
489 N characters with the initial segment of the character string S2 consisting
490 of at most N characters, ignoring case, returning less than, equal to or
491 greater than zero if the initial segment of S1 is lexicographically less
492 than, equal to or greater than the initial segment of S2.
493 Note: This function may, in multibyte locales, return 0 for initial segments
494 of different lengths!
495 Unlike strncasecmp(), this function works correctly in multibyte locales.
496 But beware that N is not a byte count but a character count! */
497 extern int mbsncasecmp (const char *s1
, const char *s2
, size_t n
)
498 _GL_ARG_NONNULL ((1, 2));
501 #if @GNULIB_MBSPCASECMP@
502 /* Compare the initial segment of the character string STRING consisting of
503 at most mbslen (PREFIX) characters with the character string PREFIX,
504 ignoring case, returning less than, equal to or greater than zero if this
505 initial segment is lexicographically less than, equal to or greater than
507 Note: This function may, in multibyte locales, return 0 if STRING is of
508 smaller length than PREFIX!
509 Unlike strncasecmp(), this function works correctly in multibyte
511 extern char * mbspcasecmp (const char *string
, const char *prefix
)
512 _GL_ARG_NONNULL ((1, 2));
515 #if @GNULIB_MBSCASESTR@
516 /* Find the first occurrence of the character string NEEDLE in the character
517 string HAYSTACK, using case-insensitive comparison.
518 Note: This function may, in multibyte locales, return success even if
519 strlen (haystack) < strlen (needle) !
520 Unlike strcasestr(), this function works correctly in multibyte locales. */
521 extern char * mbscasestr (const char *haystack
, const char *needle
)
522 _GL_ARG_NONNULL ((1, 2));
526 /* Find the first occurrence in the character string STRING of any character
527 in the character string ACCEPT. Return the number of bytes from the
528 beginning of the string to this occurrence, or to the end of the string
530 Unlike strcspn(), this function works correctly in multibyte locales. */
531 extern size_t mbscspn (const char *string
, const char *accept
)
532 _GL_ARG_NONNULL ((1, 2));
536 /* Find the first occurrence in the character string STRING of any character
537 in the character string ACCEPT. Return the pointer to it, or NULL if none
539 Unlike strpbrk(), this function works correctly in multibyte locales. */
540 # define mbspbrk rpl_mbspbrk /* avoid collision with HP-UX function */
541 extern char * mbspbrk (const char *string
, const char *accept
)
542 _GL_ARG_NONNULL ((1, 2));
546 /* Find the first occurrence in the character string STRING of any character
547 not in the character string REJECT. Return the number of bytes from the
548 beginning of the string to this occurrence, or to the end of the string
550 Unlike strspn(), this function works correctly in multibyte locales. */
551 extern size_t mbsspn (const char *string
, const char *reject
)
552 _GL_ARG_NONNULL ((1, 2));
556 /* Search the next delimiter (multibyte character listed in the character
557 string DELIM) starting at the character string *STRINGP.
558 If one is found, overwrite it with a NUL, and advance *STRINGP to point
559 to the next multibyte character after it. Otherwise, set *STRINGP to NULL.
560 If *STRINGP was already NULL, nothing happens.
561 Return the old value of *STRINGP.
563 This is a variant of mbstok_r() that supports empty fields.
565 Caveat: It modifies the original string.
566 Caveat: These functions cannot be used on constant strings.
567 Caveat: The identity of the delimiting character is lost.
569 See also mbstok_r(). */
570 extern char * mbssep (char **stringp
, const char *delim
)
571 _GL_ARG_NONNULL ((1, 2));
574 #if @GNULIB_MBSTOK_R@
575 /* Parse the character string STRING into tokens separated by characters in
576 the character string DELIM.
577 If STRING is NULL, the saved pointer in SAVE_PTR is used as
578 the next starting point. For example:
579 char s[] = "-abc-=-def";
581 x = mbstok_r(s, "-", &sp); // x = "abc", sp = "=-def"
582 x = mbstok_r(NULL, "-=", &sp); // x = "def", sp = NULL
583 x = mbstok_r(NULL, "=", &sp); // x = NULL
586 Caveat: It modifies the original string.
587 Caveat: These functions cannot be used on constant strings.
588 Caveat: The identity of the delimiting character is lost.
590 See also mbssep(). */
591 extern char * mbstok_r (char *string
, const char *delim
, char **save_ptr
)
592 _GL_ARG_NONNULL ((2, 3));
595 /* Map any int, typically from errno, into an error message. */
596 #if @GNULIB_STRERROR@
597 # if @REPLACE_STRERROR@
599 # define strerror rpl_strerror
600 extern char *strerror (int);
602 #elif defined GNULIB_POSIXCHECK
604 /* Assume strerror is always declared. */
605 _GL_WARN_ON_USE (strerror
, "strerror is unportable - "
606 "use gnulib module strerror to guarantee non-NULL result");
609 #if @GNULIB_STRSIGNAL@
610 # if @REPLACE_STRSIGNAL@
611 # define strsignal rpl_strsignal
613 # if ! @HAVE_DECL_STRSIGNAL@ || @REPLACE_STRSIGNAL@
614 extern char *strsignal (int __sig
);
616 #elif defined GNULIB_POSIXCHECK
618 # if HAVE_RAW_DECL_STRSIGNAL
619 _GL_WARN_ON_USE (strsignal
, "strsignal is unportable - "
620 "use gnulib module strsignal for portability");
624 #if @GNULIB_STRVERSCMP@
625 # if !@HAVE_STRVERSCMP@
626 extern int strverscmp (const char *, const char *) _GL_ARG_NONNULL ((1, 2));
628 #elif defined GNULIB_POSIXCHECK
630 # if HAVE_RAW_DECL_STRVERSCMP
631 _GL_WARN_ON_USE (strverscmp
, "strverscmp is unportable - "
632 "use gnulib module strverscmp for portability");
641 #endif /* _GL_STRING_H */
642 #endif /* _GL_STRING_H */