1malloc_info(3) Library Functions Manual malloc_info(3)
2
6 malloc_info - export malloc state to a stream
7
9 Standard C library (libc, -lc)
10
12 #include <malloc.h>
13 int malloc_info(int options, FILE *stream);
15
17 The malloc_info() function exports an XML string that describes the
18 current state of the memory-allocation implementation in the caller.
19 The string is printed on the file stream stream. The exported string
20 includes information about all arenas (see malloc(3)).
21 As currently implemented, options must be zero.
23
25 On success, malloc_info() returns 0. On failure, it returns -1, and
26 errno is set to indicate the error.
27
29 EINVAL options was nonzero.
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 GNU.
43
45 glibc 2.10.
46
48 The memory-allocation information is provided as an XML string (rather
49 than a C structure) because the information may change over time (ac‐
50 cording to changes in the underlying implementation). The output XML
51 string includes a version field.
52 The open_memstream(3) function can be used to send the output of mal‐
54 loc_info() directly into a buffer in memory, rather than to a file.
55 The malloc_info() function is designed to address deficiencies in mal‐
57 loc_stats(3) and mallinfo(3).
58
60 The program below takes up to four command-line arguments, of which the
61 first three are mandatory. The first argument specifies the number of
62 threads that the program should create. All of the threads, including
63 the main thread, allocate the number of blocks of memory specified by
64 the second argument. The third argument controls the size of the
65 blocks to be allocated. The main thread creates blocks of this size,
66 the second thread created by the program allocates blocks of twice this
67 size, the third thread allocates blocks of three times this size, and
68 so on.
69 The program calls malloc_info() twice to display the memory-allocation
71 state. The first call takes place before any threads are created or
72 memory allocated. The second call is performed after all threads have
73 allocated memory.
74 In the following example, the command-line arguments specify the cre‐
76 ation of one additional thread, and both the main thread and the addi‐
77 tional thread allocate 10000 blocks of memory. After the blocks of
78 memory have been allocated, malloc_info() shows the state of two allo‐
79 cation arenas.
80 $ getconf GNU_LIBC_VERSION
82 glibc 2.13
83 $ ./a.out 1 10000 100
84 ============ Before allocating blocks ============
85 <malloc version="1">
86 <heap nr="0">
87 <sizes>
88 </sizes>
89 <total type="fast" count="0" size="0"/>
90 <total type="rest" count="0" size="0"/>
91 <system type="current" size="135168"/>
92 <system type="max" size="135168"/>
93 <aspace type="total" size="135168"/>
94 <aspace type="mprotect" size="135168"/>
95 </heap>
96 <total type="fast" count="0" size="0"/>
97 <total type="rest" count="0" size="0"/>
98 <system type="current" size="135168"/>
99 <system type="max" size="135168"/>
100 <aspace type="total" size="135168"/>
101 <aspace type="mprotect" size="135168"/>
102 </malloc>
103 ============ After allocating blocks ============
105 <malloc version="1">
106 <heap nr="0">
107 <sizes>
108 </sizes>
109 <total type="fast" count="0" size="0"/>
110 <total type="rest" count="0" size="0"/>
111 <system type="current" size="1081344"/>
112 <system type="max" size="1081344"/>
113 <aspace type="total" size="1081344"/>
114 <aspace type="mprotect" size="1081344"/>
115 </heap>
116 <heap nr="1">
117 <sizes>
118 </sizes>
119 <total type="fast" count="0" size="0"/>
120 <total type="rest" count="0" size="0"/>
121 <system type="current" size="1032192"/>
122 <system type="max" size="1032192"/>
123 <aspace type="total" size="1032192"/>
124 <aspace type="mprotect" size="1032192"/>
125 </heap>
126 <total type="fast" count="0" size="0"/>
127 <total type="rest" count="0" size="0"/>
128 <system type="current" size="2113536"/>
129 <system type="max" size="2113536"/>
130 <aspace type="total" size="2113536"/>
131 <aspace type="mprotect" size="2113536"/>
132 </malloc>
133 Program source
135 #include <err.h>
136 #include <errno.h>
137 #include <malloc.h>
138 #include <pthread.h>
139 #include <stdlib.h>
140 #include <unistd.h>
141 static size_t blockSize;
143 static size_t numThreads;
144 static unsigned int numBlocks;
145 static void *
147 thread_func(void *arg)
148 {
149 int tn = (int) arg;
150 /* The multiplier '(2 + tn)' ensures that each thread (including
152 the main thread) allocates a different amount of memory. */
153 for (unsigned int j = 0; j < numBlocks; j++)
155 if (malloc(blockSize * (2 + tn)) == NULL)
156 err(EXIT_FAILURE, "malloc-thread");
157 sleep(100); /* Sleep until main thread terminates. */
159 return NULL;
160 }
161 int
163 main(int argc, char *argv[])
164 {
165 int sleepTime;
166 pthread_t *thr;
167 if (argc < 4) {
169 fprintf(stderr,
170 "%s num-threads num-blocks block-size [sleep-time]\n",
171 argv[0]);
172 exit(EXIT_FAILURE);
173 }
174 numThreads = atoi(argv[1]);
176 numBlocks = atoi(argv[2]);
177 blockSize = atoi(argv[3]);
178 sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
179 thr = calloc(numThreads, sizeof(*thr));
181 if (thr == NULL)
182 err(EXIT_FAILURE, "calloc");
183 printf("============ Before allocating blocks ============\n");
185 malloc_info(0, stdout);
186 /* Create threads that allocate different amounts of memory. */
188 for (size_t tn = 0; tn < numThreads; tn++) {
190 errno = pthread_create(&thr[tn], NULL, thread_func,
191 (void *) tn);
192 if (errno != 0)
193 err(EXIT_FAILURE, "pthread_create");
194 /* If we add a sleep interval after the start-up of each
196 thread, the threads likely won't contend for malloc
197 mutexes, and therefore additional arenas won't be
198 allocated (see malloc(3)). */
199 if (sleepTime > 0)
201 sleep(sleepTime);
202 }
203 /* The main thread also allocates some memory. */
205 for (unsigned int j = 0; j < numBlocks; j++)
207 if (malloc(blockSize) == NULL)
208 err(EXIT_FAILURE, "malloc");
209 sleep(2); /* Give all threads a chance to
211 complete allocations. */
212 printf("\n============ After allocating blocks ============\n");
214 malloc_info(0, stdout);
215 exit(EXIT_SUCCESS);
217 }
218
220 mallinfo(3), malloc(3), malloc_stats(3), mallopt(3), open_memstream(3)
221Linux man-pages 6.04 2023-03-30 malloc_info(3)