1MALLOC_INFO(3) Linux Programmer's Manual MALLOC_INFO(3)
2
6 malloc_info - export malloc state to a stream
7
9 #include <malloc.h>
10 int malloc_info(int options, FILE *stream);
12
14 The malloc_info() function exports an XML string that describes the
15 current state of the memory-allocation implementation in the caller.
16 The string is printed on the file stream stream. The exported string
17 includes information about all arenas (see malloc(3)).
18 As currently implemented, options must be zero.
20
22 On success, malloc_info() returns 0. On failure, it returns -1, and
23 errno is set to indicate the error.
24
26 EINVAL options was nonzero.
27
29 malloc_info() was added to glibc in version 2.10.
30
32 For an explanation of the terms used in this section, see at‐
33 tributes(7).
34 ┌────────────────────────────────────────────┬───────────────┬─────────┐
36 │Interface │ Attribute │ Value │
37 ├────────────────────────────────────────────┼───────────────┼─────────┤
38 │malloc_info() │ Thread safety │ MT-Safe │
39 └────────────────────────────────────────────┴───────────────┴─────────┘
40
42 This function is a GNU extension.
43
45 The memory-allocation information is provided as an XML string (rather
46 than a C structure) because the information may change over time (ac‐
47 cording to changes in the underlying implementation). The output XML
48 string includes a version field.
49 The open_memstream(3) function can be used to send the output of mal‐
51 loc_info() directly into a buffer in memory, rather than to a file.
52 The malloc_info() function is designed to address deficiencies in mal‐
54 loc_stats(3) and mallinfo(3).
55
57 The program below takes up to four command-line arguments, of which the
58 first three are mandatory. The first argument specifies the number of
59 threads that the program should create. All of the threads, including
60 the main thread, allocate the number of blocks of memory specified by
61 the second argument. The third argument controls the size of the
62 blocks to be allocated. The main thread creates blocks of this size,
63 the second thread created by the program allocates blocks of twice this
64 size, the third thread allocates blocks of three times this size, and
65 so on.
66 The program calls malloc_info() twice to display the memory-allocation
68 state. The first call takes place before any threads are created or
69 memory allocated. The second call is performed after all threads have
70 allocated memory.
71 In the following example, the command-line arguments specify the cre‐
73 ation of one additional thread, and both the main thread and the addi‐
74 tional thread allocate 10000 blocks of memory. After the blocks of
75 memory have been allocated, malloc_info() shows the state of two allo‐
76 cation arenas.
77 $ getconf GNU_LIBC_VERSION
79 glibc 2.13
80 $ ./a.out 1 10000 100
81 ============ Before allocating blocks ============
82 <malloc version="1">
83 <heap nr="0">
84 <sizes>
85 </sizes>
86 <total type="fast" count="0" size="0"/>
87 <total type="rest" count="0" size="0"/>
88 <system type="current" size="135168"/>
89 <system type="max" size="135168"/>
90 <aspace type="total" size="135168"/>
91 <aspace type="mprotect" size="135168"/>
92 </heap>
93 <total type="fast" count="0" size="0"/>
94 <total type="rest" count="0" size="0"/>
95 <system type="current" size="135168"/>
96 <system type="max" size="135168"/>
97 <aspace type="total" size="135168"/>
98 <aspace type="mprotect" size="135168"/>
99 </malloc>
100 ============ After allocating blocks ============
102 <malloc version="1">
103 <heap nr="0">
104 <sizes>
105 </sizes>
106 <total type="fast" count="0" size="0"/>
107 <total type="rest" count="0" size="0"/>
108 <system type="current" size="1081344"/>
109 <system type="max" size="1081344"/>
110 <aspace type="total" size="1081344"/>
111 <aspace type="mprotect" size="1081344"/>
112 </heap>
113 <heap nr="1">
114 <sizes>
115 </sizes>
116 <total type="fast" count="0" size="0"/>
117 <total type="rest" count="0" size="0"/>
118 <system type="current" size="1032192"/>
119 <system type="max" size="1032192"/>
120 <aspace type="total" size="1032192"/>
121 <aspace type="mprotect" size="1032192"/>
122 </heap>
123 <total type="fast" count="0" size="0"/>
124 <total type="rest" count="0" size="0"/>
125 <system type="current" size="2113536"/>
126 <system type="max" size="2113536"/>
127 <aspace type="total" size="2113536"/>
128 <aspace type="mprotect" size="2113536"/>
129 </malloc>
130 Program source
132 #include <unistd.h>
133 #include <stdlib.h>
134 #include <pthread.h>
135 #include <malloc.h>
136 #include <errno.h>
137 static size_t blockSize;
139 static int numThreads, numBlocks;
140 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
142 } while (0)
143 static void *
145 thread_func(void *arg)
146 {
147 int tn = (int) arg;
148 /* The multiplier '(2 + tn)' ensures that each thread (including
150 the main thread) allocates a different amount of memory. */
151 for (int j = 0; j < numBlocks; j++)
153 if (malloc(blockSize * (2 + tn)) == NULL)
154 errExit("malloc-thread");
155 sleep(100); /* Sleep until main thread terminates. */
157 return NULL;
158 }
159 int
161 main(int argc, char *argv[])
162 {
163 int sleepTime;
164 if (argc < 4) {
166 fprintf(stderr,
167 "%s num-threads num-blocks block-size [sleep-time]\n",
168 argv[0]);
169 exit(EXIT_FAILURE);
170 }
171 numThreads = atoi(argv[1]);
173 numBlocks = atoi(argv[2]);
174 blockSize = atoi(argv[3]);
175 sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
176 pthread_t *thr = calloc(numThreads, sizeof(*thr));
178 if (thr == NULL)
179 errExit("calloc");
180 printf("============ Before allocating blocks ============\n");
182 malloc_info(0, stdout);
183 /* Create threads that allocate different amounts of memory. */
185 for (int tn = 0; tn < numThreads; tn++) {
187 errno = pthread_create(&thr[tn], NULL, thread_func,
188 (void *) tn);
189 if (errno != 0)
190 errExit("pthread_create");
191 /* If we add a sleep interval after the start-up of each
193 thread, the threads likely won't contend for malloc
194 mutexes, and therefore additional arenas won't be
195 allocated (see malloc(3)). */
196 if (sleepTime > 0)
198 sleep(sleepTime);
199 }
200 /* The main thread also allocates some memory. */
202 for (int j = 0; j < numBlocks; j++)
204 if (malloc(blockSize) == NULL)
205 errExit("malloc");
206 sleep(2); /* Give all threads a chance to
208 complete allocations. */
209 printf("\n============ After allocating blocks ============\n");
211 malloc_info(0, stdout);
212 exit(EXIT_SUCCESS);
214 }
215
217 mallinfo(3), malloc(3), malloc_stats(3), mallopt(3), open_memstream(3)
218
220 This page is part of release 5.12 of the Linux man-pages project. A
221 description of the project, information about reporting bugs, and the
222 latest version of this page, can be found at
223 https://www.kernel.org/doc/man-pages/.
224GNU 2021-03-22 MALLOC_INFO(3)