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
23       errno 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
33       attributes(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
47       (according to changes in the underlying  implementation).   The  output
48       XML 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

EXAMPLE

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 j;
148           int tn = (int) arg;
149
150           /* The multiplier '(2 + tn)' ensures that each thread (including
151              the main thread) allocates a different amount of memory */
152
153           for (j = 0; j < numBlocks; j++)
154               if (malloc(blockSize * (2 + tn)) == NULL)
155                   errExit("malloc-thread");
156
157           sleep(100);         /* Sleep until main thread terminates */
158           return NULL;
159       }
160
161       int
162       main(int argc, char *argv[])
163       {
164           int j, tn, sleepTime;
165           pthread_t *thr;
166
167           if (argc < 4) {
168               fprintf(stderr,
169                       "%s num-threads num-blocks block-size [sleep-time]\n",
170                       argv[0]);
171               exit(EXIT_FAILURE);
172           }
173
174           numThreads = atoi(argv[1]);
175           numBlocks = atoi(argv[2]);
176           blockSize = atoi(argv[3]);
177           sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
178
179           thr = calloc(numThreads, sizeof(pthread_t));
180           if (thr == NULL)
181               errExit("calloc");
182
183           printf("============ Before allocating blocks ============\n");
184           malloc_info(0, stdout);
185
186           /* Create threads that allocate different amounts of memory */
187
188           for (tn = 0; tn < numThreads; tn++) {
189               errno = pthread_create(&thr[tn], NULL, thread_func,
190                                      (void *) tn);
191               if (errno != 0)
192                   errExit("pthread_create");
193
194               /* If we add a sleep interval after the start-up of each
195                  thread, the threads likely won't contend for malloc
196                  mutexes, and therefore additional arenas won't be
197                  allocated (see malloc(3)). */
198
199               if (sleepTime > 0)
200                   sleep(sleepTime);
201           }
202
203           /* The main thread also allocates some memory */
204
205           for (j = 0; j < numBlocks; j++)
206               if (malloc(blockSize) == NULL)
207                   errExit("malloc");
208
209           sleep(2);           /* Give all threads a chance to
210                                  complete allocations */
211
212           printf("\n============ After allocating blocks ============\n");
213           malloc_info(0, stdout);
214
215           exit(EXIT_SUCCESS);
216       }
217

SEE ALSO

219       mallinfo(3), malloc(3), malloc_stats(3), mallopt(3), open_memstream(3)
220

COLOPHON

222       This page is part of release 4.15 of the Linux  man-pages  project.   A
223       description  of  the project, information about reporting bugs, and the
224       latest    version    of    this    page,    can     be     found     at
225       https://www.kernel.org/doc/man-pages/.
226
227
228
229GNU                               2017-09-15                    MALLOC_INFO(3)
Impressum