summaryrefslogtreecommitdiffstats
path: root/man3/malloc_info.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/malloc_info.3')
-rw-r--r--man3/malloc_info.3258
1 files changed, 258 insertions, 0 deletions
diff --git a/man3/malloc_info.3 b/man3/malloc_info.3
new file mode 100644
index 0000000..045430b
--- /dev/null
+++ b/man3/malloc_info.3
@@ -0,0 +1,258 @@
+'\" t
+.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH malloc_info 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+malloc_info \- export malloc state to a stream
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.PP
+.BI "int malloc_info(int " options ", FILE *" stream );
+.fi
+.SH DESCRIPTION
+The
+.BR malloc_info ()
+function exports an XML string that describes the current state
+of the memory-allocation
+implementation in the caller.
+The string is printed on the file stream
+.IR stream .
+The exported string includes information about all arenas (see
+.BR malloc (3)).
+.PP
+As currently implemented,
+.I options
+must be zero.
+.SH RETURN VALUE
+On success,
+.BR malloc_info ()
+returns 0.
+On failure, it returns \-1, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I options
+was nonzero.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR malloc_info ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+GNU.
+.SH HISTORY
+glibc 2.10.
+.SH NOTES
+The memory-allocation information is provided as an XML string
+(rather than a C structure)
+because the information may change over time
+(according to changes in the underlying implementation).
+The output XML string includes a version field.
+.PP
+The
+.BR open_memstream (3)
+function can be used to send the output of
+.BR malloc_info ()
+directly into a buffer in memory, rather than to a file.
+.PP
+The
+.BR malloc_info ()
+function is designed to address deficiencies in
+.BR malloc_stats (3)
+and
+.BR mallinfo (3).
+.SH EXAMPLES
+The program below takes up to four command-line arguments,
+of which the first three are mandatory.
+The first argument specifies the number of threads that
+the program should create.
+All of the threads, including the main thread,
+allocate the number of blocks of memory specified by the second argument.
+The third argument controls the size of the blocks to be allocated.
+The main thread creates blocks of this size,
+the second thread created by the program allocates blocks of twice this size,
+the third thread allocates blocks of three times this size, and so on.
+.PP
+The program calls
+.BR malloc_info ()
+twice to display the memory-allocation state.
+The first call takes place before any threads
+are created or memory allocated.
+The second call is performed after all threads have allocated memory.
+.PP
+In the following example,
+the command-line arguments specify the creation of one additional thread,
+and both the main thread and the additional thread
+allocate 10000 blocks of memory.
+After the blocks of memory have been allocated,
+.BR malloc_info ()
+shows the state of two allocation arenas.
+.PP
+.in +4n
+.EX
+.RB "$ " "getconf GNU_LIBC_VERSION"
+glibc 2.13
+.RB "$ " "./a.out 1 10000 100"
+============ Before allocating blocks ============
+<malloc version="1">
+<heap nr="0">
+<sizes>
+</sizes>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="135168"/>
+<system type="max" size="135168"/>
+<aspace type="total" size="135168"/>
+<aspace type="mprotect" size="135168"/>
+</heap>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="135168"/>
+<system type="max" size="135168"/>
+<aspace type="total" size="135168"/>
+<aspace type="mprotect" size="135168"/>
+</malloc>
+\&
+============ After allocating blocks ============
+<malloc version="1">
+<heap nr="0">
+<sizes>
+</sizes>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="1081344"/>
+<system type="max" size="1081344"/>
+<aspace type="total" size="1081344"/>
+<aspace type="mprotect" size="1081344"/>
+</heap>
+<heap nr="1">
+<sizes>
+</sizes>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="1032192"/>
+<system type="max" size="1032192"/>
+<aspace type="total" size="1032192"/>
+<aspace type="mprotect" size="1032192"/>
+</heap>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="2113536"/>
+<system type="max" size="2113536"/>
+<aspace type="total" size="2113536"/>
+<aspace type="mprotect" size="2113536"/>
+</malloc>
+.EE
+.in
+.SS Program source
+.\" SRC BEGIN (malloc_info.c)
+.EX
+#include <err.h>
+#include <errno.h>
+#include <malloc.h>
+#include <pthread.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+static size_t blockSize;
+static size_t numThreads;
+static unsigned int numBlocks;
+\&
+static void *
+thread_func(void *arg)
+{
+ int tn = (int) arg;
+\&
+ /* The multiplier \[aq](2 + tn)\[aq] ensures that each thread (including
+ the main thread) allocates a different amount of memory. */
+\&
+ for (unsigned int j = 0; j < numBlocks; j++)
+ if (malloc(blockSize * (2 + tn)) == NULL)
+ err(EXIT_FAILURE, "malloc\-thread");
+\&
+ sleep(100); /* Sleep until main thread terminates. */
+ return NULL;
+}
+\&
+int
+main(int argc, char *argv[])
+{
+ int sleepTime;
+ pthread_t *thr;
+\&
+ if (argc < 4) {
+ fprintf(stderr,
+ "%s num\-threads num\-blocks block\-size [sleep\-time]\en",
+ argv[0]);
+ exit(EXIT_FAILURE);
+ }
+\&
+ numThreads = atoi(argv[1]);
+ numBlocks = atoi(argv[2]);
+ blockSize = atoi(argv[3]);
+ sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
+\&
+ thr = calloc(numThreads, sizeof(*thr));
+ if (thr == NULL)
+ err(EXIT_FAILURE, "calloc");
+\&
+ printf("============ Before allocating blocks ============\en");
+ malloc_info(0, stdout);
+\&
+ /* Create threads that allocate different amounts of memory. */
+\&
+ for (size_t tn = 0; tn < numThreads; tn++) {
+ errno = pthread_create(&thr[tn], NULL, thread_func,
+ (void *) tn);
+ if (errno != 0)
+ err(EXIT_FAILURE, "pthread_create");
+\&
+ /* If we add a sleep interval after the start\-up of each
+ thread, the threads likely won\[aq]t contend for malloc
+ mutexes, and therefore additional arenas won\[aq]t be
+ allocated (see malloc(3)). */
+\&
+ if (sleepTime > 0)
+ sleep(sleepTime);
+ }
+\&
+ /* The main thread also allocates some memory. */
+\&
+ for (unsigned int j = 0; j < numBlocks; j++)
+ if (malloc(blockSize) == NULL)
+ err(EXIT_FAILURE, "malloc");
+\&
+ sleep(2); /* Give all threads a chance to
+ complete allocations. */
+\&
+ printf("\en============ After allocating blocks ============\en");
+ malloc_info(0, stdout);
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR mallinfo (3),
+.BR malloc (3),
+.BR malloc_stats (3),
+.BR mallopt (3),
+.BR open_memstream (3)