Replace strsignal if it does not work fine.
[gnulib.git] / 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 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 #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 ! @HAVE_STRCASESTR@
317 extern char *strcasestr (const char *haystack, const char *needle)
318   __attribute__ ((__pure__));
319 #endif
320 #if defined GNULIB_POSIXCHECK
321 /* strcasestr() does not work with multibyte strings:
322    It is a glibc extension, and glibc implements it only for unibyte
323    locales.  */
324 # undef strcasestr
325 # define strcasestr(a,b) \
326     (GL_LINK_WARNING ("strcasestr does work correctly on character strings " \
327                       "in multibyte locales - " \
328                       "use mbscasestr if you care about " \
329                       "internationalization, or use c-strcasestr if you want " \
330                       "a locale independent function"), \
331      strcasestr (a, b))
332 #endif
333
334 /* Parse S into tokens separated by characters in DELIM.
335    If S is NULL, the saved pointer in SAVE_PTR is used as
336    the next starting point.  For example:
337         char s[] = "-abc-=-def";
338         char *sp;
339         x = strtok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
340         x = strtok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
341         x = strtok_r(NULL, "=", &sp);   // x = NULL
342                 // s = "abc\0-def\0"
343
344    This is a variant of strtok() that is multithread-safe.
345
346    For the POSIX documentation for this function, see:
347    http://www.opengroup.org/susv3xsh/strtok.html
348
349    Caveat: It modifies the original string.
350    Caveat: These functions cannot be used on constant strings.
351    Caveat: The identity of the delimiting character is lost.
352    Caveat: It doesn't work with multibyte strings unless all of the delimiter
353            characters are ASCII characters < 0x30.
354
355    See also strsep().  */
356 #if @GNULIB_STRTOK_R@
357 # if ! @HAVE_DECL_STRTOK_R@
358 extern char *strtok_r (char *restrict s, char const *restrict delim,
359                        char **restrict save_ptr);
360 # endif
361 # if defined GNULIB_POSIXCHECK
362 #  undef strtok_r
363 #  define strtok_r(s,d,p) \
364      (GL_LINK_WARNING ("strtok_r cannot work correctly on character strings " \
365                        "in multibyte locales - " \
366                        "use mbstok_r if you care about internationalization"), \
367       strtok_r (s, d, p))
368 # endif
369 #elif defined GNULIB_POSIXCHECK
370 # undef strtok_r
371 # define strtok_r(s,d,p) \
372     (GL_LINK_WARNING ("strtok_r is unportable - " \
373                       "use gnulib module strtok_r for portability"), \
374      strtok_r (s, d, p))
375 #endif
376
377
378 /* The following functions are not specified by POSIX.  They are gnulib
379    extensions.  */
380
381 #if @GNULIB_MBSLEN@
382 /* Return the number of multibyte characters in the character string STRING.
383    This considers multibyte characters, unlike strlen, which counts bytes.  */
384 extern size_t mbslen (const char *string);
385 #endif
386
387 #if @GNULIB_MBSNLEN@
388 /* Return the number of multibyte characters in the character string starting
389    at STRING and ending at STRING + LEN.  */
390 extern size_t mbsnlen (const char *string, size_t len);
391 #endif
392
393 #if @GNULIB_MBSCHR@
394 /* Locate the first single-byte character C in the character string STRING,
395    and return a pointer to it.  Return NULL if C is not found in STRING.
396    Unlike strchr(), this function works correctly in multibyte locales with
397    encodings such as GB18030.  */
398 # define mbschr rpl_mbschr /* avoid collision with HP-UX function */
399 extern char * mbschr (const char *string, int c);
400 #endif
401
402 #if @GNULIB_MBSRCHR@
403 /* Locate the last single-byte character C in the character string STRING,
404    and return a pointer to it.  Return NULL if C is not found in STRING.
405    Unlike strrchr(), this function works correctly in multibyte locales with
406    encodings such as GB18030.  */
407 # define mbsrchr rpl_mbsrchr /* avoid collision with HP-UX function */
408 extern char * mbsrchr (const char *string, int c);
409 #endif
410
411 #if @GNULIB_MBSSTR@
412 /* Find the first occurrence of the character string NEEDLE in the character
413    string HAYSTACK.  Return NULL if NEEDLE is not found in HAYSTACK.
414    Unlike strstr(), this function works correctly in multibyte locales with
415    encodings different from UTF-8.  */
416 extern char * mbsstr (const char *haystack, const char *needle);
417 #endif
418
419 #if @GNULIB_MBSCASECMP@
420 /* Compare the character strings S1 and S2, ignoring case, returning less than,
421    equal to or greater than zero if S1 is lexicographically less than, equal to
422    or greater than S2.
423    Note: This function may, in multibyte locales, return 0 for strings of
424    different lengths!
425    Unlike strcasecmp(), this function works correctly in multibyte locales.  */
426 extern int mbscasecmp (const char *s1, const char *s2);
427 #endif
428
429 #if @GNULIB_MBSNCASECMP@
430 /* Compare the initial segment of the character string S1 consisting of at most
431    N characters with the initial segment of the character string S2 consisting
432    of at most N characters, ignoring case, returning less than, equal to or
433    greater than zero if the initial segment of S1 is lexicographically less
434    than, equal to or greater than the initial segment of S2.
435    Note: This function may, in multibyte locales, return 0 for initial segments
436    of different lengths!
437    Unlike strncasecmp(), this function works correctly in multibyte locales.
438    But beware that N is not a byte count but a character count!  */
439 extern int mbsncasecmp (const char *s1, const char *s2, size_t n);
440 #endif
441
442 #if @GNULIB_MBSPCASECMP@
443 /* Compare the initial segment of the character string STRING consisting of
444    at most mbslen (PREFIX) characters with the character string PREFIX,
445    ignoring case, returning less than, equal to or greater than zero if this
446    initial segment is lexicographically less than, equal to or greater than
447    PREFIX.
448    Note: This function may, in multibyte locales, return 0 if STRING is of
449    smaller length than PREFIX!
450    Unlike strncasecmp(), this function works correctly in multibyte
451    locales.  */
452 extern char * mbspcasecmp (const char *string, const char *prefix);
453 #endif
454
455 #if @GNULIB_MBSCASESTR@
456 /* Find the first occurrence of the character string NEEDLE in the character
457    string HAYSTACK, using case-insensitive comparison.
458    Note: This function may, in multibyte locales, return success even if
459    strlen (haystack) < strlen (needle) !
460    Unlike strcasestr(), this function works correctly in multibyte locales.  */
461 extern char * mbscasestr (const char *haystack, const char *needle);
462 #endif
463
464 #if @GNULIB_MBSCSPN@
465 /* Find the first occurrence in the character string STRING of any character
466    in the character string ACCEPT.  Return the number of bytes from the
467    beginning of the string to this occurrence, or to the end of the string
468    if none exists.
469    Unlike strcspn(), this function works correctly in multibyte locales.  */
470 extern size_t mbscspn (const char *string, const char *accept);
471 #endif
472
473 #if @GNULIB_MBSPBRK@
474 /* Find the first occurrence in the character string STRING of any character
475    in the character string ACCEPT.  Return the pointer to it, or NULL if none
476    exists.
477    Unlike strpbrk(), this function works correctly in multibyte locales.  */
478 # define mbspbrk rpl_mbspbrk /* avoid collision with HP-UX function */
479 extern char * mbspbrk (const char *string, const char *accept);
480 #endif
481
482 #if @GNULIB_MBSSPN@
483 /* Find the first occurrence in the character string STRING of any character
484    not in the character string REJECT.  Return the number of bytes from the
485    beginning of the string to this occurrence, or to the end of the string
486    if none exists.
487    Unlike strspn(), this function works correctly in multibyte locales.  */
488 extern size_t mbsspn (const char *string, const char *reject);
489 #endif
490
491 #if @GNULIB_MBSSEP@
492 /* Search the next delimiter (multibyte character listed in the character
493    string DELIM) starting at the character string *STRINGP.
494    If one is found, overwrite it with a NUL, and advance *STRINGP to point
495    to the next multibyte character after it.  Otherwise, set *STRINGP to NULL.
496    If *STRINGP was already NULL, nothing happens.
497    Return the old value of *STRINGP.
498
499    This is a variant of mbstok_r() that supports empty fields.
500
501    Caveat: It modifies the original string.
502    Caveat: These functions cannot be used on constant strings.
503    Caveat: The identity of the delimiting character is lost.
504
505    See also mbstok_r().  */
506 extern char * mbssep (char **stringp, const char *delim);
507 #endif
508
509 #if @GNULIB_MBSTOK_R@
510 /* Parse the character string STRING into tokens separated by characters in
511    the character string DELIM.
512    If STRING is NULL, the saved pointer in SAVE_PTR is used as
513    the next starting point.  For example:
514         char s[] = "-abc-=-def";
515         char *sp;
516         x = mbstok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
517         x = mbstok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
518         x = mbstok_r(NULL, "=", &sp);   // x = NULL
519                 // s = "abc\0-def\0"
520
521    Caveat: It modifies the original string.
522    Caveat: These functions cannot be used on constant strings.
523    Caveat: The identity of the delimiting character is lost.
524
525    See also mbssep().  */
526 extern char * mbstok_r (char *string, const char *delim, char **save_ptr);
527 #endif
528
529 /* Map any int, typically from errno, into an error message.  */
530 #if @GNULIB_STRERROR@
531 # if @REPLACE_STRERROR@
532 #  undef strerror
533 #  define strerror rpl_strerror
534 extern char *strerror (int);
535 # endif
536 #elif defined GNULIB_POSIXCHECK
537 # undef strerror
538 # define strerror(e) \
539     (GL_LINK_WARNING ("strerror is unportable - " \
540                       "use gnulib module strerror to guarantee non-NULL result"), \
541      strerror (e))
542 #endif
543
544 #if @GNULIB_STRSIGNAL@
545 # if @REPLACE_STRSIGNAL@
546 #  define strsignal rpl_strsignal
547 # endif
548 # if ! @HAVE_DECL_STRSIGNAL@ || @REPLACE_STRSIGNAL@
549 extern char *strsignal (int __sig);
550 # endif
551 #elif defined GNULIB_POSIXCHECK
552 # undef strsignal
553 # define strsignal(a) \
554     (GL_LINK_WARNING ("strsignal is unportable - " \
555                       "use gnulib module strsignal for portability"), \
556      strsignal (a))
557 #endif
558
559
560 #ifdef __cplusplus
561 }
562 #endif
563
564 #endif /* _GL_STRING_H */
565 #endif /* _GL_STRING_H */