1 /* Copyright (C) 1991-1993,1995-2004,2007,2009 Free Software Foundation, Inc.
2 This file is part of the GNU C Library.
3
4 The GNU C Library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 The GNU C Library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public
15 License along with the GNU C Library; if not, see
16 <http://www.gnu.org/licenses/>. */
17
18 /*
19 * ISO C99 Standard: 7.21 String handling <string.h>
20 */
21
22 #ifndef _STRING_H
23 #define _STRING_H 1
24
25 #include <features.h>
26
27 __BEGIN_DECLS
28
29 /* Get size_t and NULL from <stddef.h>. */
30 #define __need_size_t
31 #define __need_NULL
32 #include <stddef.h>
33
34
35 __BEGIN_NAMESPACE_STD
36 /* Copy N bytes of SRC to DEST. */
37 extern void *memcpy (void *__restrict __dest,
38 const void *__restrict __src, size_t __n)
39 __THROW __nonnull ((1, 2));
40 libc_hidden_proto(memcpy)
41 /* Copy N bytes of SRC to DEST, guaranteeing
42 correct behavior for overlapping strings. */
43 extern void *memmove (void *__dest, const void *__src, size_t __n)
44 __THROW __nonnull ((1, 2));
45 libc_hidden_proto(memmove)
46 __END_NAMESPACE_STD
47
48 /* Copy no more than N bytes of SRC to DEST, stopping when C is found.
49 Return the position in DEST one byte past where C was copied,
50 or NULL if C was not found in the first N bytes of SRC. */
51 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN
52 extern void *memccpy (void *__restrict __dest, const void *__restrict __src,
53 int __c, size_t __n)
54 __THROW __nonnull ((1, 2));
55 libc_hidden_proto(memccpy)
56 #endif /* SVID. */
57
58
59 __BEGIN_NAMESPACE_STD
60 /* Set N bytes of S to C. */
61 extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
62 libc_hidden_proto(memset)
63
64 /* Compare N bytes of S1 and S2. */
65 extern int memcmp (const void *__s1, const void *__s2, size_t __n)
66 __THROW __attribute_pure__ __nonnull ((1, 2));
67 libc_hidden_proto(memcmp)
68
69 /* Search N bytes of S for C. */
70 extern void *memchr (const void *__s, int __c, size_t __n)
71 __THROW __attribute_pure__ __nonnull ((1));
72 libc_hidden_proto(memchr)
73 __END_NAMESPACE_STD
74
75 #ifdef __USE_GNU
76 /* Search in S for C. This is similar to `memchr' but there is no
77 length limit. */
78 extern void *rawmemchr (const void *__s, int __c)
79 __THROW __attribute_pure__ __nonnull ((1));
80 libc_hidden_proto(rawmemchr)
81
82 /* Search N bytes of S for the final occurrence of C. */
83 extern void *memrchr (const void *__s, int __c, size_t __n)
84 __THROW __attribute_pure__ __nonnull ((1));
85 libc_hidden_proto(memrchr)
86 #endif
87
88
89 __BEGIN_NAMESPACE_STD
90 /* Copy SRC to DEST. */
91 extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
92 __THROW __nonnull ((1, 2));
93 libc_hidden_proto(strcpy)
94 /* Copy no more than N characters of SRC to DEST. */
95 extern char *strncpy (char *__restrict __dest,
96 const char *__restrict __src, size_t __n)
97 __THROW __nonnull ((1, 2));
98 libc_hidden_proto(strncpy)
99
100 /* Append SRC onto DEST. */
101 extern char *strcat (char *__restrict __dest, const char *__restrict __src)
102 __THROW __nonnull ((1, 2));
103 libc_hidden_proto(strcat)
104 /* Append no more than N characters from SRC onto DEST. */
105 extern char *strncat (char *__restrict __dest, const char *__restrict __src,
106 size_t __n) __THROW __nonnull ((1, 2));
107 libc_hidden_proto(strncat)
108
109 /* Compare S1 and S2. */
110 extern int strcmp (const char *__s1, const char *__s2)
111 __THROW __attribute_pure__ __nonnull ((1, 2));
112 libc_hidden_proto(strcmp)
113 /* Compare N characters of S1 and S2. */
114 extern int strncmp (const char *__s1, const char *__s2, size_t __n)
115 __THROW __attribute_pure__ __nonnull ((1, 2));
116 libc_hidden_proto(strncmp)
117
118 /* Compare the collated forms of S1 and S2. */
119 extern int strcoll (const char *__s1, const char *__s2)
120 __THROW __attribute_pure__ __nonnull ((1, 2));
121 libc_hidden_proto(strcoll)
122 /* Put a transformation of SRC into no more than N bytes of DEST. */
123 extern size_t strxfrm (char *__restrict __dest,
124 const char *__restrict __src, size_t __n)
125 __THROW __nonnull ((2));
126 __END_NAMESPACE_STD
127
128 #if defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__
129 /* The following functions are equivalent to the both above but they
130 take the locale they use for the collation as an extra argument.
131 This is not standardsized but something like will come. */
132 # include <xlocale.h>
133
134 /* Compare the collated forms of S1 and S2 using rules from L. */
135 extern int strcoll_l (const char *__s1, const char *__s2, __locale_t __l)
136 __THROW __attribute_pure__ __nonnull ((1, 2, 3));
137 libc_hidden_proto(strcoll_l)
138 /* Put a transformation of SRC into no more than N bytes of DEST. */
139 extern size_t strxfrm_l (char *__dest, const char *__src, size_t __n,
140 __locale_t __l) __THROW __nonnull ((2, 4));
141 libc_hidden_proto(strxfrm_l)
142 #endif
143
144 #if defined __USE_SVID || defined __USE_BSD || \
145 defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K8
146 /* Duplicate S, returning an identical malloc'd string. */
147 extern char *strdup (const char *__s)
148 __THROW __attribute_malloc__ __nonnull ((1));
149 libc_hidden_proto(strdup)
150 #endif
151
152 /* Return a malloc'd copy of at most N bytes of STRING. The
153 resultant string is terminated even if no null terminator
154 appears before STRING[N]. */
155 #if defined __USE_XOPEN2K8
156 extern char *strndup (const char *__string, size_t __n)
157 __THROW __attribute_malloc__ __nonnull ((1));
158 libc_hidden_proto(strndup)
159 #endif
160
161 #if defined __USE_GNU && defined __GNUC__
162 /* Duplicate S, returning an identical alloca'd string. */
163 # define strdupa(s) \
164 (__extension__ \
165 ({ \
166 const char *__old = (s); \
167 size_t __len = strlen (__old) + 1; \
168 char *__new = (char *) __builtin_alloca (__len); \
169 (char *) memcpy (__new, __old, __len); \
170 }))
171
172 /* Return an alloca'd copy of at most N bytes of string. */
173 # define strndupa(s, n) \
174 (__extension__ \
175 ({ \
176 const char *__old = (s); \
177 size_t __len = strnlen (__old, (n)); \
178 char *__new = (char *) __builtin_alloca (__len + 1); \
179 __new[__len] = '\0'; \
180 (char *) memcpy (__new, __old, __len); \
181 }))
182 #endif
183
184 __BEGIN_NAMESPACE_STD
185 /* Find the first occurrence of C in S. */
186 extern char *strchr (const char *__s, int __c)
187 __THROW __attribute_pure__ __nonnull ((1));
188 libc_hidden_proto(strchr)
189 /* Find the last occurrence of C in S. */
190 extern char *strrchr (const char *__s, int __c)
191 __THROW __attribute_pure__ __nonnull ((1));
192 libc_hidden_proto(strrchr)
193 __END_NAMESPACE_STD
194
195 #ifdef __USE_GNU
196 /* This function is similar to `strchr'. But it returns a pointer to
197 the closing NUL byte in case C is not found in S. */
198 extern char *strchrnul (const char *__s, int __c)
199 __THROW __attribute_pure__ __nonnull ((1));
200 libc_hidden_proto(strchrnul)
201 #endif
202
203 __BEGIN_NAMESPACE_STD
204 /* Return the length of the initial segment of S which
205 consists entirely of characters not in REJECT. */
206 extern size_t strcspn (const char *__s, const char *__reject)
207 __THROW __attribute_pure__ __nonnull ((1, 2));
208 libc_hidden_proto(strcspn)
209 /* Return the length of the initial segment of S which
210 consists entirely of characters in ACCEPT. */
211 extern size_t strspn (const char *__s, const char *__accept)
212 __THROW __attribute_pure__ __nonnull ((1, 2));
213 libc_hidden_proto(strspn)
214 /* Find the first occurrence in S of any character in ACCEPT. */
215 extern char *strpbrk (const char *__s, const char *__accept)
216 __THROW __attribute_pure__ __nonnull ((1, 2));
217 libc_hidden_proto(strpbrk)
218 /* Find the first occurrence of NEEDLE in HAYSTACK. */
219 extern char *strstr (const char *__haystack, const char *__needle)
220 __THROW __attribute_pure__ __nonnull ((1, 2));
221 libc_hidden_proto(strstr)
222
223
224 /* Divide S into tokens separated by characters in DELIM. */
225 extern char *strtok (char *__restrict __s, const char *__restrict __delim)
226 __THROW __nonnull ((2));
227 libc_hidden_proto(strtok)
228 __END_NAMESPACE_STD
229
230 /* Divide S into tokens separated by characters in DELIM. Information
231 passed between calls are stored in SAVE_PTR. */
232 #if 0 /* uClibc: disabled */
233 extern char *__strtok_r (char *__restrict __s,
234 const char *__restrict __delim,
235 char **__restrict __save_ptr)
236 __THROW __nonnull ((2, 3));
237 #endif
238 #if defined __USE_POSIX || defined __USE_MISC
239 extern char *strtok_r (char *__restrict __s, const char *__restrict __delim,
240 char **__restrict __save_ptr)
241 __THROW __nonnull ((2, 3));
242 libc_hidden_proto(strtok_r)
243 #endif
244
245 #ifdef __USE_GNU
246 /* Similar to `strstr' but this function ignores the case of both strings. */
247 extern char *strcasestr (const char *__haystack, const char *__needle)
248 __THROW __attribute_pure__ __nonnull ((1, 2));
249 libc_hidden_proto(strcasestr)
250 #endif
251
252 #ifdef __USE_GNU
253 /* Find the first occurrence of NEEDLE in HAYSTACK.
254 NEEDLE is NEEDLELEN bytes long;
255 HAYSTACK is HAYSTACKLEN bytes long. */
256 extern void *memmem (const void *__haystack, size_t __haystacklen,
257 const void *__needle, size_t __needlelen)
258 __THROW __attribute_pure__ __nonnull ((1, 3));
259
260 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
261 last written byte. */
262 #if __GNUC_PREREQ (3, 4)
263 # define __mempcpy(dest, src, n) __builtin_mempcpy(dest, src, n)
264 #else /* uClibc: disabled */
265 extern void *__mempcpy (void *__restrict __dest,
266 const void *__restrict __src, size_t __n)
267 __THROW __nonnull ((1, 2));
268 #endif
269 extern void *mempcpy (void *__restrict __dest,
270 const void *__restrict __src, size_t __n)
271 __THROW __nonnull ((1, 2));
272 libc_hidden_proto(mempcpy)
273 #endif
274
275
276 __BEGIN_NAMESPACE_STD
277 /* Return the length of S. */
278 extern size_t strlen (const char *__s)
279 __THROW __attribute_pure__ __nonnull ((1));
280 libc_hidden_proto(strlen)
281 __END_NAMESPACE_STD
282
283 #ifdef __USE_XOPEN2K8
284 /* Find the length of STRING, but scan at most MAXLEN characters.
285 If no '\0' terminator is found in that many characters, return MAXLEN. */
286 extern size_t strnlen (const char *__string, size_t __maxlen)
287 __THROW __attribute_pure__ __nonnull ((1));
288 libc_hidden_proto(strnlen)
289 #endif
290
291
292 __BEGIN_NAMESPACE_STD
293 /* Return a string describing the meaning of the `errno' code in ERRNUM. */
294 extern char *strerror (int __errnum) __THROW;
295 libc_hidden_proto(strerror)
296 __END_NAMESPACE_STD
297 #if defined __USE_XOPEN2K || defined __USE_MISC
298 /* Reentrant version of `strerror'.
299 There are 2 flavors of `strerror_r', GNU which returns the string
300 and may or may not use the supplied temporary buffer and POSIX one
301 which fills the string into the buffer.
302 To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
303 without -D_GNU_SOURCE is needed, otherwise the GNU version is
304 preferred. */
305 # if defined __USE_XOPEN2K && !defined __USE_GNU
306 /* Fill BUF with a string describing the meaning of the `errno' code in
307 ERRNUM. */
308 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
309 __THROW __nonnull ((2));
310 libc_hidden_proto(__xpg_strerror_r)
311 # ifdef __REDIRECT_NTH
312 extern int __REDIRECT_NTH (strerror_r,
313 (int __errnum, char *__buf, size_t __buflen),
314 __xpg_strerror_r) __nonnull ((2));
315 # else
316 # define strerror_r __xpg_strerror_r
317 # endif
318 # else
319 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
320 used. */
321 extern char *__glibc_strerror_r (int __errnum, char *__buf, size_t __buflen)
322 __THROW __nonnull ((2));
323 libc_hidden_proto(__glibc_strerror_r)
324 # ifdef __REDIRECT_NTH
325 extern char * __REDIRECT_NTH (strerror_r,
326 (int __errnum, char *__buf, size_t __buflen),
327 __glibc_strerror_r) __nonnull ((2));
328 # else
329 # define strerror_r __glibc_strerror_r
330 # endif
331 # endif
332 #endif
333
334 #if 0 /*defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__*/
335 /* Translate error number to string according to the locale L. */
336 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
337 #endif
338
339
340 /* We define this function always since `bzero' is sometimes needed when
341 the namespace rules does not allow this. */
342 #if 0 /* uClibc: disabled */
343 extern void __bzero (void *__s, size_t __n) __THROW __nonnull ((1));
344 #endif
345
346 #ifdef __USE_BSD
347 extern void explicit_bzero (void *__d, size_t __n);
348 # ifdef __UCLIBC_SUSV3_LEGACY__
349 /* Copy N bytes of SRC to DEST (like memmove, but args reversed). */
350 extern void bcopy (const void *__src, void *__dest, size_t __n)
351 __THROW __nonnull ((1, 2));
352
353 /* Set N bytes of S to 0. */
354 extern void bzero (void *__s, size_t __n) __THROW __nonnull ((1));
355
356 /* Compare N bytes of S1 and S2 (same as memcmp). */
357 extern int bcmp (const void *__s1, const void *__s2, size_t __n)
358 __THROW __attribute_pure__ __nonnull ((1, 2));
359
360 /* Find the first occurrence of C in S (same as strchr). */
361 extern char *index (const char *__s, int __c)
362 __THROW __attribute_pure__ __nonnull ((1));
363
364 /* Find the last occurrence of C in S (same as strrchr). */
365 extern char *rindex (const char *__s, int __c)
366 __THROW __attribute_pure__ __nonnull ((1));
367 # elif defined(__UCLIBC_SUSV3_LEGACY_MACROS__) && !defined(_STRINGS_H)
368 /* bcopy/bzero/bcmp/index/rindex are marked LEGACY in SuSv3.
369 * They are replaced as proposed by SuSv3. Don't sync this part
370 * with glibc and keep it in sync with strings.h. */
371
372 /* Copy N bytes of SRC to DEST (like memmove, but args reversed). */
bcopy(__const void * __src,void * __dest,size_t __n)373 static __inline__ void bcopy (__const void *__src, void *__dest, size_t __n)
374 {
375 memmove(__dest, __src, __n);
376 }
377
378 /* Set N bytes of S to 0. */
bzero(void * __s,size_t __n)379 static __inline__ void bzero (void *__s, size_t __n)
380 {
381 memset(__s, 0, __n);
382 }
383
384 /* Compare N bytes of S1 and S2 (same as memcmp). */
bcmp(__const void * __s1,__const void * __s2,size_t __n)385 static __inline__ int bcmp (__const void *__s1, __const void *__s2, size_t __n)
386 {
387 return memcmp(__s1, __s2, __n);
388 }
389
390 /* Find the first occurrence of C in S (same as strchr). */
index(__const char * __s,int __c)391 static __inline__ char *index (__const char *__s, int __c)
392 {
393 return strchr(__s, __c);
394 }
395
396 /* Find the last occurrence of C in S (same as strrchr). */
rindex(__const char * __s,int __c)397 static __inline__ char *rindex (__const char *__s, int __c)
398 {
399 return strrchr(__s, __c);
400 }
401 # endif
402
403 /* Return the position of the first bit set in I, or 0 if none are set.
404 The least-significant bit is position 1, the most-significant 32. */
405 extern int ffs (int __i) __THROW __attribute__ ((__const__));
406 libc_hidden_proto(ffs)
407
408 /* The following two functions are non-standard but necessary for non-32 bit
409 platforms. */
410 #ifdef __USE_GNU
411 extern int ffsl (long int __l) __THROW __attribute__ ((__const__));
412 # ifdef __GNUC__
413 __extension__ extern int ffsll (long long int __ll)
414 __THROW __attribute__ ((__const__));
415 # endif
416 # endif
417
418 /* Compare S1 and S2, ignoring case. */
419 extern int strcasecmp (const char *__s1, const char *__s2)
420 __THROW __attribute_pure__ __nonnull ((1, 2));
421 libc_hidden_proto(strcasecmp)
422
423 /* Compare no more than N chars of S1 and S2, ignoring case. */
424 extern int strncasecmp (const char *__s1, const char *__s2, size_t __n)
425 __THROW __attribute_pure__ __nonnull ((1, 2));
426 libc_hidden_proto(strncasecmp)
427 #endif /* Use BSD. */
428
429 #if defined __USE_XOPEN2K8 && defined __UCLIBC_HAS_XLOCALE__
430 /* Again versions of a few functions which use the given locale instead
431 of the global one. */
432 extern int strcasecmp_l (const char *__s1, const char *__s2,
433 __locale_t __loc)
434 __THROW __attribute_pure__ __nonnull ((1, 2, 3));
435 libc_hidden_proto(strcasecmp_l)
436
437 extern int strncasecmp_l (const char *__s1, const char *__s2,
438 size_t __n, __locale_t __loc)
439 __THROW __attribute_pure__ __nonnull ((1, 2, 4));
440 libc_hidden_proto(strncasecmp_l)
441 #endif
442
443 #ifdef __USE_BSD
444 /* Return the next DELIM-delimited token from *STRINGP,
445 terminating it with a '\0', and update *STRINGP to point past it. */
446 extern char *strsep (char **__restrict __stringp,
447 const char *__restrict __delim)
448 __THROW __nonnull ((1, 2));
449 libc_hidden_proto(strsep)
450 #endif
451
452 #ifdef __USE_XOPEN2K8
453 /* Return a string describing the meaning of the signal number in SIG. */
454 extern char *strsignal (int __sig) __THROW;
455 libc_hidden_proto(strsignal)
456
457 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST. */
458 # if 0 /* uClibc: disabled */
459 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
460 __THROW __nonnull ((1, 2));
461 # endif
462 extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
463 __THROW __nonnull ((1, 2));
464 libc_hidden_proto(stpcpy)
465
466 /* Copy no more than N characters of SRC to DEST, returning the address of
467 the last character written into DEST. */
468 # if 0 /* uClibc: disabled */
469 extern char *__stpncpy (char *__restrict __dest,
470 const char *__restrict __src, size_t __n)
471 __THROW __nonnull ((1, 2));
472 # endif
473 extern char *stpncpy (char *__restrict __dest,
474 const char *__restrict __src, size_t __n)
475 __THROW __nonnull ((1, 2));
476 #endif
477
478 #ifdef __USE_GNU
479 /* Compare S1 and S2 as strings holding name & indices/version numbers. */
480 extern int strverscmp (const char *__s1, const char *__s2)
481 __THROW __attribute_pure__ __nonnull ((1, 2));
482 libc_hidden_proto(strverscmp)
483
484 # if 0 /* uClibc does not support strfry or memfrob. */
485 /* Sautee STRING briskly. */
486 extern char *strfry (char *__string) __THROW __nonnull ((1));
487
488 /* Frobnicate N bytes of S. */
489 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
490 # endif
491
492 # ifndef basename
493 /* Return the file name within directory of FILENAME. We don't
494 declare the function if the `basename' macro is available (defined
495 in <libgen.h>) which makes the XPG version of this function
496 available. */
497 extern char *basename (const char *__filename) __THROW __nonnull ((1));
498 # endif
499 #endif /* __USE_GNU */
500
501
502 #ifdef __USE_BSD
503 /* Two OpenBSD extension functions. */
504 extern size_t strlcat(char *__restrict dst, const char *__restrict src,
505 size_t n) __THROW __nonnull ((1, 2));
506 libc_hidden_proto(strlcat)
507 extern size_t strlcpy(char *__restrict dst, const char *__restrict src,
508 size_t n) __THROW __nonnull ((1, 2));
509 libc_hidden_proto(strlcpy)
510 #endif
511
512 __END_DECLS
513
514
515 #if defined(_LIBC) && defined(__UCLIBC_HAS_STRING_ARCH_OPT__)
516 # if defined __i386__
517 # include <../libc/string/i386/string.h>
518 # endif
519 #endif
520
521 #endif /* string.h */
522