diff options
Diffstat (limited to 'man/man3/malloc_info.3')
| -rw-r--r-- | man/man3/malloc_info.3 | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/man/man3/malloc_info.3 b/man/man3/malloc_info.3 new file mode 100644 index 000000000..0aa55ba67 --- /dev/null +++ b/man/man3/malloc_info.3 @@ -0,0 +1,257 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_info 3 (date) "Linux man-pages (unreleased)" +.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> +.P +.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)). +.P +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 +.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. +.P +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. +.P +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. +.P +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. +.P +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. +.P +.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) |