[thirdparty/glibc.git] / malloc / malloc.h

/* Prototypes and definition for malloc implementation.
   Copyright (C) 1996-2025 Free Software Foundation, Inc.
   Copyright The GNU Toolchain Authors.
   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the GNU C Library; if not, see
   <https://www.gnu.org/licenses/>.  */

#ifndef _MALLOC_H
#define _MALLOC_H 1

#include <features.h>
#include <stddef.h>
#include <stdio.h>

#ifdef _LIBC
# define __MALLOC_HOOK_VOLATILE
# define __MALLOC_DEPRECATED
#else
# define __MALLOC_HOOK_VOLATILE volatile
# define __MALLOC_DEPRECATED __attribute_deprecated__
#endif


__BEGIN_DECLS

/* Allocate SIZE bytes of memory.  */
extern void *malloc (size_t __size) __THROW __attribute_malloc__
     __attribute_alloc_size__ ((1)) __wur;

/* Allocate NMEMB elements of SIZE bytes each, all initialized to 0.  */
extern void *calloc (size_t __nmemb, size_t __size)
__THROW __attribute_malloc__ __attribute_alloc_size__ ((1, 2)) __wur;

/* Re-allocate the previously allocated block in __ptr, making the new
   block SIZE bytes long.  */
/* __attribute_malloc__ is not used, because if realloc returns
   the same pointer that was passed to it, aliasing needs to be allowed
   between objects pointed by the old and new pointers.  */
extern void *realloc (void *__ptr, size_t __size)
__THROW __attribute_warn_unused_result__ __attribute_alloc_size__ ((2));

/* Re-allocate the previously allocated block in PTR, making the new
   block large enough for NMEMB elements of SIZE bytes each.  */
/* __attribute_malloc__ is not used, because if reallocarray returns
   the same pointer that was passed to it, aliasing needs to be allowed
   between objects pointed by the old and new pointers.  */
extern void *reallocarray (void *__ptr, size_t __nmemb, size_t __size)
  __THROW __attribute_warn_unused_result__ __attribute_alloc_size__ ((2, 3))
  __attr_dealloc_free;

/* Free a block allocated by `malloc', `realloc' or `calloc'.  */
extern void free (void *__ptr) __THROW;

/* Allocate SIZE bytes allocated to ALIGNMENT bytes.  */
extern void *memalign (size_t __alignment, size_t __size)
  __THROW __attribute_malloc__ __attribute_alloc_align__ ((1))
  __attribute_alloc_size__ ((2)) __wur __attr_dealloc_free;

/* Allocate SIZE bytes on a page boundary.  */
extern void *valloc (size_t __size) __THROW __attribute_malloc__
     __attribute_alloc_size__ ((1)) __wur __attr_dealloc_free;

/* Equivalent to valloc(minimum-page-that-holds(n)), that is, round up
   __size to nearest pagesize. */
extern void *pvalloc (size_t __size) __THROW __attribute_malloc__
  __wur __attr_dealloc_free;

/* SVID2/XPG mallinfo structure */

struct mallinfo
{
  int arena;    /* non-mmapped space allocated from system */
  int ordblks;  /* number of free chunks */
  int smblks;   /* number of fastbin blocks */
  int hblks;    /* number of mmapped regions */
  int hblkhd;   /* space in mmapped regions */
  int usmblks;  /* always 0, preserved for backwards compatibility */
  int fsmblks;  /* space available in freed fastbin blocks */
  int uordblks; /* total allocated space */
  int fordblks; /* total free space */
  int keepcost; /* top-most, releasable (via malloc_trim) space */
};

/* SVID2/XPG mallinfo2 structure which can handle allocations
   bigger than 4GB.  */

struct mallinfo2
{
  size_t arena;    /* non-mmapped space allocated from system */
  size_t ordblks;  /* number of free chunks */
  size_t smblks;   /* number of fastbin blocks */
  size_t hblks;    /* number of mmapped regions */
  size_t hblkhd;   /* space in mmapped regions */
  size_t usmblks;  /* always 0, preserved for backwards compatibility */
  size_t fsmblks;  /* space available in freed fastbin blocks */
  size_t uordblks; /* total allocated space */
  size_t fordblks; /* total free space */
  size_t keepcost; /* top-most, releasable (via malloc_trim) space */
};

/* Returns a copy of the updated current mallinfo. */
extern struct mallinfo mallinfo (void) __THROW __MALLOC_DEPRECATED;

/* Returns a copy of the updated current mallinfo. */
extern struct mallinfo2 mallinfo2 (void) __THROW;

/* SVID2/XPG mallopt options */
#ifndef M_MXFAST
# define M_MXFAST  1    /* maximum request size for "fastbins" */
#endif
#ifndef M_NLBLKS
# define M_NLBLKS  2    /* UNUSED in this malloc */
#endif
#ifndef M_GRAIN
# define M_GRAIN   3    /* UNUSED in this malloc */
#endif
#ifndef M_KEEP
# define M_KEEP    4    /* UNUSED in this malloc */
#endif

/* mallopt options that actually do something */
#define M_TRIM_THRESHOLD    -1
#define M_TOP_PAD           -2
#define M_MMAP_THRESHOLD    -3
#define M_MMAP_MAX          -4
#define M_CHECK_ACTION      -5
#define M_PERTURB           -6
#define M_ARENA_TEST        -7
#define M_ARENA_MAX         -8

/* General SVID/XPG interface to tunable parameters. */
extern int mallopt (int __param, int __val) __THROW;

/* Release all but __pad bytes of freed top-most memory back to the
   system. Return 1 if successful, else 0. */
extern int malloc_trim (size_t __pad) __THROW;

/* Report the number of usable allocated bytes associated with allocated
   chunk __ptr. */
extern size_t malloc_usable_size (void *__ptr) __THROW;

/* Prints brief summary statistics on stderr. */
extern void malloc_stats (void) __THROW;

/* Output information about state of allocator to stream FP.  */
extern int malloc_info (int __options, FILE *__fp) __THROW;

__END_DECLS
#endif /* malloc.h */
Commit	Line	Data
	1	/* Prototypes and definition for malloc implementation.
	2	Copyright (C) 1996-2025 Free Software Foundation, Inc.
	3	Copyright The GNU Toolchain Authors.
	4	This file is part of the GNU C Library.
	5
	6	The GNU C Library is free software; you can redistribute it and/or
	7	modify it under the terms of the GNU Lesser General Public
	8	License as published by the Free Software Foundation; either
	9	version 2.1 of the License, or (at your option) any later version.
	10
	11	The GNU C Library is distributed in the hope that it will be useful,
	12	but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	14	Lesser General Public License for more details.
	15
	16	You should have received a copy of the GNU Lesser General Public
	17	License along with the GNU C Library; if not, see
	18	<https://www.gnu.org/licenses/>. */
	19
	20	#ifndef _MALLOC_H
	21	#define _MALLOC_H 1
	22
	23	#include <features.h>
	24	#include <stddef.h>
	25	#include <stdio.h>
	26
	27	#ifdef _LIBC
	28	# define __MALLOC_HOOK_VOLATILE
	29	# define __MALLOC_DEPRECATED
	30	#else
	31	# define __MALLOC_HOOK_VOLATILE volatile
	32	# define __MALLOC_DEPRECATED __attribute_deprecated__
	33	#endif
	34
	35
	36	__BEGIN_DECLS
	37
	38	/* Allocate SIZE bytes of memory. */
	39	extern void *malloc (size_t __size) __THROW __attribute_malloc__
	40	__attribute_alloc_size__ ((1)) __wur;
	41
	42	/* Allocate NMEMB elements of SIZE bytes each, all initialized to 0. */
	43	extern void *calloc (size_t __nmemb, size_t __size)
	44	__THROW __attribute_malloc__ __attribute_alloc_size__ ((1, 2)) __wur;
	45
	46	/* Re-allocate the previously allocated block in __ptr, making the new
	47	block SIZE bytes long. */
	48	/* __attribute_malloc__ is not used, because if realloc returns
	49	the same pointer that was passed to it, aliasing needs to be allowed
	50	between objects pointed by the old and new pointers. */
	51	extern void realloc (void __ptr, size_t __size)
	52	__THROW __attribute_warn_unused_result__ __attribute_alloc_size__ ((2));
	53
	54	/* Re-allocate the previously allocated block in PTR, making the new
	55	block large enough for NMEMB elements of SIZE bytes each. */
	56	/* __attribute_malloc__ is not used, because if reallocarray returns
	57	the same pointer that was passed to it, aliasing needs to be allowed
	58	between objects pointed by the old and new pointers. */
	59	extern void reallocarray (void __ptr, size_t __nmemb, size_t __size)
	60	__THROW __attribute_warn_unused_result__ __attribute_alloc_size__ ((2, 3))
	61	__attr_dealloc_free;
	62
	63	/* Free a block allocated by `malloc', `realloc' or `calloc'. */
	64	extern void free (void *__ptr) __THROW;
	65
	66	/* Allocate SIZE bytes allocated to ALIGNMENT bytes. */
	67	extern void *memalign (size_t __alignment, size_t __size)
	68	__THROW __attribute_malloc__ __attribute_alloc_align__ ((1))
	69	__attribute_alloc_size__ ((2)) __wur __attr_dealloc_free;
	70
	71	/* Allocate SIZE bytes on a page boundary. */
	72	extern void *valloc (size_t __size) __THROW __attribute_malloc__
	73	__attribute_alloc_size__ ((1)) __wur __attr_dealloc_free;
	74
	75	/* Equivalent to valloc(minimum-page-that-holds(n)), that is, round up
	76	__size to nearest pagesize. */
	77	extern void *pvalloc (size_t __size) __THROW __attribute_malloc__
	78	__wur __attr_dealloc_free;
	79
	80	/* SVID2/XPG mallinfo structure */
	81
	82	struct mallinfo
	83	{
	84	int arena; /* non-mmapped space allocated from system */
	85	int ordblks; /* number of free chunks */
	86	int smblks; /* number of fastbin blocks */
	87	int hblks; /* number of mmapped regions */
	88	int hblkhd; /* space in mmapped regions */
	89	int usmblks; /* always 0, preserved for backwards compatibility */
	90	int fsmblks; /* space available in freed fastbin blocks */
	91	int uordblks; /* total allocated space */
	92	int fordblks; /* total free space */
	93	int keepcost; /* top-most, releasable (via malloc_trim) space */
	94	};
	95
	96	/* SVID2/XPG mallinfo2 structure which can handle allocations
	97	bigger than 4GB. */
	98
	99	struct mallinfo2
	100	{
	101	size_t arena; /* non-mmapped space allocated from system */
	102	size_t ordblks; /* number of free chunks */
	103	size_t smblks; /* number of fastbin blocks */
	104	size_t hblks; /* number of mmapped regions */
	105	size_t hblkhd; /* space in mmapped regions */
	106	size_t usmblks; /* always 0, preserved for backwards compatibility */
	107	size_t fsmblks; /* space available in freed fastbin blocks */
	108	size_t uordblks; /* total allocated space */
	109	size_t fordblks; /* total free space */
	110	size_t keepcost; /* top-most, releasable (via malloc_trim) space */
	111	};
	112
	113	/* Returns a copy of the updated current mallinfo. */
	114	extern struct mallinfo mallinfo (void) __THROW __MALLOC_DEPRECATED;
	115
	116	/* Returns a copy of the updated current mallinfo. */
	117	extern struct mallinfo2 mallinfo2 (void) __THROW;
	118
	119	/* SVID2/XPG mallopt options */
	120	#ifndef M_MXFAST
	121	# define M_MXFAST 1 /* maximum request size for "fastbins" */
	122	#endif
	123	#ifndef M_NLBLKS
	124	# define M_NLBLKS 2 /* UNUSED in this malloc */
	125	#endif
	126	#ifndef M_GRAIN
	127	# define M_GRAIN 3 /* UNUSED in this malloc */
	128	#endif
	129	#ifndef M_KEEP
	130	# define M_KEEP 4 /* UNUSED in this malloc */
	131	#endif
	132
	133	/* mallopt options that actually do something */
	134	#define M_TRIM_THRESHOLD -1
	135	#define M_TOP_PAD -2
	136	#define M_MMAP_THRESHOLD -3
	137	#define M_MMAP_MAX -4
	138	#define M_CHECK_ACTION -5
	139	#define M_PERTURB -6
	140	#define M_ARENA_TEST -7
	141	#define M_ARENA_MAX -8
	142
	143	/* General SVID/XPG interface to tunable parameters. */
	144	extern int mallopt (int __param, int __val) __THROW;
	145
	146	/* Release all but __pad bytes of freed top-most memory back to the
	147	system. Return 1 if successful, else 0. */
	148	extern int malloc_trim (size_t __pad) __THROW;
	149
	150	/* Report the number of usable allocated bytes associated with allocated
	151	chunk __ptr. */
	152	extern size_t malloc_usable_size (void *__ptr) __THROW;
	153
	154	/* Prints brief summary statistics on stderr. */
	155	extern void malloc_stats (void) __THROW;
	156
	157	/* Output information about state of allocator to stream FP. */
	158	extern int malloc_info (int __options, FILE *__fp) __THROW;
	159
	160	__END_DECLS
	161	#endif /* malloc.h */