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