1MALLOC_INFO(3)             Linux Programmer's Manual            MALLOC_INFO(3)
2
3
4

NAME

6       malloc_info - export malloc state to a stream
7

SYNOPSIS

9       #include <malloc.h>
10
11       int malloc_info(int options, FILE *stream);
12

DESCRIPTION

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
19       As currently implemented, options must be zero.
20

RETURN VALUE

22       On success, malloc_info() returns 0; on error, it returns -1, with  er‐
23       rno set to indicate the cause.
24

ERRORS

26       EINVAL options was nonzero.
27

VERSIONS

29       malloc_info() was added to glibc in version 2.10.
30

ATTRIBUTES

32       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
33       tributes(7).
34
35       ┌──────────────┬───────────────┬─────────┐
36Interface     Attribute     Value   
37       ├──────────────┼───────────────┼─────────┤
38malloc_info() │ Thread safety │ MT-Safe │
39       └──────────────┴───────────────┴─────────┘
40

CONFORMING TO

42       This function is a GNU extension.
43

NOTES

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
50       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
53       The malloc_info() function is designed to address deficiencies in  mal‐
54       loc_stats(3) and mallinfo(3).
55

EXAMPLES

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
67       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
72       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
78           $ 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
101           ============ 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
131   Program source
132       #include <unistd.h>
133       #include <stdlib.h>
134       #include <pthread.h>
135       #include <malloc.h>
136       #include <errno.h>
137
138       static size_t blockSize;
139       static int numThreads, numBlocks;
140
141       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
142                               } while (0)
143
144       static void *
145       thread_func(void *arg)
146       {
147           int tn = (int) arg;
148
149           /* The multiplier '(2 + tn)' ensures that each thread (including
150              the main thread) allocates a different amount of memory */
151
152           for (int j = 0; j < numBlocks; j++)
153               if (malloc(blockSize * (2 + tn)) == NULL)
154                   errExit("malloc-thread");
155
156           sleep(100);         /* Sleep until main thread terminates */
157           return NULL;
158       }
159
160       int
161       main(int argc, char *argv[])
162       {
163           int sleepTime;
164
165           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
172           numThreads = atoi(argv[1]);
173           numBlocks = atoi(argv[2]);
174           blockSize = atoi(argv[3]);
175           sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
176
177           pthread_t *thr = calloc(numThreads, sizeof(*thr));
178           if (thr == NULL)
179               errExit("calloc");
180
181           printf("============ Before allocating blocks ============\n");
182           malloc_info(0, stdout);
183
184           /* Create threads that allocate different amounts of memory */
185
186           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
192               /* 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
197               if (sleepTime > 0)
198                   sleep(sleepTime);
199           }
200
201           /* The main thread also allocates some memory */
202
203           for (int j = 0; j < numBlocks; j++)
204               if (malloc(blockSize) == NULL)
205                   errExit("malloc");
206
207           sleep(2);           /* Give all threads a chance to
208                                  complete allocations */
209
210           printf("\n============ After allocating blocks ============\n");
211           malloc_info(0, stdout);
212
213           exit(EXIT_SUCCESS);
214       }
215

SEE ALSO

217       mallinfo(3), malloc(3), malloc_stats(3), mallopt(3), open_memstream(3)
218

COLOPHON

220       This page is part of release 5.10 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/.
224
225
226
227GNU                               2020-11-01                    MALLOC_INFO(3)
Impressum