1/* Copyright (C) 1991-2021 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 <https://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#define __GLIBC_INTERNAL_STARTING_HEADER_IMPLEMENTATION
26#include <bits/libc-header-start.h>
27
28__BEGIN_DECLS
29
30/* Get size_t and NULL from <stddef.h>. */
31#define __need_size_t
32#define __need_NULL
33#include <stddef.h>
34
35/* Tell the caller that we provide correct C++ prototypes. */
36#if defined __cplusplus && (__GNUC_PREREQ (4, 4) \
37 || __glibc_clang_prereq (3, 5))
38# define __CORRECT_ISO_CPP_STRING_H_PROTO
39#endif
40
41
42/* Copy N bytes of SRC to DEST. */
43extern void *memcpy (void *__restrict __dest, const void *__restrict __src,
44 size_t __n) __THROW __nonnull ((1, 2));
45/* Copy N bytes of SRC to DEST, guaranteeing
46 correct behavior for overlapping strings. */
47extern void *memmove (void *__dest, const void *__src, size_t __n)
48 __THROW __nonnull ((1, 2));
49
50/* Copy no more than N bytes of SRC to DEST, stopping when C is found.
51 Return the position in DEST one byte past where C was copied,
52 or NULL if C was not found in the first N bytes of SRC. */
53#if defined __USE_MISC || defined __USE_XOPEN || __GLIBC_USE (ISOC2X)
54extern void *memccpy (void *__restrict __dest, const void *__restrict __src,
55 int __c, size_t __n)
56 __THROW __nonnull ((1, 2)) __attr_access ((__write_only__, 1, 4));
57#endif /* Misc || X/Open. */
58
59
60/* Set N bytes of S to C. */
61extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
62
63/* Compare N bytes of S1 and S2. */
64extern int memcmp (const void *__s1, const void *__s2, size_t __n)
65 __THROW __attribute_pure__ __nonnull ((1, 2));
66
67/* Search N bytes of S for C. */
68#ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
69extern "C++"
70{
71extern void *memchr (void *__s, int __c, size_t __n)
72 __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
73extern const void *memchr (const void *__s, int __c, size_t __n)
74 __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
75
76# ifdef __OPTIMIZE__
77__extern_always_inline void *
78memchr (void *__s, int __c, size_t __n) __THROW
79{
80 return __builtin_memchr (__s, __c, __n);
81}
82
83__extern_always_inline const void *
84memchr (const void *__s, int __c, size_t __n) __THROW
85{
86 return __builtin_memchr (__s, __c, __n);
87}
88# endif
89}
90#else
91extern void *memchr (const void *__s, int __c, size_t __n)
92 __THROW __attribute_pure__ __nonnull ((1));
93#endif
94
95#ifdef __USE_GNU
96/* Search in S for C. This is similar to `memchr' but there is no
97 length limit. */
98# ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
99extern "C++" void *rawmemchr (void *__s, int __c)
100 __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
101extern "C++" const void *rawmemchr (const void *__s, int __c)
102 __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
103# else
104extern void *rawmemchr (const void *__s, int __c)
105 __THROW __attribute_pure__ __nonnull ((1));
106# endif
107
108/* Search N bytes of S for the final occurrence of C. */
109# ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
110extern "C++" void *memrchr (void *__s, int __c, size_t __n)
111 __THROW __asm ("memrchr") __attribute_pure__ __nonnull ((1))
112 __attr_access ((__read_only__, 1, 3));
113extern "C++" const void *memrchr (const void *__s, int __c, size_t __n)
114 __THROW __asm ("memrchr") __attribute_pure__ __nonnull ((1))
115 __attr_access ((__read_only__, 1, 3));
116# else
117extern void *memrchr (const void *__s, int __c, size_t __n)
118 __THROW __attribute_pure__ __nonnull ((1))
119 __attr_access ((__read_only__, 1, 3));
120# endif
121#endif
122
123
124/* Copy SRC to DEST. */
125extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
126 __THROW __nonnull ((1, 2));
127/* Copy no more than N characters of SRC to DEST. */
128extern char *strncpy (char *__restrict __dest,
129 const char *__restrict __src, size_t __n)
130 __THROW __nonnull ((1, 2));
131
132/* Append SRC onto DEST. */
133extern char *strcat (char *__restrict __dest, const char *__restrict __src)
134 __THROW __nonnull ((1, 2));
135/* Append no more than N characters from SRC onto DEST. */
136extern char *strncat (char *__restrict __dest, const char *__restrict __src,
137 size_t __n) __THROW __nonnull ((1, 2));
138
139/* Compare S1 and S2. */
140extern int strcmp (const char *__s1, const char *__s2)
141 __THROW __attribute_pure__ __nonnull ((1, 2));
142/* Compare N characters of S1 and S2. */
143extern int strncmp (const char *__s1, const char *__s2, size_t __n)
144 __THROW __attribute_pure__ __nonnull ((1, 2));
145
146/* Compare the collated forms of S1 and S2. */
147extern int strcoll (const char *__s1, const char *__s2)
148 __THROW __attribute_pure__ __nonnull ((1, 2));
149/* Put a transformation of SRC into no more than N bytes of DEST. */
150extern size_t strxfrm (char *__restrict __dest,
151 const char *__restrict __src, size_t __n)
152 __THROW __nonnull ((2)) __attr_access ((__write_only__, 1, 3));
153
154#ifdef __USE_XOPEN2K8
155/* POSIX.1-2008 extended locale interface (see locale.h). */
156# include <bits/types/locale_t.h>
157
158/* Compare the collated forms of S1 and S2, using sorting rules from L. */
159extern int strcoll_l (const char *__s1, const char *__s2, locale_t __l)
160 __THROW __attribute_pure__ __nonnull ((1, 2, 3));
161/* Put a transformation of SRC into no more than N bytes of DEST,
162 using sorting rules from L. */
163extern size_t strxfrm_l (char *__dest, const char *__src, size_t __n,
164 locale_t __l) __THROW __nonnull ((2, 4))
165 __attr_access ((__write_only__, 1, 3));
166#endif
167
168#if (defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K8 \
169 || __GLIBC_USE (LIB_EXT2) || __GLIBC_USE (ISOC2X))
170/* Duplicate S, returning an identical malloc'd string. */
171extern char *strdup (const char *__s)
172 __THROW __attribute_malloc__ __nonnull ((1));
173#endif
174
175/* Return a malloc'd copy of at most N bytes of STRING. The
176 resultant string is terminated even if no null terminator
177 appears before STRING[N]. */
178#if defined __USE_XOPEN2K8 || __GLIBC_USE (LIB_EXT2) || __GLIBC_USE (ISOC2X)
179extern char *strndup (const char *__string, size_t __n)
180 __THROW __attribute_malloc__ __nonnull ((1));
181#endif
182
183#if defined __USE_GNU && defined __GNUC__
184/* Duplicate S, returning an identical alloca'd string. */
185# define strdupa(s) \
186 (__extension__ \
187 ({ \
188 const char *__old = (s); \
189 size_t __len = strlen (__old) + 1; \
190 char *__new = (char *) __builtin_alloca (__len); \
191 (char *) memcpy (__new, __old, __len); \
192 }))
193
194/* Return an alloca'd copy of at most N bytes of string. */
195# define strndupa(s, n) \
196 (__extension__ \
197 ({ \
198 const char *__old = (s); \
199 size_t __len = strnlen (__old, (n)); \
200 char *__new = (char *) __builtin_alloca (__len + 1); \
201 __new[__len] = '\0'; \
202 (char *) memcpy (__new, __old, __len); \
203 }))
204#endif
205
206/* Find the first occurrence of C in S. */
207#ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
208extern "C++"
209{
210extern char *strchr (char *__s, int __c)
211 __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
212extern const char *strchr (const char *__s, int __c)
213 __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
214
215# ifdef __OPTIMIZE__
216__extern_always_inline char *
217strchr (char *__s, int __c) __THROW
218{
219 return __builtin_strchr (__s, __c);
220}
221
222__extern_always_inline const char *
223strchr (const char *__s, int __c) __THROW
224{
225 return __builtin_strchr (__s, __c);
226}
227# endif
228}
229#else
230extern char *strchr (const char *__s, int __c)
231 __THROW __attribute_pure__ __nonnull ((1));
232#endif
233/* Find the last occurrence of C in S. */
234#ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
235extern "C++"
236{
237extern char *strrchr (char *__s, int __c)
238 __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
239extern const char *strrchr (const char *__s, int __c)
240 __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
241
242# ifdef __OPTIMIZE__
243__extern_always_inline char *
244strrchr (char *__s, int __c) __THROW
245{
246 return __builtin_strrchr (__s, __c);
247}
248
249__extern_always_inline const char *
250strrchr (const char *__s, int __c) __THROW
251{
252 return __builtin_strrchr (__s, __c);
253}
254# endif
255}
256#else
257extern char *strrchr (const char *__s, int __c)
258 __THROW __attribute_pure__ __nonnull ((1));
259#endif
260
261#ifdef __USE_GNU
262/* This function is similar to `strchr'. But it returns a pointer to
263 the closing NUL byte in case C is not found in S. */
264# ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
265extern "C++" char *strchrnul (char *__s, int __c)
266 __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
267extern "C++" const char *strchrnul (const char *__s, int __c)
268 __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
269# else
270extern char *strchrnul (const char *__s, int __c)
271 __THROW __attribute_pure__ __nonnull ((1));
272# endif
273#endif
274
275/* Return the length of the initial segment of S which
276 consists entirely of characters not in REJECT. */
277extern size_t strcspn (const char *__s, const char *__reject)
278 __THROW __attribute_pure__ __nonnull ((1, 2));
279/* Return the length of the initial segment of S which
280 consists entirely of characters in ACCEPT. */
281extern size_t strspn (const char *__s, const char *__accept)
282 __THROW __attribute_pure__ __nonnull ((1, 2));
283/* Find the first occurrence in S of any character in ACCEPT. */
284#ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
285extern "C++"
286{
287extern char *strpbrk (char *__s, const char *__accept)
288 __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
289extern const char *strpbrk (const char *__s, const char *__accept)
290 __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
291
292# ifdef __OPTIMIZE__
293__extern_always_inline char *
294strpbrk (char *__s, const char *__accept) __THROW
295{
296 return __builtin_strpbrk (__s, __accept);
297}
298
299__extern_always_inline const char *
300strpbrk (const char *__s, const char *__accept) __THROW
301{
302 return __builtin_strpbrk (__s, __accept);
303}
304# endif
305}
306#else
307extern char *strpbrk (const char *__s, const char *__accept)
308 __THROW __attribute_pure__ __nonnull ((1, 2));
309#endif
310/* Find the first occurrence of NEEDLE in HAYSTACK. */
311#ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
312extern "C++"
313{
314extern char *strstr (char *__haystack, const char *__needle)
315 __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
316extern const char *strstr (const char *__haystack, const char *__needle)
317 __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
318
319# ifdef __OPTIMIZE__
320__extern_always_inline char *
321strstr (char *__haystack, const char *__needle) __THROW
322{
323 return __builtin_strstr (__haystack, __needle);
324}
325
326__extern_always_inline const char *
327strstr (const char *__haystack, const char *__needle) __THROW
328{
329 return __builtin_strstr (__haystack, __needle);
330}
331# endif
332}
333#else
334extern char *strstr (const char *__haystack, const char *__needle)
335 __THROW __attribute_pure__ __nonnull ((1, 2));
336#endif
337
338
339/* Divide S into tokens separated by characters in DELIM. */
340extern char *strtok (char *__restrict __s, const char *__restrict __delim)
341 __THROW __nonnull ((2));
342
343/* Divide S into tokens separated by characters in DELIM. Information
344 passed between calls are stored in SAVE_PTR. */
345extern char *__strtok_r (char *__restrict __s,
346 const char *__restrict __delim,
347 char **__restrict __save_ptr)
348 __THROW __nonnull ((2, 3));
349#ifdef __USE_POSIX
350extern char *strtok_r (char *__restrict __s, const char *__restrict __delim,
351 char **__restrict __save_ptr)
352 __THROW __nonnull ((2, 3));
353#endif
354
355#ifdef __USE_GNU
356/* Similar to `strstr' but this function ignores the case of both strings. */
357# ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
358extern "C++" char *strcasestr (char *__haystack, const char *__needle)
359 __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
360extern "C++" const char *strcasestr (const char *__haystack,
361 const char *__needle)
362 __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
363# else
364extern char *strcasestr (const char *__haystack, const char *__needle)
365 __THROW __attribute_pure__ __nonnull ((1, 2));
366# endif
367#endif
368
369#ifdef __USE_GNU
370/* Find the first occurrence of NEEDLE in HAYSTACK.
371 NEEDLE is NEEDLELEN bytes long;
372 HAYSTACK is HAYSTACKLEN bytes long. */
373extern void *memmem (const void *__haystack, size_t __haystacklen,
374 const void *__needle, size_t __needlelen)
375 __THROW __attribute_pure__ __nonnull ((1, 3))
376 __attr_access ((__read_only__, 1, 2))
377 __attr_access ((__read_only__, 3, 4));
378
379/* Copy N bytes of SRC to DEST, return pointer to bytes after the
380 last written byte. */
381extern void *__mempcpy (void *__restrict __dest,
382 const void *__restrict __src, size_t __n)
383 __THROW __nonnull ((1, 2));
384extern void *mempcpy (void *__restrict __dest,
385 const void *__restrict __src, size_t __n)
386 __THROW __nonnull ((1, 2));
387#endif
388
389
390/* Return the length of S. */
391extern size_t strlen (const char *__s)
392 __THROW __attribute_pure__ __nonnull ((1));
393
394#ifdef __USE_XOPEN2K8
395/* Find the length of STRING, but scan at most MAXLEN characters.
396 If no '\0' terminator is found in that many characters, return MAXLEN. */
397extern size_t strnlen (const char *__string, size_t __maxlen)
398 __THROW __attribute_pure__ __nonnull ((1));
399#endif
400
401
402/* Return a string describing the meaning of the `errno' code in ERRNUM. */
403extern char *strerror (int __errnum) __THROW;
404#ifdef __USE_XOPEN2K
405/* Reentrant version of `strerror'.
406 There are 2 flavors of `strerror_r', GNU which returns the string
407 and may or may not use the supplied temporary buffer and POSIX one
408 which fills the string into the buffer.
409 To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
410 without -D_GNU_SOURCE is needed, otherwise the GNU version is
411 preferred. */
412# if defined __USE_XOPEN2K && !defined __USE_GNU
413/* Fill BUF with a string describing the meaning of the `errno' code in
414 ERRNUM. */
415# ifdef __REDIRECT_NTH
416extern int __REDIRECT_NTH (strerror_r,
417 (int __errnum, char *__buf, size_t __buflen),
418 __xpg_strerror_r) __nonnull ((2))
419 __attr_access ((__write_only__, 2, 3));
420# else
421extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
422 __THROW __nonnull ((2)) __attr_access ((__write_only__, 2, 3));
423# define strerror_r __xpg_strerror_r
424# endif
425# else
426/* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
427 used. */
428extern char *strerror_r (int __errnum, char *__buf, size_t __buflen)
429 __THROW __nonnull ((2)) __wur __attr_access ((__write_only__, 2, 3));
430# endif
431
432# ifdef __USE_GNU
433/* Return a string describing the meaning of tthe error in ERR. */
434extern const char *strerrordesc_np (int __err) __THROW;
435/* Return a string with the error name in ERR. */
436extern const char *strerrorname_np (int __err) __THROW;
437# endif
438#endif
439
440#ifdef __USE_XOPEN2K8
441/* Translate error number to string according to the locale L. */
442extern char *strerror_l (int __errnum, locale_t __l) __THROW;
443#endif
444
445#ifdef __USE_MISC
446# include <strings.h>
447
448/* Set N bytes of S to 0. The compiler will not delete a call to this
449 function, even if S is dead after the call. */
450extern void explicit_bzero (void *__s, size_t __n) __THROW __nonnull ((1))
451 __attr_access ((__write_only__, 1, 2));
452
453/* Return the next DELIM-delimited token from *STRINGP,
454 terminating it with a '\0', and update *STRINGP to point past it. */
455extern char *strsep (char **__restrict __stringp,
456 const char *__restrict __delim)
457 __THROW __nonnull ((1, 2));
458#endif
459
460#ifdef __USE_XOPEN2K8
461/* Return a string describing the meaning of the signal number in SIG. */
462extern char *strsignal (int __sig) __THROW;
463
464# ifdef __USE_GNU
465/* Return an abbreviation string for the signal number SIG. */
466extern const char *sigabbrev_np (int __sig) __THROW;
467/* Return a string describing the meaning of the signal number in SIG,
468 the result is not translated. */
469extern const char *sigdescr_np (int __sig) __THROW;
470# endif
471
472/* Copy SRC to DEST, returning the address of the terminating '\0' in DEST. */
473extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
474 __THROW __nonnull ((1, 2));
475extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
476 __THROW __nonnull ((1, 2));
477
478/* Copy no more than N characters of SRC to DEST, returning the address of
479 the last character written into DEST. */
480extern char *__stpncpy (char *__restrict __dest,
481 const char *__restrict __src, size_t __n)
482 __THROW __nonnull ((1, 2));
483extern char *stpncpy (char *__restrict __dest,
484 const char *__restrict __src, size_t __n)
485 __THROW __nonnull ((1, 2));
486#endif
487
488#ifdef __USE_GNU
489/* Compare S1 and S2 as strings holding name & indices/version numbers. */
490extern int strverscmp (const char *__s1, const char *__s2)
491 __THROW __attribute_pure__ __nonnull ((1, 2));
492
493/* Sautee STRING briskly. */
494extern char *strfry (char *__string) __THROW __nonnull ((1));
495
496/* Frobnicate N bytes of S. */
497extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1))
498 __attr_access ((__write_only__, 1, 2));
499
500# ifndef basename
501/* Return the file name within directory of FILENAME. We don't
502 declare the function if the `basename' macro is available (defined
503 in <libgen.h>) which makes the XPG version of this function
504 available. */
505# ifdef __CORRECT_ISO_CPP_STRING_H_PROTO
506extern "C++" char *basename (char *__filename)
507 __THROW __asm ("basename") __nonnull ((1));
508extern "C++" const char *basename (const char *__filename)
509 __THROW __asm ("basename") __nonnull ((1));
510# else
511extern char *basename (const char *__filename) __THROW __nonnull ((1));
512# endif
513# endif
514#endif
515
516#if __GNUC_PREREQ (3,4)
517# if __USE_FORTIFY_LEVEL > 0 && defined __fortify_function
518/* Functions with security checks. */
519# include <bits/string_fortified.h>
520# endif
521#endif
522
523__END_DECLS
524
525#endif /* string.h */
526