summaryrefslogtreecommitdiffstats
path: root/man3/mallinfo.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/mallinfo.3')
-rw-r--r--man3/mallinfo.3338
1 files changed, 338 insertions, 0 deletions
diff --git a/man3/mallinfo.3 b/man3/mallinfo.3
new file mode 100644
index 0000000..af08137
--- /dev/null
+++ b/man3/mallinfo.3
@@ -0,0 +1,338 @@
+'\" t
+.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mallinfo 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+mallinfo, mallinfo2 \- obtain memory allocation information
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.PP
+.B struct mallinfo mallinfo(void);
+.B struct mallinfo2 mallinfo2(void);
+.fi
+.SH DESCRIPTION
+These functions return a copy of a structure containing information about
+memory allocations performed by
+.BR malloc (3)
+and related functions.
+The structure returned by each function contains the same fields.
+However, the older function,
+.BR mallinfo (),
+is deprecated since the type used for the fields is too small (see BUGS).
+.PP
+Note that not all allocations are visible to these functions;
+see BUGS and consider using
+.BR malloc_info (3)
+instead.
+.PP
+The
+.I mallinfo2
+structure returned by
+.BR mallinfo2 ()
+is defined as follows:
+.PP
+.in +4n
+.EX
+struct mallinfo2 {
+ size_t arena; /* Non\-mmapped space allocated (bytes) */
+ size_t ordblks; /* Number of free chunks */
+ size_t smblks; /* Number of free fastbin blocks */
+ size_t hblks; /* Number of mmapped regions */
+ size_t hblkhd; /* Space allocated in mmapped regions
+ (bytes) */
+ size_t usmblks; /* See below */
+ size_t fsmblks; /* Space in freed fastbin blocks (bytes) */
+ size_t uordblks; /* Total allocated space (bytes) */
+ size_t fordblks; /* Total free space (bytes) */
+ size_t keepcost; /* Top\-most, releasable space (bytes) */
+};
+.EE
+.in
+.PP
+The
+.I mallinfo
+structure returned by the deprecated
+.BR mallinfo ()
+function is exactly the same, except that the fields are typed as
+.IR int .
+.PP
+The structure fields contain the following information:
+.TP 10
+.I arena
+The total amount of memory allocated by means other than
+.BR mmap (2)
+(i.e., memory allocated on the heap).
+This figure includes both in-use blocks and blocks on the free list.
+.TP
+.I ordblks
+The number of ordinary (i.e., non-fastbin) free blocks.
+.TP
+.I smblks
+.\" the glibc info page wrongly says this field is unused
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746
+The number of fastbin free blocks (see
+.BR mallopt (3)).
+.TP
+.I hblks
+The number of blocks currently allocated using
+.BR mmap (2).
+(See the discussion of
+.B M_MMAP_THRESHOLD
+in
+.BR mallopt (3).)
+.TP
+.I hblkhd
+The number of bytes in blocks currently allocated using
+.BR mmap (2).
+.TP
+.I usmblks
+This field is unused, and is always 0.
+.\" It seems to have been zero since at least as far back as glibc 2.15
+Historically, it was the "highwater mark" for allocated space\[em]that is,
+the maximum amount of space that was ever allocated (in bytes);
+this field was maintained only in nonthreading environments.
+.TP
+.I fsmblks
+.\" the glibc info page wrongly says this field is unused
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746
+The total number of bytes in fastbin free blocks.
+.TP
+.I uordblks
+The total number of bytes used by in-use allocations.
+.TP
+.I fordblks
+The total number of bytes in free blocks.
+.TP
+.I keepcost
+The total amount of releasable free space at the top
+of the heap.
+This is the maximum number of bytes that could ideally
+(i.e., ignoring page alignment restrictions, and so on) be released by
+.BR malloc_trim (3).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lbx
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR mallinfo (),
+.BR mallinfo2 ()
+T} Thread safety T{
+.na
+.nh
+MT-Unsafe init const:mallopt
+T}
+.TE
+.sp 1
+.BR mallinfo ()/
+.BR mallinfo2 ()
+would access some global internal objects.
+If modify them with non-atomically,
+may get inconsistent results.
+The identifier
+.I mallopt
+in
+.I const:mallopt
+mean that
+.BR mallopt ()
+would modify the global internal objects with atomics, that make sure
+.BR mallinfo ()/
+.BR mallinfo2 ()
+is safe enough, others modify with non-atomically maybe not.
+.SH STANDARDS
+None.
+.SH HISTORY
+.TP
+.BR mallinfo ()
+glibc 2.0.
+SVID.
+.TP
+.BR mallinfo2 ()
+.\" commit e3960d1c57e57f33e0e846d615788f4ede73b945
+glibc 2.33.
+.SH BUGS
+.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208
+.\" See the 24 Aug 2011 mail by Paul Pluzhnikov:
+.\" "[patch] Fix mallinfo() to accumulate results for all arenas"
+.\" on libc-alpha@sourceware.org
+.B Information is returned for only the main memory allocation area.
+Allocations in other arenas are excluded.
+See
+.BR malloc_stats (3)
+and
+.BR malloc_info (3)
+for alternatives that include information about other arenas.
+.PP
+The fields of the
+.I mallinfo
+structure that is returned by the older
+.BR mallinfo ()
+function are typed as
+.IR int .
+However, because some internal bookkeeping values may be of type
+.IR long ,
+the reported values may wrap around zero and thus be inaccurate.
+.SH EXAMPLES
+The program below employs
+.BR mallinfo2 ()
+to retrieve memory allocation statistics before and after
+allocating and freeing some blocks of memory.
+The statistics are displayed on standard output.
+.PP
+The first two command-line arguments specify the number and size of
+blocks to be allocated with
+.BR malloc (3).
+.PP
+The remaining three arguments specify which of the allocated blocks
+should be freed with
+.BR free (3).
+These three arguments are optional, and specify (in order):
+the step size to be used in the loop that frees blocks
+(the default is 1, meaning free all blocks in the range);
+the ordinal position of the first block to be freed
+(default 0, meaning the first allocated block);
+and a number one greater than the ordinal position
+of the last block to be freed
+(default is one greater than the maximum block number).
+If these three arguments are omitted,
+then the defaults cause all allocated blocks to be freed.
+.PP
+In the following example run of the program,
+1000 allocations of 100 bytes are performed,
+and then every second allocated block is freed:
+.PP
+.in +4n
+.EX
+$ \fB./a.out 1000 100 2\fP
+============== Before allocating blocks ==============
+Total non\-mmapped bytes (arena): 0
+# of free chunks (ordblks): 1
+# of free fastbin blocks (smblks): 0
+# of mapped regions (hblks): 0
+Bytes in mapped regions (hblkhd): 0
+Max. total allocated space (usmblks): 0
+Free bytes held in fastbins (fsmblks): 0
+Total allocated space (uordblks): 0
+Total free space (fordblks): 0
+Topmost releasable block (keepcost): 0
+\&
+============== After allocating blocks ==============
+Total non\-mmapped bytes (arena): 135168
+# of free chunks (ordblks): 1
+# of free fastbin blocks (smblks): 0
+# of mapped regions (hblks): 0
+Bytes in mapped regions (hblkhd): 0
+Max. total allocated space (usmblks): 0
+Free bytes held in fastbins (fsmblks): 0
+Total allocated space (uordblks): 104000
+Total free space (fordblks): 31168
+Topmost releasable block (keepcost): 31168
+\&
+============== After freeing blocks ==============
+Total non\-mmapped bytes (arena): 135168
+# of free chunks (ordblks): 501
+# of free fastbin blocks (smblks): 0
+# of mapped regions (hblks): 0
+Bytes in mapped regions (hblkhd): 0
+Max. total allocated space (usmblks): 0
+Free bytes held in fastbins (fsmblks): 0
+Total allocated space (uordblks): 52000
+Total free space (fordblks): 83168
+Topmost releasable block (keepcost): 31168
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (mallinfo.c)
+.EX
+#include <malloc.h>
+#include <stdlib.h>
+#include <string.h>
+\&
+static void
+display_mallinfo2(void)
+{
+ struct mallinfo2 mi;
+\&
+ mi = mallinfo2();
+\&
+ printf("Total non\-mmapped bytes (arena): %zu\en", mi.arena);
+ printf("# of free chunks (ordblks): %zu\en", mi.ordblks);
+ printf("# of free fastbin blocks (smblks): %zu\en", mi.smblks);
+ printf("# of mapped regions (hblks): %zu\en", mi.hblks);
+ printf("Bytes in mapped regions (hblkhd): %zu\en", mi.hblkhd);
+ printf("Max. total allocated space (usmblks): %zu\en", mi.usmblks);
+ printf("Free bytes held in fastbins (fsmblks): %zu\en", mi.fsmblks);
+ printf("Total allocated space (uordblks): %zu\en", mi.uordblks);
+ printf("Total free space (fordblks): %zu\en", mi.fordblks);
+ printf("Topmost releasable block (keepcost): %zu\en", mi.keepcost);
+}
+\&
+int
+main(int argc, char *argv[])
+{
+#define MAX_ALLOCS 2000000
+ char *alloc[MAX_ALLOCS];
+ size_t blockSize, numBlocks, freeBegin, freeEnd, freeStep;
+\&
+ if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) {
+ fprintf(stderr, "%s num\-blocks block\-size [free\-step "
+ "[start\-free [end\-free]]]\en", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+\&
+ numBlocks = atoi(argv[1]);
+ blockSize = atoi(argv[2]);
+ freeStep = (argc > 3) ? atoi(argv[3]) : 1;
+ freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
+ freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;
+\&
+ printf("============== Before allocating blocks ==============\en");
+ display_mallinfo2();
+\&
+ for (size_t j = 0; j < numBlocks; j++) {
+ if (numBlocks >= MAX_ALLOCS) {
+ fprintf(stderr, "Too many allocations\en");
+ exit(EXIT_FAILURE);
+ }
+\&
+ alloc[j] = malloc(blockSize);
+ if (alloc[j] == NULL) {
+ perror("malloc");
+ exit(EXIT_FAILURE);
+ }
+ }
+\&
+ printf("\en============== After allocating blocks ==============\en");
+ display_mallinfo2();
+\&
+ for (size_t j = freeBegin; j < freeEnd; j += freeStep)
+ free(alloc[j]);
+\&
+ printf("\en============== After freeing blocks ==============\en");
+ display_mallinfo2();
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.ad l
+.nh
+.BR mmap (2),
+.BR malloc (3),
+.BR malloc_info (3),
+.BR malloc_stats (3),
+.BR malloc_trim (3),
+.BR mallopt (3)