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. */
43 extern 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. */
47 extern 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)
54 extern 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. */
61 extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
62
63 /* Compare N bytes of S1 and S2. */
64 extern 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
69 extern "C++"
70 {
71 extern void *memchr (void *__s, int __c, size_t __n)
72 __THROW __asm ("memchr") __attribute_pure__ __nonnull ((1));
73 extern 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 *
memchr(void * __s,int __c,size_t __n)78 memchr (void *__s, int __c, size_t __n) __THROW
79 {
80 return __builtin_memchr (__s, __c, __n);
81 }
82
83 __extern_always_inline const void *
memchr(const void * __s,int __c,size_t __n)84 memchr (const void *__s, int __c, size_t __n) __THROW
85 {
86 return __builtin_memchr (__s, __c, __n);
87 }
88 # endif
89 }
90 #else
91 extern 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
99 extern "C++" void *rawmemchr (void *__s, int __c)
100 __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
101 extern "C++" const void *rawmemchr (const void *__s, int __c)
102 __THROW __asm ("rawmemchr") __attribute_pure__ __nonnull ((1));
103 # else
104 extern 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
110 extern "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));
113 extern "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
117 extern 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. */
125 extern 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. */
128 extern char *strncpy (char *__restrict __dest,
129 const char *__restrict __src, size_t __n)
130 __THROW __nonnull ((1, 2));
131
132 /* Append SRC onto DEST. */
133 extern 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. */
136 extern char *strncat (char *__restrict __dest, const char *__restrict __src,
137 size_t __n) __THROW __nonnull ((1, 2));
138
139 /* Compare S1 and S2. */
140 extern int strcmp (const char *__s1, const char *__s2)
141 __THROW __attribute_pure__ __nonnull ((1, 2));
142 /* Compare N characters of S1 and S2. */
143 extern 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. */
147 extern 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. */
150 extern 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. */
159 extern 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. */
163 extern 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. */
171 extern 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)
179 extern 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
208 extern "C++"
209 {
210 extern char *strchr (char *__s, int __c)
211 __THROW __asm ("strchr") __attribute_pure__ __nonnull ((1));
212 extern 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 *
strchr(char * __s,int __c)217 strchr (char *__s, int __c) __THROW
218 {
219 return __builtin_strchr (__s, __c);
220 }
221
222 __extern_always_inline const char *
strchr(const char * __s,int __c)223 strchr (const char *__s, int __c) __THROW
224 {
225 return __builtin_strchr (__s, __c);
226 }
227 # endif
228 }
229 #else
230 extern 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
235 extern "C++"
236 {
237 extern char *strrchr (char *__s, int __c)
238 __THROW __asm ("strrchr") __attribute_pure__ __nonnull ((1));
239 extern 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 *
strrchr(char * __s,int __c)244 strrchr (char *__s, int __c) __THROW
245 {
246 return __builtin_strrchr (__s, __c);
247 }
248
249 __extern_always_inline const char *
strrchr(const char * __s,int __c)250 strrchr (const char *__s, int __c) __THROW
251 {
252 return __builtin_strrchr (__s, __c);
253 }
254 # endif
255 }
256 #else
257 extern 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
265 extern "C++" char *strchrnul (char *__s, int __c)
266 __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
267 extern "C++" const char *strchrnul (const char *__s, int __c)
268 __THROW __asm ("strchrnul") __attribute_pure__ __nonnull ((1));
269 # else
270 extern 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. */
277 extern 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. */
281 extern 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
285 extern "C++"
286 {
287 extern char *strpbrk (char *__s, const char *__accept)
288 __THROW __asm ("strpbrk") __attribute_pure__ __nonnull ((1, 2));
289 extern 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 *
strpbrk(char * __s,const char * __accept)294 strpbrk (char *__s, const char *__accept) __THROW
295 {
296 return __builtin_strpbrk (__s, __accept);
297 }
298
299 __extern_always_inline const char *
strpbrk(const char * __s,const char * __accept)300 strpbrk (const char *__s, const char *__accept) __THROW
301 {
302 return __builtin_strpbrk (__s, __accept);
303 }
304 # endif
305 }
306 #else
307 extern 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
312 extern "C++"
313 {
314 extern char *strstr (char *__haystack, const char *__needle)
315 __THROW __asm ("strstr") __attribute_pure__ __nonnull ((1, 2));
316 extern 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 *
strstr(char * __haystack,const char * __needle)321 strstr (char *__haystack, const char *__needle) __THROW
322 {
323 return __builtin_strstr (__haystack, __needle);
324 }
325
326 __extern_always_inline const char *
strstr(const char * __haystack,const char * __needle)327 strstr (const char *__haystack, const char *__needle) __THROW
328 {
329 return __builtin_strstr (__haystack, __needle);
330 }
331 # endif
332 }
333 #else
334 extern 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. */
340 extern 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. */
345 extern 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
350 extern 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
358 extern "C++" char *strcasestr (char *__haystack, const char *__needle)
359 __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
360 extern "C++" const char *strcasestr (const char *__haystack,
361 const char *__needle)
362 __THROW __asm ("strcasestr") __attribute_pure__ __nonnull ((1, 2));
363 # else
364 extern 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. */
373 extern 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. */
381 extern void *__mempcpy (void *__restrict __dest,
382 const void *__restrict __src, size_t __n)
383 __THROW __nonnull ((1, 2));
384 extern 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. */
391 extern 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. */
397 extern 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. */
403 extern 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
416 extern 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
421 extern 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. */
428 extern 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. */
434 extern const char *strerrordesc_np (int __err) __THROW;
435 /* Return a string with the error name in ERR. */
436 extern 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. */
442 extern 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. */
450 extern 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. */
455 extern 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. */
462 extern char *strsignal (int __sig) __THROW;
463
464 # ifdef __USE_GNU
465 /* Return an abbreviation string for the signal number SIG. */
466 extern 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. */
469 extern const char *sigdescr_np (int __sig) __THROW;
470 # endif
471
472 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST. */
473 extern char *__stpcpy (char *__restrict __dest, const char *__restrict __src)
474 __THROW __nonnull ((1, 2));
475 extern 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. */
480 extern char *__stpncpy (char *__restrict __dest,
481 const char *__restrict __src, size_t __n)
482 __THROW __nonnull ((1, 2));
483 extern 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. */
490 extern int strverscmp (const char *__s1, const char *__s2)
491 __THROW __attribute_pure__ __nonnull ((1, 2));
492
493 /* Sautee STRING briskly. */
494 extern char *strfry (char *__string) __THROW __nonnull ((1));
495
496 /* Frobnicate N bytes of S. */
497 extern 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
506 extern "C++" char *basename (char *__filename)
507 __THROW __asm ("basename") __nonnull ((1));
508 extern "C++" const char *basename (const char *__filename)
509 __THROW __asm ("basename") __nonnull ((1));
510 # else
511 extern 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 */