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